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-groep | Aantal | Voorbeelden | Kernel-afhankelijk |
| wallet-handlers | ~15 | wallet:connect, wallet:disconnect, wallet:sign, wallet:send, wallet:signMessage, wallet:getBalance, wallet:switchChain, wallet:addToken | Ja (wallet service) |
| storage-handlers | ~12 | storage:read, storage:write, storage:list, storage:delete, storage:mkdir, storage:stat, storage:copy, storage:move | Ja (storage service) |
| chain-handlers | ~10 | chain:call, chain:send, chain:estimateGas, chain:getBalance, chain:getBlock, chain:getTxReceipt, chain:encode | Ja (chain service) |
| dapp-handlers | ~8 | dapp:install, dapp:uninstall, dapp:list, dapp:info, dapp:update, dapp:enable, dapp:disable | Ja (kernel events) |
| extension-handlers | ~8 | extension:connect, extension:queue, extension:sign, extension:disconnect, extension:status | Ja (extension service) |
| vfs-backend-handlers | ~7 | vfs:mount, vfs:unmount, vfs:read, vfs:write, vfs:list, vfs:stat | Ja (VFS service) |
3. Migratie-principes
- Gedrag identiek: Elke Hono-handler retourneert identieke JSON als de huidige Next.js implementatie. Geen breaking changes.
- Capability-check in Worker: Elke VAPI-call wordt gecontroleerd in SharedWorker (niet in de handler). De handler vertrouwt op de Worker.
- Exact method+pad matching:
storage:read matcht niet met storage:read:/app/other/. Familie-matching is verboden.
- Geen shortcuts: Geen
broadcast:true flag voor DApps. Geen directe send. Alles via intent-queue.
- Capability-grants: Elke DApp heeft een manifest met
grants: ["method:path"]. Alleen toegestande combinaties worden doorgelaten.
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
| Grant | VAPI call | Match | Reden |
wallet:sign | wallet:sign | Ja | Exacte method match |
wallet:sign | wallet:send | Nee | Andere method |
storage:read:/app/* | storage:read:/app/file.txt | Ja | Wildcard match |
storage:read:/app/* | storage:read:/other/file.txt | Nee | Pad niet in scope |
chain:call:0x1234* | chain:call:0x1234abcd | Ja | Contract-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
- 60+ handlers gemigreerd naar Hono met identiek gedrag
- Capability-check in SharedWorker (niet in handler)
- Exact method+pad matching: geen family-matching
- Geen shortcuts: geen broadcast:true, geen directe send
- Intent-queue: alle mutaties via queue met goedkeuring
- Audit logging: elke VAPI-call gelogd (method, dappId, resultaat)
- Kernel-context: elke handler heeft toegang tot kernel via middleware
11. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| 60+ handlers = grote migratie-oppervlak | High | Batch-migratie per handler-groep. Test suite per groep. Geen big-bang. |
| Capability-check fouten blokkeren DApps | High | Debug-mode: log warnings i.p.v. errors. Staging environment voor testing. |
| Identiek gedrag = subtiel verschil = bug | High | Golden-output test suite: vergelijk Next.js output met Hono output per handler. |
| Performance-verschil (Next.js vs Hono) | Medium | Benchmark 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.