API: VAPI-handlers migratie (60+ handlers)

Ticket 1D-02 • Bron: src/routes/vapi.ts (gepland) • Status: ontwerp • Risico: hoog (60+ handlers, capability-checks)

Kerndefinitie: Migratie van 60+ VAPI-handlers van Next.js naar Hono. Handlers zijn gegroepeerd in zes categorieen: wallet (~15), storage (~12), chain (~10), dapp (~8), extension (~8), vfs-backend (~7). Gedrag blijft identiek. Elke VAPI-call wordt gecontroleerd in SharedWorker (capability-check) voordat de handler wordt aangeroepen. Exact method+pad matching, geen family-matching.

1. Architectuur

DApp (iframe)
    │
    ├── maos.request("wallet:sign", { tx: {...} })
    │
    └── SharedWorker
            ├── 1. Method+pad extraheren
            │       method: "wallet:sign"
            │       pad: (geen pad voor wallet-methods)
            │
            ├── 2. Manifest-grants van DApp
            │       grants: ["wallet:connect", "wallet:sign", "wallet:send"]
            │
            ├── 3. Exact match check
            │       "wallet:sign" in grants? → ja
            │
            └── 4. Door naar Hono handler
                    │
                    └── POST /vapi/wallet/sign
                            ├── Kernel-context middleware
                            ├── Handler voert uit
                            └── Return resultaat

Capability-check in SharedWorker (niet in handler):
  ├── sneller (geen network round-trip)
  ├── veiliger (geen ongeautoriseerde calls)
  └── eenvoudiger (middleware op client-side)

2. Handler-overzicht (60+ handlers)

Handler-groepAantalVoorbeeldenKernel-afhankelijk
wallet-handlers~15wallet:connect, wallet:disconnect, wallet:sign, wallet:send, wallet:signMessage, wallet:getBalance, wallet:switchChain, wallet:addTokenJa (wallet service)
storage-handlers~12storage:read, storage:write, storage:list, storage:delete, storage:mkdir, storage:stat, storage:copy, storage:moveJa (storage service)
chain-handlers~10chain:call, chain:send, chain:estimateGas, chain:getBalance, chain:getBlock, chain:getTxReceipt, chain:encodeJa (chain service)
dapp-handlers~8dapp:install, dapp:uninstall, dapp:list, dapp:info, dapp:update, dapp:enable, dapp:disableJa (kernel events)
extension-handlers~8extension:connect, extension:queue, extension:sign, extension:disconnect, extension:statusJa (extension service)
vfs-backend-handlers~7vfs:mount, vfs:unmount, vfs:read, vfs:write, vfs:list, vfs:statJa (VFS service)

3. Migratie-principes

4. Exact method+pad matching

Regel: GEEN family-matching.

Geldig:
  DApp manifest: grants = ["storage:read:/app/my-data/*"]
  VAPI call:     method = "storage:read", path = "/app/my-data/file.txt"
  Match: ✓ (pad eindigt op /*, dus match)

Ongeldig (familie-matching, VERBODEN):
  DApp manifest: grants = ["storage:read"]
  VAPI call:     method = "storage:read", path = "/app/other/file.txt"
  Match: ✗ (geen pad-constraint, dus geen toegang tot /app/other/)

Reden: zonder pad-constraint heeft een DApp toegang tot ALLE storage.
       Dat is een veiligheidsrisico. Pad-constraints zijn verplicht voor storage/chain.

4.1 Matching-voorbeelden

GrantVAPI callMatchReden
wallet:signwallet:signJaExacte method match
wallet:signwallet:sendNeeAndere method
storage:read:/app/*storage:read:/app/file.txtJaWildcard match
storage:read:/app/*storage:read:/other/file.txtNeePad niet in scope
chain:call:0x1234*chain:call:0x1234abcdJaContract-adres match

5. Handler-groep detail: wallet-handlers

// POST /vapi/wallet/sign
// Input: { method: "wallet:sign", params: { tx: {...} } }

1. SharedWorker capability-check
   ├── method+pad match met manifest.grants?
   │   ├── Ja → door naar handler
   │   └── Nee → 403 + audit
   │
2. Handler: kernel-context middleware
   ├── const kernel = c.get("kernel")
   │
3. Intent-queue toevoegen
   ├── Intent: { type: "sign", dappId, wallet, tx }
   │
4. Wallet-DApp: toon details + approve/reject
   │
5. Approve → kernel.wallet.sign(tx) → receipt
   │
6. Reject → blokkeer + audit log

6. Handler-groep detail: storage-handlers

// POST /vapi/storage/read
// Input: { method: "storage:read", params: { path: "/app/data/file.txt" } }

1. SharedWorker capability-check
   ├── grant: "storage:read:/app/*"
   ├── pad: "/app/data/file.txt"
   └── match: ✓ (wildcard)
   │
2. Handler: kernel.storage.read(path)
   ├── Lees bestand uit VFS
   └── Return content als base64
   │
3. Audit log
   ├── { dappId, method: "storage:read", path, timestamp }
   └── Geen fout? → info log. Fout? → warning log.

7. Capability-check in SharedWorker

SharedWorker ontvangt VAPI-call van DApp-iframe
    │
    ├── 1. Method+pad extraheren
    │       ├── method: "storage:read"
    │       └── path: "/app/my-data/file.txt"
    │
    ├── 2. Manifest-grants van DApp ophalen
    │       └── grants: ["storage:read:/app/my-data/*"]
    │
    ├── 3. Exact match checken
    │       ├── "storage:read" + "/app/my-data/file.txt"
    │       ├── Match met "storage:read:/app/my-data/*"?
    │       │
    │       └── Ja → toegestaan
    │       └── Nee → 403 + audit
    │
    └── 4. Door naar Hono handler
            └── POST /vapi/storage/read
                    ├── kernel = c.get("kernel")
                    └── kernel.storage.read(path)

8. Betaalde DApps via VAPI-payment

BESLIST: Betaalde DApps worden ondersteund via VAPI-payment door wallet-DApp als enige payment-rail. MAOS draait geen eigen Stripe-integratie per DApp.

9. Request / Response voorbeelden

9.1 POST /vapi/wallet/sign

POST /vapi/wallet/sign HTTP/1.1
Cookie: maos-session=...
Content-Type: application/json

{
  "method": "wallet:sign",
  "params": {
    "tx": {
      "to": "0x742d35Cc...",
      "value": "1000000000000000000",
      "chainId": 270
    }
  }
}

Response (goedgekeurd):
{
  "signed": true,
  "txHash": "0xabc123...",
  "signature": "0xdef456...",
  "intentId": "intent_xyz"
}

Response (gegeweigerd):
{
  "signed": false,
  "error": "User rejected transaction",
  "intentId": "intent_xyz"
}

9.2 POST /vapi/storage/read

POST /vapi/storage/read HTTP/1.1
Cookie: maos-session=...
Content-Type: application/json

{
  "method": "storage:read",
  "params": {
    "path": "/app/my-data/config.json"
  }
}

Response:
{
  "content": "eyJrZXkiOiAidmFsdWUifQ==",
  "encoding": "base64",
  "size": 1234,
  "mimeType": "application/json"
}

9.3 Capability拒绝

POST /vapi/storage/delete HTTP/1.1
Cookie: maos-session=...
Content-Type: application/json

{
  "method": "storage:delete",
  "params": { "path": "/app/important/file.txt" }
}

Response:
{
  "error": "Capability denied",
  "method": "storage:delete",
  "granted": ["storage:read", "storage:write"],
  "required": "storage:delete:/app/important/*"
}

10. Acceptatiecriteria

11. Risico's en aanbevelingen

RisicoImpactMitigatie
60+ handlers = grote migratie-oppervlakHighBatch-migratie per handler-groep. Test suite per groep. Geen big-bang.
Capability-check fouten blokkeren DAppsHighDebug-mode: log warnings i.p.v. errors. Staging environment voor testing.
Identiek gedrag = subtiel verschil = bugHighGolden-output test suite: vergelijk Next.js output met Hono output per handler.
Performance-verschil (Next.js vs Hono)MediumBenchmark suite: vergelijk response-tijden. Hono zou sneller moeten zijn.

12. Verwijzingen

Fase 1D Nog niet geimplementeerd. Vereist: handler-migratie per groep, capability-check integratie, golden-output test suite. Laatste fase: kernel + VAPI vormen de ruggengraat van MAOS.