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

EndpointMethodeBeschrijvingAuth
/api/dappsGETLijst van alle geregistreerde DAppsSession cookie
/api/dapps/:cidGETDApp-details op CIDSession cookie
/api/dapps/registerPOSTNieuwe DApp registrerenSession + Ed25519 sig
/api/dapps/:cid/updatePUTBestaande DApp bijwerkenSession + Ed25519 sig
/api/dapps/:cid/publishPOSTDApp publiceren (IPFS pin + store-registratie)Session + Ed25519 sig
/api/dapps/:cid/deleteDELETEDApp 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

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-groepAantalVoorbeelden
wallet-handlers~15wallet:connect, wallet:disconnect, wallet:sign, wallet:send
storage-handlers~12storage:read, storage:write, storage:list, storage:delete
chain-handlers~10chain:call, chain:send, chain:estimateGas, chain:getBalance
dapp-handlers~8dapp:install, dapp:uninstall, dapp:list, dapp:info
extension-handlers~8extension:connect, extension:queue, extension:sign
vfs-backend-handlers~7vfs:mount, vfs:unmount, vfs:read, vfs:write

2.2 Migratie-principes

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

3.3 Verificatie-flow (on-chain receipt)

StapActieWaar
1VAPI-payment intent van DAppSharedWorker → wallet-DApp
2Gebruiker approve in wallet-DAppWallet-DApp
3Intent-queue → kernel broadcastKernel → blockchain
4Receipt + tx-hash → DAppVAPI-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)

#BeslissingRationaleHerziening
V1Betaalde DApps via VAPI wallet-rail (geen eigen Stripe per DApp)dapp-wallet is enige payment-rail; uniformiteit; minder integratie-oppervlak—
V2Top-up alleen via wallet-DApp (Stripe SEPA/iDEAL)Fiat-to-crypto独自桥 via wallet; daarna alles on-chain—

5.1 Open Grillvragen