Expand description
Embedded wasmtime host for sandboxing untrusted wasm guests behind capability profiles.
This crate is a GENERIC capability-sandbox host: it loads an arbitrary wasm guest module and runs it under wasmtime with a deny-by-default capability surface plus DoS bounds. Two profiles are provided:
- Profile A (
Sandbox, this module): a bespokeLinkerthat exposes exactly the host functions we choose —env::host_randomplus the Subject-scopedenv::vfs_*capabilities (seevfs) — and wires EVERY other declared import to a trap viadefine_unknown_imports_as_traps. Nowasmtime-wasi, no preopens, no syscall surface: a guest that reaches for any un-granted host function traps.Sandbox::call_exportdrives an arbitrary guest export over the guest’salloc/memoryABI; language profiles (e.g. thehyprstream-workers-pythoncrate’seval/shell) build on top of it. This crate is LANGUAGE-AGNOSTIC: it carries no Python (or other language) awareness. - Profile B (
wasi_sandbox::WasiSandbox): a real WASI preview1 surface whose ONLY filesystem is a Subject-scoped [hyprstream_vfs::Mount] — no host preopen, clocks/random/sockets/sched withheld.
Capabilities are Subject-scoped BY CONSTRUCTION: the per-call SandboxState
carries the Subject the call runs as, and host functions read it out of the
Store rather than trusting any guest-supplied identity. There is no
global/thread-local identity state.
DoS guards on the Store (wasmtime 46.0.1 spellings):
- fuel (
Config::consume_fuel(true)+Store::set_fuel(u64)) - epoch (
Config::epoch_interruption(true)+Store::set_epoch_deadline(u64)Engine::increment_epoch())
wasmtime 46 ships its own error type (wasmtime::Error / wasmtime::Result, not
anyhow::Error) with an inherent wasmtime::Context trait; this crate uses those.
Modules§
- vfs
- VFS capability backing for the sandbox (#483 P2 — REAL, not a sketch).
- wasi_fs
- Profile B (#506): preview1
WasiDir/WasiFilebacked by a Subject-scopedhyprstream_vfs::Mount. - wasi_
sandbox - Profile B (#506): a WASI (
wasm32-wasip1) sandbox whose ENTIRE filesystem is a Subject-scoped [hyprstream_vfs::Mount] — and nothing else.
Structs§
- Epoch
Timer - A background thread that advances an [
Engine]’s epoch at a fixed cadence. - Persistent
Instance - A persistent guest instance over a single
Sandbox, driving the generic packed-op ABI. - Sandbox
- A loaded, ready-to-run sandbox over a single guest module, bound to one
Subject. - Sandbox
State - Per-call host state carried in the wasmtime
Storedata. - Subject
- The identity a sandbox evaluation runs as.
Constants§
- TAG_OK
- Status tag for an “ok” reply in the first byte of a host-serialised guest reply
buffer (the
vfs_*and packed-op ABIs share this convention: 0 = ok). Used bySandbox::probe_vfsand the genericPersistentInstancepacked-op decoder. Public so language profile crates (e.g.hyprstream-workers-python) can match the shared ABI tag without redefining it.
Functions§
- build_
engine - Build the wasmtime
Enginewith both DoS guards enabled. - build_
linker - Construct the bespoke Linker exposing ONLY
env::host_random.