WASM Sandbox

The WASM sandbox provides isolated tool execution with configurable resource limits. Tools run as WASM modules inside a Wasmtime runtime with fuel metering, memory caps, and optional WASI access.

Source: crates/clawft-kernel/src/wasm_runner.rs (~1,639 lines) Feature: wasm-sandbox

WasmToolRunner

pub struct WasmToolRunner {
    config: WasmSandboxConfig,
}

Executes WASM modules with fuel metering (each instruction consumes fuel), memory limits via ResourceLimiter, and configurable timeout.

WasmSandboxConfig

pub struct WasmSandboxConfig {
    pub fuel_limit: u64,
    pub memory_limit_bytes: u64,
    pub timeout_ms: u64,
    pub wasi_enabled: bool,
    pub wasi_fs_scope: WasiFsScope,
}

pub enum WasiFsScope {
    None,
    ReadOnly(Vec<PathBuf>),
    ReadWrite(Vec<PathBuf>),
}

Tool Catalog (27 Built-in Tools)

Each tool has a BuiltinToolSpec with an EffectVector for governance scoring.

Tool Lifecycle

Build -> Deploy -> Execute -> Version -> Revoke

All phases are chain-logged when exochain is enabled.

Host Isolation

By default, WASM modules have no access to filesystem, network, environment variables, or system clock unless explicitly configured via WasiFsScope.

Extended Tool Catalog (Sprint 10)

10 additional tools in tools_extended.rs:

Stateless tools are registered via register_stateless_tools(). Tools requiring kernel services (metrics, kv, health) use register_extended_tools() with injected Arc references.

Tool Signing (D9)

Ed25519 signing for tool provenance and integrity verification.

pub struct ToolSignature {
    pub tool_hash: String,      // SHA-256 of tool module bytes
    pub signer_id: String,      // Identity of the signer
    pub signature: Vec<u8>,     // Ed25519 signature
}

Signature Verification

// Register a signed tool
registry.register_signed("my-tool", module_bytes, signature)?;

// Enforce signature requirement
registry.set_require_signatures(true);

// Manage trusted keys
registry.add_trusted_key(public_key);

When require_signatures is enabled, unsigned tools are rejected at registration. Each signature is verified against all trusted keys.

Chain constant: EVENT_KIND_TOOL_SIGNED logs signing events to ExoChain.

WASM Shell Execution (D10)

Shell commands compiled to WASM for sandboxed execution:

pub struct ShellCommand {
    pub command: String,
    pub args: Vec<String>,
}

pub struct ShellResult {
    pub exit_code: i32,
    pub stdout: String,
    pub stderr: String,
    pub duration_ms: u64,
}

execute_shell() dispatches to built-in commands (echo, true, false) within the sandbox. Wall-clock timing is recorded. The shell.exec tool is registered in the builtin catalog.

Chain constant: EVENT_KIND_SHELL_EXEC logs shell executions to ExoChain.

CompiledModuleCache

LRU cache of compiled WASM modules keyed by content hash to avoid repeated compilation.