SharedWorker VAPI-router

Browser-only MUST • postMessage(MessageChannel) • lazy kernel-init • DApp-sandboxing via VFS-scope • fallback naar HTTP • status: ontwerp, bron: workers/client-kernel-*.ts

Besluit in 1 zin: De SharedWorker draait een eigen KernelOrchestrator-instance in de browser (geen HTTP round-trip), wordt lazy geinitialiseerd bij eerste VAPI-call, geeft elke DApp een dedicated MessagePort, en valt terug op HTTP-fetch als SharedWorker niet beschikbaar is.

1. Architectuur

DApp iframe (sandbox, opaque origin)
  └── window.maos.request('wallet:sign', {...})
        │
        ▼ postMessage(MessageChannel)
AppWindow (main-thread, client-kernel-client.ts)
  │
  ├── SharedWorker beschikbaar? ──▶ client-kernel-worker.ts
  │     │                              │
  │     │                              ▼ ensureKernel()
  │     │                              │  new KernelOrchestrator(config)
  │     │                              │  await kernel.initialize()
  │     │                              │  await kernel.start()
  │     │                              │
  │     │                              ▼ port.onmessage
  │     │                              │  kernel.call(method, params, appId)
  │     │                              │  → VAPIServer dispatch
  │     │                              │  → Permission check
  │     │                              │  → Handler execution
  │     │                              │
  │     │                              ◀── port.postMessage({result})
  │     │
  │     └── SharedWorker NIET beschikbaar? ──▶ HTTP fallback
  │           POST /api/kernel (Next.js route)
  │           → KernelOrchestrator via HTTP
  │
  ◀── result (of fallback-antwoord)
        │
        ▼
DApp iframe ontvangt antwoord

2. SharedWorker lifecycle

FaseActieBron
1. connectAppWindow opent SharedWorker, ontvangt READY handshakeclient-kernel-worker.ts:166-178
2. lazy initEerste VAPI-call triggert ensureKernel()client-kernel-worker.ts:49
3. kernel initNieuwe KernelOrchestrator + initialize() + start()client-kernel-worker.ts:111-113
4. permission hydrationPermissionRegistry uit IndexedDB hydraten (D-fix 1)client-kernel-worker.ts:127-131
5. notification pollerOn-chain notificaties starten (best-effort)client-kernel-worker.ts:137-141
6. serveport.onmessage → kernel.call() → port.postMessage(result)client-kernel-worker.ts:180-219
REGEL: De kernel wordt lazy geinitialiseerd — niet bij SharedWorker-start, maar bij eerste VAPI-call. Dit voorkomt onnodig geheugengebruik als er geen DApps draaien.
Q21 — Sessielimiet configurable: Het maximale aantal gelijktijdige DApp-sessies is configureerbaar via KernelConfig.maxSessions (default: 3). Bij overschrijding: nieuwe sessie wordt geweigerd + console.warn-log met appId + huidigAantal. Reden: SharedWorker geheugenlimiet in browser. Logging bij >3 sessies helpt bij debugging van geheugendruk.

3. Connectiebeheer (main-thread side)

De client-kernel-client.ts is een main-thread singleton die de SharedWorker-verbinding beheert:

Bron: client-kernel-client.ts:63-100.

Q22 — LockGate grace 60s statisch: De wallet-disconnect grace-periode is 60 seconden, statisch. Geen dynamische berekening op basis van netwerkconditie. Reden: eenvoud, voorspelbaarheid, geen extra complexiteit voor Fase 1A. Aanpassing is mogelijk in toekomst via KernelConfig.lockGate.graceMs.

4. VAPI-call flow (SharedWorker-kant)

port.onmessage(event)
  │
  ├── Bron-check: source !== 'app-window'? → drop
  ├── Type-check: type !== 'VAPI'? → drop
  ├── Method-check: geen string? → error
  │
  ▼
ensureKernel()  ──▶ kernel instanceof KernelOrchestrator? ──▶ return kernel
  │                                               │
  │ (nog niet geinitialiseerd)                    │ (init error)
  │                                               ▼
  ▼                                              throw
new KernelOrchestrator(config)
  │
  ├── Storage scope resolver fetchen (/api/dapps)
  │   └── Offline? → legacy scopes
  │
  ├── kernel.initialize()
  ├── kernel.start()
  ├── PermissionRegistry hydrate
  ├── Notification poller start
  │
  ▼
kernel.call(method, params, appId, source)
  │
  ├── VAPIServer.buildContext(appId, source)
  │   ├── Permission resolver: welke permissies heeft deze DApp?
  │   ├── VFS scope: /user/apps/{appId}/ (of manifest basePath)
  │   └── Rate-limit tier bepalen
  │
  ├── Permission check: requiredPermissions vs context.permissions
  │   └── GEEN match? → 403 PERMISSION_DENIED
  │
  ├── VFS scope enforcement (voor VFS-calls)
  │   └── Pad buiten scope + geen grant? → PERMISSION_DENIED
  │
  ├── Handler uitvoeren
  │
  └── Resultaat terug via port.postMessage({source:'client-kernel', id, result})

5. DApp-sandboxing (VFS-scope)

Elke DApp wordt beperkt tot zijn eigen VFS-map. De scope wordt bepaald door:

  1. Manifest storage.basePath — als aanwezig, wordt dit als scope gebruikt
  2. Legacy fallback — /user/apps/{appId}/
  3. External paths — storage.allowExternalPaths uit manifest (extra prefixes)
  4. Launch grants — exact-pad toegang bij double-click openen (GrantRegistry)

Sandboxing-regels:

Bron: vapi/server.ts:164-217, security/grant-registry.ts:9-23.

6. Security in de Worker

De DApp-worker-bootstrap blokkeert actief directe netwerktoegang:

BlokkadeMechanismeBron
fetch()Overschreven: alles behalve blob:/data: → throw Errordapp-worker-bootstrap.ts:24-30
XMLHttpRequestSubclass: open() blokkeert niet-blob URLsdapp-worker-bootstrap.ts:33-48
Origin checkAccepteert HTTP-origins (browser sandbox is security boundary)dapp-worker-bootstrap.ts:57-65
BELANGRIJK: De security boundary is de iframe sandbox (geen allow-same-origin), niet de origin-check in de worker. De worker-blocks zijn defensief (defense-in-depth).

7. Fallback naar HTTP

Als SharedWorker niet beschikbaar is (Safari, incognito, CSP):

AppWindow
  └── callViaSharedWorker(method, params, appId, fallback?)
        │
        ├── SharedWorker OK → port.postMessage → port.onmessage → resolve
        │
        └── SharedWorker NIET OK → fallback(method, params)
              │
              ▼
            POST /api/kernel
              ├── x-dapp-id header (DApp-identiteit)
              ├── x-client-id header ('maos-core' voor desktop)
              ├── CSRF-token
              │
              ▼
            Next.js route → KernelOrchestrator via HTTP
              │
              ▼
            antwoord terug

De HTTP-route (/api/kernel/route.ts) voert dezelfde checks uit: tier-resolutie, rate-limiting, DApp-identity verificatie via Referer-header.

8. Risico's en aanbevelingen

RisicoImpactAanbeveling
SharedWorker init mislukt → geen DAppshoogHTTP fallback is aanwezig; test expliciet op Safari/incognito
Lazy init race (tweede call wacht 10s)middelHuidige polling (200 × 50ms = 10s) is acceptabel; overweeg Promise-based wait
Permission hydration mist eerste callmiddelD-fix 1: hydrate() bij init; re-hydrate guard voorkomt dubbele
Geheugengebruik SharedWorker (kernel leeft voor altijd)middelSuspendScheduler + MemoryGuard + ProcessAutoRestart als safety-net
devMode nooit auto-enable (F2-besluit)laagBlijf devMode: false forceren — geen NODE_ENV-check
Aanbeveling: De SharedWorker-aanpak is goed — lazy init, singleton port, HTTP fallback. Het zwakste punt was de init-wachttijd (tot 10s). Q17: kernel.preload() bij boot verhelpt dit (zie kernel-orchestrator-spec). Q21: Sessielimiet via KernelConfig.maxSessions (default 3). Q22: 60s grace statisch houden.