Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,538 @@
|
||||
# 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_<pluginId>_` |
|
||||
| `storage.get/put(key, value)` | `storage.read` / `storage.write` | Tenant-scoped KV-Store via SharedStore (Redis), Prefix `plugin:<id>:tenant:<tid>:` |
|
||||
| `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:<key-pattern>` | 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:<base64-signature>",
|
||||
"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<Manifest, Error[]>`)
|
||||
- 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_<id>_*`-Prefix für Tabellen, läuft via `prismaWrite`.
|
||||
- `storage.ts` — KV via SharedStore mit Prefix `plugin:<id>:tenant:<tid>:`; 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=<pluginId>`.
|
||||
- `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/<id>/<version>/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_<id>_`-Prefix → Reject.
|
||||
- Plugin liest aus Tenant A's Daten via direktem SQL-Bypass-Versuch (`WHERE tenantId = '<other>'` 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:<id>:tenant:<tid>:`. 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": "<base64>", "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.)
|
||||
Reference in new issue
Block a user