35 lines
2.0 KiB
Markdown
35 lines
2.0 KiB
Markdown
# @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`.
|