Skip to main content

Crate hyprstream_workers_wasmtime

Crate hyprstream_workers_wasmtime 

Source
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 bespoke Linker that exposes exactly the host functions we choose — env::host_random plus the Subject-scoped env::vfs_* capabilities (see vfs) — and wires EVERY other declared import to a trap via define_unknown_imports_as_traps. No wasmtime-wasi, no preopens, no syscall surface: a guest that reaches for any un-granted host function traps. Sandbox::call_export drives an arbitrary guest export over the guest’s alloc/memory ABI; language profiles (e.g. the hyprstream-workers-python crate’s eval/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/WasiFile backed by a Subject-scoped hyprstream_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§

EpochTimer
A background thread that advances an [Engine]’s epoch at a fixed cadence.
PersistentInstance
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.
SandboxState
Per-call host state carried in the wasmtime Store data.
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 by Sandbox::probe_vfs and the generic PersistentInstance packed-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 Engine with both DoS guards enabled.
build_linker
Construct the bespoke Linker exposing ONLY env::host_random.