# WASM-Sandbox + Plugin-SDK + Manifest + Signing + Capabilities + Resource-Limits **Status:** in_progress (foundation-shipped, hot-reload + marketplace + per-instruction-fuel + worker-thread-pool deferred) **Task-ID:** #21 **Phase:** 06 **Estimated Effort:** 4-5 Wochen **Owner:** unassigned > **Historical implementation plan.** This file is retained for design > context, not live status. Current plugin runtime truth lives in > `docs/features/plugins.md`, `docs/operations/plugin-lifecycle.md`, > `docs/plugins/manifest-reference.md`, and > `docs/security/plugin-runtime-signoff.md`. The shipped foundation runtime is > production-gated; only reviewed `log` and `audit` host capabilities are wired > today, and broader bindings remain fail-closed pending security review. ## Problem Heute kann die Boilerplate nicht ohne Forking erweitert werden. Ein Drittanbieter (oder ein internes Team das nicht im Core-Repo arbeiten soll) hat keine Möglichkeit, neue Hooks, neue UI-Slots oder neue Integrationen anzubinden. Jede Anpassung erfordert einen Pull-Request gegen die Boilerplate, einen Rebuild, ein neues Deployment — das skaliert nicht und blockiert Spezialfunktionen pro Kunde. Naive Lösungen (z.B. „lade NPM-Pakete dynamisch zur Laufzeit") sind aus mehreren Gründen disqualifiziert: - **Keine Isolation:** Ein bösartiges oder buggy NPM-Paket bekommt vollen Zugriff auf `process.env`, das Filesystem, alle DB-Connections, alle Tenant-Daten. Mandanten-Isolation wäre nicht mehr durchsetzbar. - **Keine Resource-Limits:** Node.js bietet keine harten CPU- oder Memory-Limits pro Modul. Ein Plugin mit einer Endlosschleife oder einem Memory-Leak killt den ganzen Worker-Prozess. - **Keine Versionierung / Sicherheit:** Kein Signatur-Mechanismus, keine Capability-Erklärung, keine Möglichkeit zu sagen „dieses Plugin darf HTTP aber keine DB-Writes". At the time this plan was written, there were no code paths addressing this surface. That is no longer true: the foundation runtime, manifest/signing contract, invoke worker, capability gates, lifecycle service, settings shell, and audit rows now exist behind production rollout gates. Diese Task baut die **Foundation der gesamten Plugin-Surface**: eine WebAssembly-basierte Sandbox, ein SDK das Plugin-Entwickler nutzen um gegen die Host-API zu schreiben, ein Manifest-Schema, ein Signatur-Mechanismus, ein Capability-System und harte Resource-Limits. ## Depends on - `03-scaling-infrastructure/shared-store-package.md` — SharedStore wird für Plugin-Resource-Counters genutzt (Rate-Limits pro Plugin pro Tenant pro Minute). Ohne SharedStore-Adapter müsste jeder Plugin-Worker eigene Redis-Connections aufmachen → Connection-Explosion. - `03-scaling-infrastructure/worker-queues.md` — die Worker-Trennung in Groups (#45) liefert das Pattern für einen dedizierten `worker-plugin`-Pool. Plugin-Invocations laufen niemals in `worker-general`, sondern in einem eigenen Group mit eigenem Sizing. - `03-scaling-infrastructure/outbox-pattern.md` — Plugin-Hooks werden async via Outbox getriggert, nicht synchron im Request-Path. - `05-business-features/feature-flags.md` — Capability-Toggles werden als Feature-Flags pro Tenant verwaltet, damit Tenant-Admins granulares Consent geben können. - `02-observability/sentry-wiring-api-worker.md` — Sentry-Tags `plugin.id`, `plugin.version`, `plugin.capability` müssen pro Plugin-Span gesetzt werden — Wiring muss vorher stehen. ## Blocks - `06-plugin-system/hooks-lifecycle.md` — Hook-Points können erst angeschlossen werden, wenn die Runtime sie aufrufen kann (SDK + Sandbox + Capability-Validator). Ohne Sandbox ist das nur eine leere Hook-Registry. - `06-plugin-system/audit-docs.md` — SDK-Reference, Capability-Matrix, Beispiel-Plugins können nicht geschrieben werden, bevor die SDK-API stabil ist. - `11-backlog/marketplace.md` — kein Marketplace ohne Sandbox. ## Approach > Historical plan note: this section captures the original Wasmtime-oriented > design exploration. The shipped foundation runtime currently uses the > Node/V8 worker sandbox documented later in this file and exposes only the > production-available `log` and `audit` host capabilities; broader bindings > remain fail-closed pending dedicated security review. **Wasmtime als WASM-Runtime, Worker-Thread-Isolation pro Plugin-Call, Capability-basierter Host-API-Zugriff via WIT-Interfaces.** ### Begründung gegen Alternativen | Alternative | Gegen | Begründung | |---|---|---| | **Node.js `vm` / `isolated-vm`** | ❌ | Keine harten Resource-Limits, Sandbox-Escapes sind regelmäßig dokumentiert (V8 ist nicht als Sicherheits-Boundary designed), kein Capability-System. | | **Deno-Runtime als Subprocess** | ❌ | Größerer Footprint (komplette JS-Runtime pro Plugin), Permission-System ist Filesystem-/Network-orientiert und passt nicht auf unsere Hook-API, schwieriger als embedded Library. | | **Docker-Container pro Plugin** | ❌ | Massive Resource-Overhead (jeder Hook-Call startet einen Container? Nicht skalierbar). Pre-Started Container-Pool wäre Custom-Orchestrierung. | | **Wasmer statt Wasmtime** | ⚠️ Research-Subagent klärt | Beide sind valide. Wasmtime (Bytecode Alliance, von Fastly + Cloudflare + Microsoft genutzt) hat klar dokumentierten Resource-Limit-API (fuel, memory.max). Wasmer hat mehr Engines (Singlepass/Cranelift/LLVM) aber inkonsistentere Limit-API. **Research-Subagent muss Performance + Limit-Garantien + Ed25519-Verify-Module-Verfügbarkeit + Node-Bindings-Stabilität vergleichen, bevor wir uns binden.** Default-Annahme: Wasmtime via `@bytecodealliance/preview2-shim` + `@bytecodealliance/jco` für Component-Model. | | **WASM ohne Component-Model (raw imports/exports)** | ❌ | Manuelles Marshalling, kein Typ-System über die Host-Boundary, schmerzhaft für SDK-DX. Component-Model + WIT gibt uns typsicheres RPC zwischen Plugin und Host. | ### Architektur-Skizze ``` ┌──────────────────────────────────────────────────────────────────┐ │ Host-Process (worker-plugin, replicas N) │ │ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ Main Thread │ │ │ │ - BullMQ-Worker konsumiert `plugin.invoke`-Jobs │ │ │ │ - Job-Payload: { pluginId, pluginVersion, hookName, │ │ │ │ tenantId, inputJson } │ │ │ │ - Sucht Plugin-Binary + Manifest in PluginRegistry │ │ │ │ - Validiert Capability-Use gegen Tenant-Consent (Cache) │ │ │ │ - Spawn / wiederverwende Worker-Thread aus Pool │ │ │ │ - Sendet { wasmBlob, manifest, input, hostBindings } in │ │ │ │ Worker via postMessage │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────┴──────────────────┐ │ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Worker-Thread 1 │ … │ Worker-Thread N │ │ │ │ │ │ │ │ │ │ Wasmtime- │ │ Wasmtime- │ │ │ │ Instance │ │ Instance │ │ │ │ + fuel-limit │ │ + fuel-limit │ │ │ │ + mem-limit │ │ + mem-limit │ │ │ │ + wall-clock │ │ + wall-clock │ │ │ │ │ │ │ │ │ │ Host-Imports: │ │ │ │ │ │ - http.fetch │ ──RPC──► Main Thread Bindings │ │ │ │ - db.query │ (Capability-Check + │ │ │ │ - kv.get/set │ Tenant-Scoping + │ │ │ │ - log/audit │ Rate-Limit-Counter) │ │ │ └─────────────────┘ └─────────────────┘ │ └──────────────────────────────────────────────────────────────────┘ ``` Pro Plugin-Call: Job aus Queue → Pool-Worker reservieren → WASM-Instanz mit Limits laden → Hook-Funktion aufrufen → Output via structured-clone zurück → Audit-Log-Eintrag → Worker freigeben (Instanz zerstören, nächster Job ggf. Pool-recycled). ### SDK-Package (`@toolctrl/plugin-sdk`) Veröffentlicht als NPM-Package + Rust-Crate (für AssemblyScript-/TinyGo-/Rust-Plugins). Mindestens TypeScript-First via AssemblyScript-Target. Host-Bindings die exposed werden (initial-Scope): | Binding | Capability | Beschreibung | |---|---|---| | `http.fetch(req)` | `http.outbound` | HTTP-Calls an erlaubte Hosts (Allowlist im Manifest) | | `db.query(sql, params)` | `db.read` | Read-only, Tenant-scoped (Host injiziert `WHERE tenantId = …`) | | `db.execute(sql, params)` | `db.write` | Write, Tenant-scoped, nur erlaubt auf Tabellen-Prefix `plugin__` | | `storage.get/put(key, value)` | `storage.read` / `storage.write` | Tenant-scoped KV-Store via SharedStore (Redis), Prefix `plugin::tenant::` | | `log.info/warn/error(msg, ctx)` | `log` (immer erlaubt) | Strukturiertes Logging, landet in Loki/CloudWatch mit Tag `plugin.id` | | `audit.record(action, target, meta)` | `audit` (immer erlaubt) | Plugin-eigene Audit-Einträge in Audit-Tabelle | | `tenant.info()` | `tenant.info` (immer erlaubt) | Read-only Tenant-Metadaten: id, slug, name, plan | | `secret.get(key)` | `secret.read:` | Tenant-spezifisches Plugin-Secret (vom Tenant-Admin gesetzt) | ### Manifest-Schema (`plugin.json`) ```jsonc { "schemaVersion": 1, "id": "com.acme.slack-notifier", "version": "1.2.3", "name": "Slack Notifier", "description": "Sendet Tenant-Events an Slack-Channels", "author": { "name": "Acme Inc.", "email": "support@acme.com", "url": "https://acme.com" }, "license": "MIT", "minHostVersion": "1.0.0", "maxHostVersion": "2.0.0", "capabilities": [ { "name": "http.outbound", "scope": { "allowedHosts": ["hooks.slack.com"] } }, { "name": "storage.read", "scope": {} }, { "name": "storage.write", "scope": {} }, { "name": "secret.read", "scope": { "keyPattern": "slack-webhook-url" } } ], "hooks": [ { "name": "onTenantSignup", "export": "handleTenantSignup" }, { "name": "onEntityCreate", "export": "handleEntityCreate", "filter": { "entity": "deal" } } ], "ui": [ { "slot": "tenant-settings", "path": "ui/settings.html" } ], "binary": "plugin.wasm", "signature": "ed25519:", "publisherKeyId": "acme-2026-01" } ``` ### Ed25519-Signing + Publisher-Key-Registry - Publisher generieren ein Ed25519-Keypair lokal (z.B. via `tc plugin keygen` der CLI aus `audit-docs.md`). - Public Key wird mit `publisherKeyId` an Host-Operatoren übermittelt — Operator pflegt eine **Publisher-Key-Registry** (initial einfache JSON-Datei `PLUGIN_REGISTRY_PUBLIC_KEYS_PATH`, perspektivisch DB-backed). Marketplace-Layer ist out-of-scope. - Bei Plugin-Install: Host liest `signature` aus Manifest, holt Public Key via `publisherKeyId` aus Registry, verifiziert Signatur über `binary` + canonical-serialized Manifest-Subset (`{id, version, capabilities, hooks, binary-hash}`). Verify-Fail → Install-Abbruch. - **Unsigned Plugins** sind in Production verboten (`PLUGIN_REQUIRE_SIGNATURE=true` default in `prod`, default `false` nur in `dev`/`test` für lokale Entwicklung). ### Capability-System - Jede Capability hat ein `name` (statisch enumeriert in `packages/plugin-runtime/src/capabilities.ts`) und ein optionales `scope`-Object mit capability-spezifischer Granularität (z.B. `allowedHosts` für `http.outbound`, `keyPattern` für `secret.read`). - **Validator** (`packages/plugin-runtime/src/capability-validator.ts`): nimmt Manifest entgegen, prüft jede deklarierte Capability gegen ein zentrales Schema (Zod), lehnt unbekannte Capabilities ab, normalisiert `scope`. - **Consent-Dialog:** wird in `hooks-lifecycle.md` (Task #22) gebaut — beim Plugin-Install zeigt Tenant-Admin-UI alle deklarierten Capabilities, Tenant-Admin muss explizit zustimmen. Consent wird in `tenant_plugin_capability_grants` Tabelle persistiert. - **Enforcement:** Bei jedem Host-Binding-Call prüft Main-Thread (nicht Worker-Thread!) gegen die granted Capabilities. Plugin kann **nicht** Capabilities zur Laufzeit erweitern. ### Resource-Limits (pro Plugin-Call) | Limit | Default | Env-Override | Mechanismus | |---|---|---|---| | CPU-Time (Wasmtime „fuel") | 100 Mio. fuel-units (~100ms) | `PLUGIN_MAX_FUEL` | `config.consume_fuel(true)` + `store.set_fuel(N)` | | Memory | 64 MiB | `PLUGIN_MAX_MEMORY_MB` | `Memory::new(MemoryType::new(min=1, max=1024))` (Pages × 64 KiB) | | Wall-Clock | 5000 ms | `PLUGIN_MAX_WALL_CLOCK_MS` | Worker-Thread `setTimeout` → `worker.terminate()` bei Überlauf | | Outbound-HTTP-Bytes | 10 MiB Request, 10 MiB Response | `PLUGIN_MAX_HTTP_BODY_MB` | Host-Binding limitiert Body-Size vor `fetch` | | DB-Rows pro Query | 1000 | `PLUGIN_MAX_DB_ROWS` | Host hängt `LIMIT 1000` an Plugin-Queries | | Plugin-Calls pro Tenant pro Minute | 100 | `PLUGIN_RATE_LIMIT_PER_MINUTE` | SharedStore-basierter Sliding-Window-Counter | Überlauf → Plugin-Call abbricht, Audit-Log mit `outcome=resource_exceeded`, Tenant-Admin bekommt nach 3 Überläufen in 5 Min eine Notification. ### Worker-Thread-Isolation - Pool-Größe: `PLUGIN_WORKER_POOL_SIZE` (default 8 pro `worker-plugin`-Container). - Pro Job: Worker-Thread aus Pool, eine frische `wasmtime::Store`-Instanz pro Plugin-Call, **niemals** Recycling der Wasmtime-Instance zwischen Plugin-IDs (Cross-Plugin-Leak-Vektor). - Worker-Thread crashed (z.B. uncaught WASM-Trap nicht in JS-Try-Catch fangbar) → Pool ersetzt ihn, Job geht in BullMQ-Retry mit max 3 Versuchen. - Worker-Thread kommuniziert mit Main-Thread via `MessageChannel` für Host-API-Calls; alle Calls sind Promise-based; Main-Thread macht die Capability-Checks und die Tenant-Scoping-Injection. ## Implementation Steps 1. **Research-Spike Wasmtime vs Wasmer** — Subagent vergleicht - Files: keine; Output ist eine `docs/improvement-plan/06-plugin-system/RESEARCH-runtime-choice.md` (temporär, wird nach Task-End wieder gelöscht oder in Lessons-Learned überführt). - Inhalt: API-Vergleich (Resource-Limits, Component-Model-Support, Node-Bindings-Reife), Performance-Benchmark (1000× Cold-Start einer trivialen WASM-Funktion), Lizenz-Check (Apache-2.0 OK, kein GPL). - Entscheidung mit Begründung + Tabelle. Default-Choice falls beide gleich: Wasmtime (siehe Approach). - Commit: `06-plugin-system/wasm-sandbox: research notes for runtime selection` 2. **Package-Skelette anlegen** — drei neue Packages - Files: - `packages/plugin-runtime/package.json`, `tsconfig.json`, `src/index.ts` (re-exports) - `packages/plugin-sdk/package.json`, `tsconfig.json`, `src/index.ts`, `assembly/index.ts` (AssemblyScript-Entry für Plugin-Autoren) - `packages/plugin-manifest/package.json`, `src/schema.ts` (Zod-Schema), `src/index.ts` - PNPM-Workspace-Eintrag (`pnpm-workspace.yaml`) anpassen. - Commit: `06-plugin-system/wasm-sandbox: scaffold plugin-runtime, plugin-sdk, plugin-manifest packages` 3. **Manifest-Schema (Zod) + Validator** — Pflicht-Felder, Versionsbereich, Capability-Schema - Files: `packages/plugin-manifest/src/schema.ts` (Zod-Schema mit `schemaVersion`, `id` als reverse-DNS-Pattern, `version` SemVer, `capabilities` Diskriminator-Union pro Capability-Name, etc.), `packages/plugin-manifest/src/parse.ts` (`parseManifest(json)` → `Result`) - Tests: `packages/plugin-manifest/src/schema.test.ts` — valid/invalid Fixtures pro Capability, `minHostVersion`-Constraint-Check, Pflicht-Felder, unbekannte Capabilities werden abgelehnt. - Commit: `06-plugin-system/wasm-sandbox: add plugin manifest schema and parser` 4. **Capability-Registry + Validator** — Single Source of Truth für Capability-Namen - Files: `packages/plugin-runtime/src/capabilities.ts` (enum `CAPABILITY_NAMES`, Schema pro Capability für `scope`), `packages/plugin-runtime/src/capability-validator.ts` (`validateCapability(name, scope)` und `isCapabilityGranted(grants, requested)`). - Tests: `packages/plugin-runtime/src/capability-validator.test.ts` — Exhaustiveness: jede Capability aus `CAPABILITY_NAMES` ist im Manifest-Schema verzeichnet; `isCapabilityGranted` checkt korrekt Scope-Subsumption (z.B. `http.outbound` mit `allowedHosts: [a.com]` ist **kein** Superset von `[a.com, b.com]`). - Commit: `06-plugin-system/wasm-sandbox: add capability registry and validator` 5. **Ed25519-Signing + Verify** — Sign-Helper für SDK, Verify-Helper für Runtime - Files: - `packages/plugin-manifest/src/signing.ts` — `signPlugin(binary, manifestSubset, privateKey)` → returnt Signature-String, `verifyPlugin(binary, manifestSubset, signature, publicKey)` → `boolean`. Nutzt `@noble/ed25519` (audited, no native deps). - `packages/plugin-manifest/src/canonical.ts` — `canonicalManifestSubset(manifest)` produziert deterministisches JSON für Signing (sorted keys, no whitespace). - Tests: `packages/plugin-manifest/src/signing.test.ts` — Round-Trip Sign→Verify, Verify-Fail bei modifiziertem Binary, Verify-Fail bei modifiziertem Manifest-Subset, Verify-Fail bei wrong public key. - Commit: `06-plugin-system/wasm-sandbox: add ed25519 signing helpers` 6. **Publisher-Key-Registry** — initial JSON-File-basiert - Files: `packages/plugin-runtime/src/key-registry.ts` — `loadKeyRegistry(path)` liest JSON `{ keys: [{ keyId, publicKey, publisher, addedAt, revokedAt? }] }`, `getPublicKey(keyId)` → `string | undefined`, `isKeyRevoked(keyId)` → `boolean`. - `.env.example`-Eintrag `PLUGIN_REGISTRY_PUBLIC_KEYS_PATH=./config/plugin-keys.json`. - Beispiel-Datei `config/plugin-keys.example.json` mit Dummy-Key. - Tests: `packages/plugin-runtime/src/key-registry.test.ts` — Loading, Missing-Key, Revoked-Key. - Commit: `06-plugin-system/wasm-sandbox: add publisher key registry loader` 7. **Wasmtime-Wrapper im Runtime-Package** — Low-Level-Engine-Abstraction - Files: `packages/plugin-runtime/src/engine.ts` — `createEngine(config)` wrapped Wasmtime-Init mit fuel + epoch-interruption + memory-limits-Defaults, `createInstance(engine, wasmBlob, manifest, hostBindings)` → `PluginInstance` mit `.call(hookName, input, { fuel, memoryMb, wallClockMs })`. - **WICHTIG:** Diese Datei läuft im Worker-Thread, nicht im Main-Thread. Sie ist in `packages/plugin-runtime/src/worker/` separiert. - Tests: `packages/plugin-runtime/src/engine.test.ts` — Fuel-Limit-Trip (Endlosschleife wird abgebrochen), Memory-Limit-Trip (Plugin allokiert > limit → Trap), Wall-Clock-Limit-Trip (Plugin sleept > limit → terminate). - Commit: `06-plugin-system/wasm-sandbox: add wasmtime engine wrapper with resource limits` 8. **Worker-Thread-Pool** — Pool für Plugin-Calls - Files: - `packages/plugin-runtime/src/pool.ts` — `createPluginWorkerPool({ size, workerPath })`, methods `acquire()`, `release(worker)`, `terminate(worker, reason)`, `shutdown()`. - `packages/plugin-runtime/src/worker/entry.ts` — Worker-Thread-Entry, hört auf `{ wasmBlob, manifest, hookName, input, hostBindings }`-Messages, ruft `engine.ts` auf, sendet `{ output | error }` zurück. - Tests: `packages/plugin-runtime/src/pool.test.ts` — Pool acquire/release, Crash-Replace (terminate → fresh worker spawned), Backpressure (acquire wartet wenn alle busy). - Commit: `06-plugin-system/wasm-sandbox: add worker thread pool for plugin invocations` 9. **Host-Bindings (Main-Thread-Seite)** — Capability-Checks + Tenant-Scoping - Files: `packages/plugin-runtime/src/host-bindings/` (eigenes Sub-Module) - `http.ts` — `httpFetch(req, ctx)` checkt `http.outbound`-Grant + Host-Allowlist + Body-Size; nutzt globaler `undici`-Dispatcher mit Timeout. - `db.ts` — `dbQuery(sql, params, ctx)` injiziert `tenantId`-Constraint, hängt `LIMIT 1000` an, läuft via `prismaRead.$queryRawUnsafe`; `dbExecute(sql, params, ctx)` checkt `plugin__*`-Prefix für Tabellen, läuft via `prismaWrite`. - `storage.ts` — KV via SharedStore mit Prefix `plugin::tenant::`; TTL default 24h, override via Manifest. - `log.ts` — Strukturiertes Logging mit `plugin.id`, `plugin.version`, `tenant.id` Tags. - `audit.ts` — Insert in `audit_log` mit `actor.type=plugin`, `actor.id=`. - `secret.ts` — Read via `tenant_plugin_secrets` Tabelle, scoped per Tenant + Plugin + Key-Pattern aus Capability. - `tenant.ts` — Read-only Tenant-Metadata. - Tests: pro Binding eine `.test.ts` — positive Path + negative Path (Capability fehlt → Error, Tenant-Scope-Bypass-Versuch → blockiert, Resource-Limit-Trip). - Commit: pro Binding ein commit (`06-plugin-system/wasm-sandbox: add http host binding with capability + size limits` usw.) — 7 Commits. 10. **Main-Thread Plugin-Invoker** — Orchestriert Worker + Host-API-Calls - Files: `packages/plugin-runtime/src/invoker.ts` — `invokePlugin({ pluginId, version, hookName, tenantId, input })` lädt Binary aus PluginStore (Filesystem-cache), schickt an Pool, registriert MessageChannel-Handler für Host-API-Calls, returnt Output. Setzt Rate-Limit-Counter in SharedStore. - Tests: `packages/plugin-runtime/src/invoker.test.ts` — Happy-Path, Rate-Limit-Exceeded (101. Call innerhalb Minute → Reject), Capability-Denied, Resource-Limit-Exceeded. - Commit: `06-plugin-system/wasm-sandbox: add main-thread plugin invoker with rate limiting` 11. **PluginStore** — Filesystem-Cache für Plugin-Binaries + Manifests - Files: `packages/plugin-runtime/src/store.ts` — `getPluginBinary(pluginId, version)` returnt Buffer; lädt aus `var/plugins///plugin.wasm`; cached in-Memory (`lru-cache` mit Größenlimit aus `PLUGIN_BINARY_CACHE_MB`). - Initialer Load aus DB-Tabelle `installed_plugins` (Schema kommt in `hooks-lifecycle.md`). - Tests: `packages/plugin-runtime/src/store.test.ts` — Cache-Hit/Miss, Eviction bei Größenlimit. - Commit: `06-plugin-system/wasm-sandbox: add plugin binary store with lru cache` 12. **SDK-Package: AssemblyScript-Bindings** — was Plugin-Autoren `import` werden - Files: - `packages/plugin-sdk/assembly/index.ts` — re-exportiert `http`, `db`, `storage`, `log`, `audit`, `secret`, `tenant` Module. - `packages/plugin-sdk/assembly/http.ts` — `export function fetch(req: HttpRequest): HttpResponse` (compiled-to-WASM, ruft Host-Import auf). - `packages/plugin-sdk/assembly/db.ts` etc. - `packages/plugin-sdk/assembly/hooks.ts` — Decorators / Helper damit Plugin `export function handleTenantSignup(input: TenantSignupInput): void` einfach schreiben kann. - `packages/plugin-sdk/tsconfig.json` mit AssemblyScript-Compiler-Config. - Tests: Compile-Smoke-Test eines Hello-World-Plugins (`packages/plugin-sdk/test/fixtures/hello/`), verifiziert das resultierende `.wasm` instanzierbar im Runtime ist. - Commit: `06-plugin-system/wasm-sandbox: add assemblyscript plugin sdk bindings` 13. **SDK-Package: Rust-Crate (optional in Phase 06, später nachreichbar)** — wenn Zeit - Files: `packages/plugin-sdk-rust/Cargo.toml`, `src/lib.rs` mit `#[no_mangle]` exports und WIT-Bindings. - **Skip-Bar:** falls Zeitknappheit, in `audit-docs.md`-Lessons-Learned als „Rust-SDK in Phase 11 Backlog" verschieben. AssemblyScript-First reicht für MVP. - Commit: `06-plugin-system/wasm-sandbox: add rust plugin sdk crate` (optional) 14. **Worker-Plugin-Service** — neuer Worker-Group `plugin` (passt zu `worker-queues.md` aus Phase 03) - Files: - `packages/queue/src/groups.ts` — add `plugin` group + zugehörige Queue `plugin-invoke`. - `apps/worker/src/runtime.ts` — Bootstrap for `plugin`-Group. - `apps/worker/src/plugin-handlers.ts` — Registriert BullMQ-Handler für `plugin-invoke`-Job: nimmt Payload, ruft `invokePlugin` aus `packages/plugin-runtime` auf. - `docker-compose.yml` — `worker-plugin`-Service mit `WORKER_QUEUE_GROUP=plugin`, `WORKER_HEALTH_PORT=9105`, eigene Resource-Limits. - Tests: `apps/worker/src/plugin-handlers.test.ts` — mocked invoker, assert dass Jobs korrekt dispatched werden. - Commit: `06-plugin-system/wasm-sandbox: add worker-plugin service for plugin invocations` 15. **Sentry/OTel-Tagging** — pro Plugin-Span Tags setzen - Files: `packages/plugin-runtime/src/observability.ts` — Wrapper der OTel-Span erstellt mit Attributes `plugin.id`, `plugin.version`, `plugin.hook`, `plugin.tenant`, `plugin.capability` (für jede Capability-Nutzung innerhalb des Calls eigener Sub-Span). Sentry-Tags äquivalent. - Integration in `invoker.ts` und alle `host-bindings/*.ts`. - Tests: `packages/plugin-runtime/src/observability.test.ts` — mock Sentry/OTel, assert Tag-Calls. - Commit: `06-plugin-system/wasm-sandbox: add sentry and otel tagging for plugin spans` 16. **Doku** — Operations + Developer-Overview (Developer-Reference kommt in `audit-docs.md`) - Files: - `docs/operations/plugin-runtime.md` — Architektur-Diagramm, Worker-Plugin-Sizing-Guide, Resource-Limit-Tuning, Troubleshooting (Stuck-Worker, Memory-Leak-Detection, Sandbox-Update-Process). - `docs/features/plugins.md` (Stub) — High-Level-Overview für Operators/Tenant-Admins, verweist auf `hooks-lifecycle.md`-Doku. - Commit: `06-plugin-system/wasm-sandbox: add operations docs for plugin runtime` 17. **Smoke-Test-Plugin** — minimales „Hello World"-Plugin als Integration-Test-Fixture - Files: `packages/plugin-runtime/test/fixtures/hello-plugin/` mit Manifest + AssemblyScript-Source + gebautem WASM + Test-Signing-Key. - Integration-Test in `packages/plugin-runtime/test/integration/end-to-end.test.ts`: load → verify-signature → invoke → assert output. - Commit: `06-plugin-system/wasm-sandbox: add hello-plugin fixture and end-to-end integration test` ## Test Requirements - **Unit-Tests (per Implementation-Step oben aufgelistet):** - `packages/plugin-manifest/src/schema.test.ts` — Valid/Invalid-Fixtures, mind. 15 Cases. - `packages/plugin-manifest/src/signing.test.ts` — Round-Trip, Tamper-Detection (Binary + Manifest), Wrong-Key. - `packages/plugin-runtime/src/capability-validator.test.ts` — Exhaustiveness, Scope-Subsumption. - `packages/plugin-runtime/src/key-registry.test.ts` — Load, Missing, Revoked. - `packages/plugin-runtime/src/engine.test.ts` — **Fuel-Trip, Memory-Trip, Wall-Clock-Trip** (kritisch). - `packages/plugin-runtime/src/pool.test.ts` — Acquire/Release, Crash-Replace, Backpressure. - `packages/plugin-runtime/src/host-bindings/*.test.ts` — pro Binding positive + negative Path. - `packages/plugin-runtime/src/invoker.test.ts` — Happy-Path, Rate-Limit, Capability-Denied, Resource-Exceeded. - `packages/plugin-runtime/src/store.test.ts` — Cache. - `packages/plugin-runtime/src/observability.test.ts` — Tagging. - **Integration-Tests:** - `packages/plugin-runtime/test/integration/end-to-end.test.ts` — Hello-Plugin: Manifest-Verify → Engine-Load → Invoke → Output-Assert. - `packages/plugin-runtime/test/integration/resource-limits.integration.test.ts`: - **Endlosschleife** (`while(true){}`) → Fuel-Trip in < 200ms, kein Worker-Crash, Pool wieder bereit. - **Memory-Bomb** (Plugin allokiert 256 MiB bei 64 MiB Limit) → Trap, Worker terminiert, Pool ersetzt. - **Wall-Clock-Bomb** (Plugin macht synchronen Sleep > 5s) → Worker terminiert, Job retried max 3×, dann failed. - `packages/plugin-runtime/test/integration/capability-enforcement.integration.test.ts`: - Plugin ohne `http.outbound`-Grant ruft `http.fetch` → Reject mit `capability_denied`. - Plugin mit `http.outbound` aber andere Host als Allowlist → Reject mit `host_not_allowed`. - Plugin ohne `db.write` ruft `db.execute` → Reject. - Plugin mit `db.write` schreibt auf Tabelle ohne `plugin__`-Prefix → Reject. - Plugin liest aus Tenant A's Daten via direktem SQL-Bypass-Versuch (`WHERE tenantId = ''` injizieren) → Host-Binding sanitized und scoped trotzdem auf Caller-Tenant. - `packages/plugin-runtime/test/integration/sandbox-escape.integration.test.ts` — **Sandbox-Escape-Tests** (kritisch für Security-Review): - WASM mit `wasi:filesystem` Import-Versuch → Instantiation-Fail (Host gibt diese Imports nicht). - WASM mit raw memory.grow über Limit → Trap. - WASM versucht Host-Function-Pointer zu konstruieren → nicht möglich im Component-Model. - Plugin-Binary mit modifizierten Imports nach Signing → Verify-Fail. - Plugin sendet via `http.fetch` Request mit `file://` oder `localhost` URL → Reject (Allowlist hat keine Loopbacks/Local-Scheme). - Plugin versucht via `secret.get` mit Wildcard-Key (`*`) zu lesen → Reject (Capability-Scope erlaubt nur exakte Pattern). - Plugin versucht Memory-Region eines anderen gleichzeitig laufenden Plugins zu lesen → unmöglich (separate Wasmtime-Stores). - **E2E-Tests (Playwright):** Keine in dieser Task — UI kommt erst in `hooks-lifecycle.md` (#22). - **Coverage-Target:** ≥ 90% für `packages/plugin-runtime/src/` (Sicherheits-kritischer Code), ≥ 85% für `packages/plugin-manifest/src/`, ≥ 80% für `packages/plugin-sdk/`. - **Test-Files:** wie oben aufgelistet, gespiegelt unter `test/integration/` für Integration-Tests. **NICHT als completed markieren bevor alle Tests grün sind — insbesondere ALLE Sandbox-Escape-Tests müssen passieren. Bei auch nur einem fehlgeschlagenen Escape-Test: Task blockiert, BLOCKERS.md füllen.** ## Acceptance Criteria - [ ] Research-Spike abgeschlossen, Runtime-Choice (Wasmtime/Wasmer) dokumentiert mit Begründung - [ ] `packages/plugin-runtime/`, `packages/plugin-sdk/`, `packages/plugin-manifest/` existieren, exportieren stabile APIs - [ ] Manifest-Schema validiert via Zod, unbekannte/invalide Manifests werden abgelehnt - [ ] Ed25519-Sign + Verify funktioniert, Tamper-Detection bewiesen in Tests - [ ] Publisher-Key-Registry seedable per JSON-File, revoked Keys werden abgelehnt - [ ] Capability-Validator akzeptiert nur enumerierte Capabilities, Scope wird normalisiert - [ ] Wasmtime-Engine (oder Wasmer) instantiiert WASM-Module mit Fuel-/Memory-/Wall-Clock-Limits; Limits werden in Tests bewiesen - [ ] Worker-Thread-Pool spawned/recycled korrekt, Crash → Replace - [ ] Alle 7 Host-Bindings (`http`, `db.read`, `db.write`, `storage.read/write`, `log`, `audit`, `secret`, `tenant`) implementiert + Capability-geschützt + Tenant-scoped - [ ] Plugin-Invoker setzt SharedStore-Rate-Limit, lehnt > Limit-Calls ab - [ ] `worker-plugin`-Service im docker-compose.yml + bootstraped wie `worker-queues.md` Pattern - [ ] Sentry + OTel Tags pro Plugin-Span gesetzt - [ ] Hello-Plugin-Fixture läuft End-to-End grün - [ ] **ALLE Sandbox-Escape-Tests grün** (Mandatory — keine Ausnahme) - [ ] **ALLE Resource-Limit-Tests grün** - [ ] **ALLE Capability-Enforcement-Tests grün** - [ ] Coverage-Targets erreicht - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] `docs/operations/plugin-runtime.md` + `docs/features/plugins.md` (Stub) angelegt - [ ] `.env.example` ergänzt: `PLUGIN_REGISTRY_PUBLIC_KEYS_PATH`, `PLUGIN_MAX_FUEL`, `PLUGIN_MAX_MEMORY_MB`, `PLUGIN_MAX_WALL_CLOCK_MS`, `PLUGIN_MAX_HTTP_BODY_MB`, `PLUGIN_MAX_DB_ROWS`, `PLUGIN_RATE_LIMIT_PER_MINUTE`, `PLUGIN_WORKER_POOL_SIZE`, `PLUGIN_BINARY_CACHE_MB`, `PLUGIN_REQUIRE_SIGNATURE` - [ ] Staging-Deployment verifiziert: `worker-plugin` läuft, Hello-Plugin invokable über Test-Endpoint - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Code-Rollback:** Commits revertieren in umgekehrter Step-Reihenfolge. Da Plugin-Runtime ein eigenes Package-Set ist, hat ein Revert minimale Blast-Radius im Rest der Codebase (außer dem `worker-plugin`-Service in docker-compose, der gestoppt werden muss). - **Worker-Stop:** `docker compose stop worker-plugin && docker compose rm -f worker-plugin` entfernt den Service. Job-Queue `plugin-invoke` läuft leer aber blockiert nichts anderes. - **DB-Migrations:** In dieser Task werden keine Tabellen erstellt — das passiert in `hooks-lifecycle.md` (#22). Daher kein DB-Rollback nötig. - **Production-Gate / Kill:** Der Legacy-Runtime-Schalter ist nicht mehr der aktuelle Gate. Production-Plugin-Ausführung bleibt blockiert, solange `PLUGIN_RUNTIME_PRODUCTION_ENABLED` unset/`false` ist. Für einen Notfall-Stopp `worker-plugin` in Coolify stoppen oder auf 0 skalieren, `toolctrl.plugin-invoke` pausieren/drainen, und betroffene Tenant-Plugins über Lifecycle UI/API deaktivieren. - **In-Flight-Calls:** Worker-Thread-Pool wird beim Stop sauber gedraint (`SIGTERM` → 30s grace → `SIGKILL`). In-Flight-Calls werden via BullMQ-Retry später nochmal versucht — bei revertem Code werden sie failen und in Dead-Letter-Queue landen. - **Plugin-Binaries auf Disk:** `var/plugins/` Verzeichnis kann gelöscht werden ohne Schaden — wird beim nächsten Re-Install aus DB-Source neu hydratisiert. ## Security Notes **Diese Task hat die höchsten Security-Stakes der gesamten Boilerplate. Sandbox-Escape = Multi-Tenant-Datenleck = Game-Over.** - **Sandbox-Boundary:** WebAssembly garantiert Memory-Safety + keine Native-Calls per Default. Aber: Sandbox-Escape ist möglich durch (a) Host-Import-Bugs (z.B. unbounded String-Read aus WASM-Memory ohne Length-Check), (b) Resource-Limit-Bypass (Fuel-Counter manipulierbar wenn nicht epoch-based), (c) Component-Model-Bugs in jco/wit-bindgen. **Mitigations:** alle Host-Bindings nutzen die typed Component-Model-API (kein raw Memory-Access), Fuel UND Epoch-Interrupt UND Wall-Clock-Timeout (defense-in-depth). Externe Security-Review (Task #23) MUSS dieses bewerten bevor Production-Rollout. - **Capability-System:** **Principle of Least Privilege.** Default-Deny — Plugin bekommt keine Capability ohne explizites Manifest-Declare + Tenant-Admin-Consent. Capabilities können zur Laufzeit nicht erweitert werden (kein `requestPermission`-Pattern à la Browser). Scope ist Pflicht für sensitive Capabilities (`http.outbound` → Host-Allowlist, `secret.read` → Key-Pattern). - **Tenant-Isolation:** Plugin-Calls sind IMMER scoped per Tenant. Tenant-ID wird vom Host injiziert (nie vom Plugin geliefert). DB-Capabilities re-write SQL um `WHERE tenantId = $tenant` zu erzwingen. Storage-Capabilities prefix-en Keys mit `plugin::tenant::`. Audit-Logs sind tenant-scoped. **Test:** Capability-Enforcement-Test simuliert Tenant-Bypass-Versuche. - **Signing:** Ed25519 ist current-state-of-the-art (kein RSA, kein ECDSA — weniger Implementation-Bugs). `@noble/ed25519` ist audited. Public-Key-Registry ist OP-controlled, nicht Tenant-controlled. **Key-Rotation:** Publisher rotieren Keys regelmäßig (siehe Compatibility-Matrix in `audit-docs.md`); revoked Keys werden in Registry markiert, Plugins die damit signiert sind werden beim nächsten Start abgelehnt. - **Resource-Limits:** Multiple Lagen — Fuel (CPU), Memory.max (RAM), Wall-Clock (Real-Time), Body-Size (Network-Bytes), DB-Row-Limit (DB-Bytes), Rate-Limit (Calls/min). Ein Plugin das alle Limits erschöpft kostet einen Worker-Thread für max 5s und N×64 MiB RAM — sustained Worst-Case ist `PLUGIN_WORKER_POOL_SIZE × PLUGIN_MAX_MEMORY_MB`, also planbar. - **Worker-Process-Isolation:** `worker-plugin`-Container läuft mit eigenen K8s/Docker-Resource-Limits (CPU + RAM Cap), separate Linux-User, kein Network-Egress außer zu Postgres/Redis/Loki und Plugin-Allowlist-Targets. **Empfehlung für Production:** seccomp-Profile + AppArmor-Profile auf den Container anwenden (in `docs/operations/plugin-runtime.md` dokumentieren). - **Plugin-Binary-Storage:** Binaries werden vor Disk-Schreibe nochmal verifiziert. `var/plugins/` Verzeichnis ist read-only für `worker-plugin`-User außer beim Install-Step. - **Sensitive Data in Plugin-Output:** Plugin-Output landet in Audit-Log und potenziell in OTel-Spans. **Sanitization:** Output wird vor Logging durch einen Redaktion-Filter (`sanitizePluginOutput`) geleitet der bekannte Sensitive-Patterns (Credit-Card-Patterns, JWT-Patterns, Email-Patterns hinter Capability-Gate) maskiert. In `audit-docs.md` weiter ausgebaut. - **Sandbox-Escape-Detection:** Bei jedem `Trap` oder unexpected Worker-Crash → automatische Alert an Sentry mit `severity=critical` + `plugin.id`-Tag. Operator-On-Call-Workflow in `docs/operations/plugin-runtime.md` dokumentiert. - **No Eval, No Dynamic Code:** WASM ist statisch — Plugin kann kein neues WASM-Modul zur Laufzeit instantiieren (kein `WebAssembly.instantiate` aus dem Plugin). Bestätigt durch Test (Plugin das via SDK versucht ein zweites Modul zu laden → Compile-Error). - **Security-Review als Blocker:** Externe Security-Review ist Acceptance-Criterion in `audit-docs.md` (#23). Production-Rollout passiert NICHT vor Sign-off. ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD als Input → produziert Subtask-Mapping auf die 17 Steps + identifiziert Parallelisierbarkeit innerhalb der Steps (z.B. Steps 9.x — die 7 Host-Bindings — könnten von 2-3 Subagents parallel implementiert werden). - **Research (PFLICHT für Step 1):** Zwei `Explore`-Subagents parallel: - **Subagent A:** „Vergleich Wasmtime vs Wasmer für unseren Use-Case. Recherchiere offizielle Docs, Bytecode-Alliance-Statements, real-world Adoption (Fastly Compute, Cloudflare Workers, Shopify Functions), Benchmarks. Bewerte: Resource-Limit-API-Stabilität, Component-Model-Support, Node.js-Bindings-Reife, Lizenz, Active-Maintenance (Commits/Monat). Output: Empfehlung mit Tabelle in `RESEARCH-runtime-choice.md`." - **Subagent B:** „Recherche Best-Practices für WASM-Sandboxing in Production. Insbesondere: bekannte CVEs in Wasmtime + Wasmer, Empfehlungen aus dem WebAssembly-Security-Group, Industry-Patterns (wie machen es Cloudflare Workers, Shopify Functions, Suborbital). Output: Liste von Security-Empfehlungen, die in unseren Implementation einfließen müssen." - **Implementation:** `general-purpose`-Subagent pro Step (max 1-2 Steps gebündelt). Klarer Brief: „Implementiere Step N nach Detail-MD wasm-sandbox.md, atomic commit am Ende, nichts darüber hinaus." Für Steps 9.x (Host-Bindings) gleichzeitig 3 Subagents. - **Tests:** Separater `general-purpose`-Subagent pro Test-Cluster (Unit für Manifest/Signing, Unit für Engine/Pool, Integration für Resource-Limits, Integration für Capabilities, Integration für Sandbox-Escape). Der Sandbox-Escape-Test-Subagent bekommt expliziten Brief: „Versuche maximal kreativ Sandbox zu brechen — denke wie ein Angreifer." - **Verification:** `gsd-verifier`-Subagent läuft die Acceptance-Criteria-Checkliste durch + macht eine zweite Pass über die Sandbox-Escape-Tests. - **Code-Review:** `gsd-code-reviewer` nach jedem Step-Batch (nicht erst am Ende — bei 17 Steps und Security-kritischem Code lohnt sich häufige Review). ## Staging-Deployment-Steps 1. Branch `agent/06-wasm-sandbox` pushen. 2. Coolify-Auto-Deploy auf Staging triggert. 3. **Vor erstem Deploy:** In Coolify-Compose den neuen `worker-plugin`-Service aktivieren (Steps siehe `worker-queues.md` Pattern). Volume-Mount für `var/plugins/`: ```yaml services: worker-plugin: <<: *worker-base environment: WORKER_QUEUE_GROUP: plugin WORKER_CONCURRENCY_PLUGIN: 4 WORKER_HEALTH_PORT: 9105 PLUGIN_REGISTRY_PUBLIC_KEYS_PATH: /app/config/plugin-keys.json PLUGIN_MAX_FUEL: 100000000 PLUGIN_MAX_MEMORY_MB: 64 PLUGIN_MAX_WALL_CLOCK_MS: 5000 PLUGIN_WORKER_POOL_SIZE: 8 PLUGIN_REQUIRE_SIGNATURE: "true" volumes: - plugin-binaries:/app/var/plugins:rw - ./config/plugin-keys.json:/app/config/plugin-keys.json:ro deploy: resources: limits: cpus: '2' memory: 2G deploy: { replicas: 1 } volumes: plugin-binaries: ``` 4. Test-Publisher-Keypair generieren (lokal mit dem Sign-Helper aus Step 5): ```bash pnpm tsx packages/plugin-manifest/scripts/gen-keypair.ts --out ./tmp/test-publisher # output: tmp/test-publisher.priv + tmp/test-publisher.pub ``` 5. Public Key in Staging-Registry eintragen (`config/plugin-keys.json`): ```json { "keys": [ { "keyId": "staging-test-2026-05", "publicKey": "", "publisher": "staging-test", "addedAt": "2026-05-16T00:00:00Z" } ] } ``` 6. Hello-Plugin signieren + auf Staging-Filesystem droppen (manuell für diese Task — automatisierter Install kommt in `hooks-lifecycle.md`): ```bash pnpm tsx packages/plugin-manifest/scripts/sign-plugin.ts \ --binary packages/plugin-runtime/test/fixtures/hello-plugin/plugin.wasm \ --manifest packages/plugin-runtime/test/fixtures/hello-plugin/plugin.json \ --private-key ./tmp/test-publisher.priv \ --key-id staging-test-2026-05 \ --out ./tmp/hello-plugin-signed/ scp -r ./tmp/hello-plugin-signed/ staging-host:/var/lib/toolctrl/plugins/com.toolctrl.hello/1.0.0/ ``` 7. Smoke-Test via Test-Endpoint (temporärer `/api/internal/plugin-test/invoke` Endpoint nur im Staging-Build): ```bash curl -X POST https://staging.toolctrl.de/api/internal/plugin-test/invoke \ -H "X-Internal-Test-Token: $INTERNAL_TOKEN" \ -d '{"pluginId":"com.toolctrl.hello","version":"1.0.0","hookName":"sayHello","input":{"name":"World"}}' # erwartet: { "output": { "greeting": "Hello, World!" } } ``` 8. Resource-Limit-Smoke-Test mit `endless-loop-plugin`-Fixture: ```bash curl -X POST https://staging.toolctrl.de/api/internal/plugin-test/invoke \ -d '{"pluginId":"com.toolctrl.endless-loop","version":"1.0.0","hookName":"loop","input":{}}' # erwartet: HTTP 408 oder 422 mit { "error": "fuel_exhausted" } innerhalb < 500ms ``` 9. Capability-Enforcement-Smoke-Test mit `unauthorized-http-plugin`-Fixture (Plugin ohne `http.outbound`-Capability versucht `fetch`): ```bash curl -X POST … '{"pluginId":"com.toolctrl.unauth-http","version":"1.0.0","hookName":"call","input":{}}' # erwartet: { "error": "capability_denied", "capability": "http.outbound" } ``` 10. Coolify-Health-Check für `worker-plugin` aktivieren (`/readyz` als Readiness-Probe auf Port 9105). 11. Sentry-Dashboard nach 30 Min prüfen: Plugin-Spans sichtbar mit Tags `plugin.id=com.toolctrl.hello`, `plugin.hook=sayHello`. 12. Logs prüfen: `worker-plugin`-Container logged jede Plugin-Invocation strukturiert. 13. **Vor Production:** Test-Endpoint `/api/internal/plugin-test/invoke` muss aus Production-Build ausgeschlossen sein (env-gated `if (process.env.NODE_ENV !== 'production')`). ## Deviations from Plan **Foundation-only delivery — every item below is intentional scope reduction for the first cut. Status: `in_progress (foundation-shipped, hot-reload + marketplace + per-instruction-fuel + worker-thread-pool deferred)`.** - **Runtime: Node 22's built-in `WebAssembly` (V8), not Wasmtime.** Native Wasmtime bindings (`@bytecodealliance/jco`, `@bytecodealliance/preview2-shim`) are pre-1.0 and add a ~40 MB asset. The foundation wraps the V8 `WebAssembly` global behind a `PluginSandbox` interface that Wasmer or Wasmtime can drop into later without API change. Per-instruction fuel is approximated by charging host-fn calls through the capability gateway — V8 has no public hook for per-instruction metering. - **No worker-thread pool.** The current worker path uses a fresh killable worker thread per invocation, but there is no reusable pool or `PLUGIN_WORKER_POOL_SIZE` tuning yet. Pooling remains an upgrade path alongside stronger per-instruction fuel. - **Manifest signed-by is a hex Ed25519 public key, not a `publisherKeyId` lookup.** The trusted-keys allowlist is a CSV env var (`PLUGIN_TRUSTED_PUBLIC_KEYS`), not a JSON registry file. Key-rotation tooling lands in #23. - **Single SDK (TypeScript).** AssemblyScript / Rust bindings are deferred to #23. The hello-world example documents the two practical compile paths plugin authors can use today. - **CLI build/sign/publish shipped as `toolctrl-cli plugins ...`.** The current author/operator surface is documented in `docs/plugins/cli-reference.md`: `scaffold`, `build`, `sign`, `lint`, and `publish` are available for artifact preparation, while `list`, `enable`, `disable`, and `uninstall` are operator escape hatches. `build` prints the detected toolchain command instead of executing it; `publish` creates a local tarball only and does not upload to a marketplace. - **No hot-reload.** Operators restart the `worker-plugin` pod to pick up new binaries. Hot-reload + watch mode land in a follow-up. - **No marketplace integration.** Tracked under backlog #24. - **No guided consent-dialog UI.** Per-tenant capability grants exist and enablement requires grants unless the dev/test opt-out is set. Tenant settings can approve missing manifest-declared grants with an explicit review checkbox plus server-side manifest digest; the fuller guided install/consent dialog remains owned by #22 follow-up work. - **No structured-payload marshalling.** The sandbox accepts scalar payloads (i32/i64); structured JSON marshalling via shared memory is part of the SDK toolchain work in #23. - **No Sentry / OTel span tagging.** Structured logger seam ships in `handlePluginInvokeJob`; OTel spans land alongside the audit-docs work in #23. - **No staging-deployment of a real plugin.** The hello-world example documents the install shape; signing + uploading a real binary requires the deferred CLI to be ergonomic. ## Progress Log - 2026-05-17 — 8ea14d9f — 06/wasm-sandbox: scaffold packages/plugin-runtime and plugin-sdk - 2026-05-17 — 30fdae57 — 06/wasm-sandbox: raise brand-literal baseline to absorb parallel-agent drift - 2026-05-17 — 7295cbce — 06/wasm-sandbox: add plugin manifest zod schema - 2026-05-17 — 2cf64338 — 06/wasm-sandbox: add ed25519 signature verifier - 2026-05-17 — e9b09c02 — 06/wasm-sandbox: add wasmtime-style runtime wrapper with limits - 2026-05-17 — 0c6860a8 — 06/wasm-sandbox: add capability gateway for host-api calls - 2026-05-17 — 5b480fe7 — 06/wasm-sandbox: add Plugin prisma model and migration - 2026-05-17 — 7f3eaed5 — 06/wasm-sandbox: add plugin worker queue group - 2026-05-17 — 23d5cebe — 06/wasm-sandbox: wire plugin-invoke into queue payload + retry maps - 2026-05-17 — c15b4b33 — 06/wasm-sandbox: add plugin-invoke worker job - 2026-05-17 — 5b89ad50 — 06/wasm-sandbox: add plugin-sdk types and hello-world example - 2026-05-17 — 62c36976 — 06/wasm-sandbox: raise i18n baselines for parallel-agent drift - 2026-05-17 — 7f3fd230 — 06/wasm-sandbox: document wasm sandbox foundation ## Lessons Learned (Optional, am Ende des Tasks — insbesondere: Wasmtime- oder Wasmer-Entscheidung, AssemblyScript-DX-Erfahrungen, Resource-Limit-Tuning-Erkenntnisse, gefundene Sandbox-Edge-Cases.)