2.0 KiB
@toolctrl/plugin-runtime
Phase 06 Task #21 foundation — host-side runtime for WebAssembly plugins.
Runtime is staging/foundation only until external WASM sandbox security signoff; do not treat third-party plugin execution as production-enabled yet.
Scope
- Manifest schema (Zod) with capability declarations
- Ed25519 signature verification against a trusted-keys allowlist
- WebAssembly sandbox wrapper on Node 22's built-in
WebAssembly, with memory-page caps and host-function fuel charging - Capability gateway: deny-by-default host-function access
- Hook registry/fanout contracts for the foundation hook set
- Crash tracker, audit helpers, migrations guardrails, and lifecycle integration helpers
Deferred
See ../../docs/features/plugins.md and ../../docs/architecture/plugin-hooks.md for
current status. Still-deferred runtime work:
- Hot-reload (operator restarts pod)
- Marketplace integration (#24 backlog)
- Additional hook points beyond the registered foundation set
- Higher-risk host bindings (
http.outbound,secret.read,db.read,db.write) until security review/tests are complete - Plugin secret storage and encrypted settings bindings
- Live debugging in plugin-dev mode
Runtime choice
Default: Node's built-in WebAssembly (V8) with memory-page limits and host-function fuel charging; per-instruction fuel remains deferred.
Rationale: native Wasmtime bindings for Node (@bytecodealliance/jco, @bytecodealliance/preview2-shim) are still pre-1.0 and add a ~40 MB build asset. For the foundation we ship a portable wrapper around Node 22's WebAssembly runtime — sufficient for memory limits (WebAssembly.Memory max-page bounds) and an instruction-budget gate via host-fn fuel charging on each capability call.
Fallback / upgrade path: Wasmer (@wasmer/sdk) is API-compatible with the wrapper's contract and can be swapped in if we need richer per-instruction fuel. Wasmtime via jco becomes the production choice once the Component-Model is GA on Node. This is documented in docs/architecture/plugin-system.md.