API: DApps + VAPI-handlers
DApp registry (register/update/publish) + VAPI-handlers migratie naar Hono • manifest-validatie + Ed25519 verificatie • exact method+path capability checks • status: ontwerp, nog geen code
Kerndefinitie: De API-laag biedt twee pijlers: (1) DApp registry voor het registreren, bijwerken en publiceren van DApps, en (2) VAPI-handlers voor het verwerken van DApp-verzoeken (wallet, storage, chain, extension). Beide worden gemigreerd naar Hono-routes met identiek gedrag als de huidige Next.js implementatie.
1. DApp registry (api/dapps)
1.1 Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/api/dapps | GET | Lijst van alle geregistreerde DApps | Session cookie |
/api/dapps/:cid | GET | DApp-details op CID | Session cookie |
/api/dapps/register | POST | Nieuwe DApp registreren | Session + Ed25519 sig |
/api/dapps/:cid/update | PUT | Bestaande DApp bijwerken | Session + Ed25519 sig |
/api/dapps/:cid/publish | POST | DApp publiceren (IPFS pin + store-registratie) | Session + Ed25519 sig |
/api/dapps/:cid/delete | DELETE | DApp verwijderen (soft-delete) | Session + eigenaar |
1.2 Manifest-validatie (register + update)
Ontvangen manifest.json
│
├── 1. JSON Schema validatie
│ ├── name (string, verplicht)
│ ├── cid (string, verplicht)
│ ├── version (semver, verplicht)
│ ├── minCore (semver, verplicht)
│ ├── tier (0|1|2, verplicht)
│ ├── vapi (string, verplicht)
│ ├── capabilities (object, verplicht)
│ ├── sig (ed25519, verplicht)
│ └── allowlist (string[], optioneel)
│
├── 2. Ed25519-signature verificatie
│ ├── Canonical JSON van manifest (gesorteerde keys, geen whitespace)
│ ├── Signature over canonical JSON
│ └── Pubkey in store-backend (gekoppeld aan publisher)
│
├── 3. CID-verificatie
│ ├── CID matcht met inhoud van bundle
│ └── Hash-integriteit (geen corruptie)
│
└── 4. Status: staged (wacht op auto-scan)
1.3 Ed25519 verificatie
- Canonical JSON: Manifesten worden geverifieerd op basis van canonical-JSON (gesorteerde keys, geen whitespace). Dit voorkomt signature-mismatch door formatting-verschillen.
- Verificatie-timing: Bij register/update (server-side) en bij mount (client-side in SharedWorker).
- Pubkey-beheer: Pubkeys worden opgeslagen in store-backend, gekoppeld aan publisher-accounts.
- Geen ongeldige signatures: Ongeldige signature = reject + audit. Geen uitzonderingen.
1.4 Publish-flow
Publisher: POST /api/dapps/:cid/publish
│
├── 1. CID-resolutie (IPFS)
│
├── 2. Bundle download + hash-verificatie
│
├── 3. Pin bij eigen Kubo + externe providers
│
├── 4. Store-backend registratie
│ ├── huidige CID
│ ├── status: staged
│ ├── tier (uit manifest)
│ ├── minCore (uit manifest)
│ └── publishedAt, updatedAt
│
└── 5. Auto-scan triggeren
│
├── Geen issues → handmatige review → verified
└── Issues gevonden → untrusted
2. VAPI-handlers migratie naar Hono
2.1 Overzicht (60+ handlers)
| Handler-groep | Aantal | Voorbeelden |
| wallet-handlers | ~15 | wallet:connect, wallet:disconnect, wallet:sign, wallet:send |
| storage-handlers | ~12 | storage:read, storage:write, storage:list, storage:delete |
| chain-handlers | ~10 | chain:call, chain:send, chain:estimateGas, chain:getBalance |
| dapp-handlers | ~8 | dapp:install, dapp:uninstall, dapp:list, dapp:info |
| extension-handlers | ~8 | extension:connect, extension:queue, extension:sign |
| vfs-backend-handlers | ~7 | vfs:mount, vfs:unmount, vfs:read, vfs:write |
2.2 Migratie-principes
- Gedrag identiek: Elke Hono-handler retourneert identieke JSON als de huidige Next.js implementatie.
- Capability-check in Worker: Elke VAPI-call wordt gecontroleerd in SharedWorker (niet in de handler).
- Exact method+pad matching: Geen family-matching.
storage:read matcht niet met storage:read:/app/other/.
- Geen shortcuts: Geen
broadcast:true flag voor DApps. Geen directe send.
2.3 Example: wallet:sign handler
// Hono route: /api/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: intent-queue toevoegen
├── Intent: { type: "sign", dappId, wallet, tx }
│
3. Wallet-DApp: toon details + approve/reject
│
4. Approve → kernel sign → receipt
│
5. Reject → blokkeer + audit
2.4 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
3. Betaalde DApps via VAPI-payment (wallet-DApp als enige rail)
BESLIST: Betaalde DApps worden ondersteund via VAPI-payment door wallet-DApp. De dapp-wallet is de enige payment-rail. MAOS draait geen eigen Stripe-integratie per DApp. Funds top-up (storten) uitsluitend via wallet-DApp (Stripe SEPA/iDEAL als top-up-rail), daarna alles on-chain via wallet-queue met approval + gas/daglimiet.
3.1 Betaal-flow (on-chain via wallet-DApp)
DApp: maos.request('vapi:payment', { amount, currency, chain, contract })
│
├── 1. Wallet-DApp toont: bedrag + contract + chain + dapp-id
│
├── 2. Gebruiker approve in wallet-DApp
│ │
│ ├── Wallet heeft saldo? → intent-queue → on-chain betaling
│ │
│ └── Onvoldoende saldo? → top-up flow (wallet-DApp)
│ │
│ ├── Top-up via Stripe SEPA/iDEAL (alleen in wallet-DApp)
│ │
│ └── Na storting → on-chain betaling via intent-queue
│
├── 3. Intent-queue → goedkeuring → kernel broadcast
│
└── 4. Receipt → DApp informed (vapi:payment-result)
3.2 Regels betaalde DApps
- Geen eigen Stripe per DApp: MAOS integreert geen Stripe-direct. Alle betalingen lopen via wallet-DApp als enige payment-rail.
- Top-up alleen via wallet-DApp: Storten (funds) via Stripe SEPA/iDEAL in wallet-DApp. Daarna alles on-chain.
- Wallet-queue met approval: Elke betaling gaat door intent-queue → goedkeuring → pas broadcast. Sign != send.
- Gas/daglimiet: Betaalde DApps vallen onder dezelfde gas-ceiling + daglimiet als andere chain:send operaties.
- Geen auto-sign: Ook bij kleine bedragen = volledige approval flow.
3.3 Verificatie-flow (on-chain receipt)
| Stap | Actie | Waar |
| 1 | VAPI-payment intent van DApp | SharedWorker → wallet-DApp |
| 2 | Gebruiker approve in wallet-DApp | Wallet-DApp |
| 3 | Intent-queue → kernel broadcast | Kernel → blockchain |
| 4 | Receipt + tx-hash → DApp | VAPI-handler |
4. Verwijzingen naar verwante specs
Volgende stap Na akkoord: Hono-routes aanmaken per handler-groep + manifest-schema + Ed25519 verificatie + capability-check in SharedWorker.
5. Beslissingen (VAPI)
| # | Beslissing | Rationale | Herziening |
| V1 | Betaalde DApps via VAPI wallet-rail (geen eigen Stripe per DApp) | dapp-wallet is enige payment-rail; uniformiteit; minder integratie-oppervlak | — |
| V2 | Top-up alleen via wallet-DApp (Stripe SEPA/iDEAL) | Fiat-to-crypto独自桥 via wallet; daarna alles on-chain | — |
5.1 Open Grillvragen
- Vraag 1: Moeten VAPI-handlers ook een versie-beheer bieden (v1/v2), of is backwards-compat via minCore voldoende?
- Vraag 2: Hoe wordt de Ed25519 pubkey van een publisher geverifieerd: via DID, of via centralised store-backend registratie?
- Vraag 3: Wat is het gedrag als een DApp een onbekende VAPI-method aanvraagt: deny + audit, of doorlaten naar optionele handler?