Browser-only MUST • postMessage(MessageChannel) • lazy kernel-init • DApp-sandboxing via VFS-scope • fallback naar HTTP • status: ontwerp, bron: workers/client-kernel-*.ts
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
| Fase | Actie | Bron |
|---|---|---|
| 1. connect | AppWindow opent SharedWorker, ontvangt READY handshake | client-kernel-worker.ts:166-178 |
| 2. lazy init | Eerste VAPI-call triggert ensureKernel() | client-kernel-worker.ts:49 |
| 3. kernel init | Nieuwe KernelOrchestrator + initialize() + start() | client-kernel-worker.ts:111-113 |
| 4. permission hydration | PermissionRegistry uit IndexedDB hydraten (D-fix 1) | client-kernel-worker.ts:127-131 |
| 5. notification poller | On-chain notificaties starten (best-effort) | client-kernel-worker.ts:137-141 |
| 6. serve | port.onmessage → kernel.call() → port.postMessage(result) | client-kernel-worker.ts:180-219 |
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.De client-kernel-client.ts is een main-thread singleton die de SharedWorker-verbinding beheert:
MessagePort gedeeld door alle DApps (geen heropening)READY handshake (timeout: 5s) voor eerste callVAPI_TIMEOUT_MS)/api/kernelsharedWorkerAvailable = false gezet — geen herpogingenBron: client-kernel-client.ts:63-100.
KernelConfig.lockGate.graceMs.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})
Elke DApp wordt beperkt tot zijn eigen VFS-map. De scope wordt bepaald door:
storage.basePath — als aanwezig, wordt dit als scope gebruikt/user/apps/{appId}/storage.allowExternalPaths uit manifest (extra prefixes)Sandboxing-regels:
.. in pad-segment = onmiddellijk geweigerd/ — voorkomt sibling-collisieBron: vapi/server.ts:164-217, security/grant-registry.ts:9-23.
De DApp-worker-bootstrap blokkeert actief directe netwerktoegang:
| Blokkade | Mechanisme | Bron |
|---|---|---|
fetch() | Overschreven: alles behalve blob:/data: → throw Error | dapp-worker-bootstrap.ts:24-30 |
XMLHttpRequest | Subclass: open() blokkeert niet-blob URLs | dapp-worker-bootstrap.ts:33-48 |
| Origin check | Accepteert HTTP-origins (browser sandbox is security boundary) | dapp-worker-bootstrap.ts:57-65 |
allow-same-origin), niet de origin-check in de worker. De worker-blocks zijn defensief (defense-in-depth).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.
| Risico | Impact | Aanbeveling |
|---|---|---|
| SharedWorker init mislukt → geen DApps | hoog | HTTP fallback is aanwezig; test expliciet op Safari/incognito |
| Lazy init race (tweede call wacht 10s) | middel | Huidige polling (200 × 50ms = 10s) is acceptabel; overweeg Promise-based wait |
| Permission hydration mist eerste call | middel | D-fix 1: hydrate() bij init; re-hydrate guard voorkomt dubbele |
| Geheugengebruik SharedWorker (kernel leeft voor altijd) | middel | SuspendScheduler + MemoryGuard + ProcessAutoRestart als safety-net |
| devMode nooit auto-enable (F2-besluit) | laag | Blijf devMode: false forceren — geen NODE_ENV-check |
kernel.preload() bij boot verhelpt dit (zie kernel-orchestrator-spec). Q21: Sessielimiet via KernelConfig.maxSessions (default 3). Q22: 60s grace statisch houden.