API: DApp registry

Ticket 1B-01 • Bron: src/routes/dapps.ts (gepland) • Status: ontwerp • Risico: hoog (Ed25519 + IPFS)

Kerndefinitie: Vier DApp-routes voor het registreren, bijwerken en publiceren van DApps in de MAOS store. Manifest-validatie met JSON Schema + Ed25519-signatuurverificatie. Publiceren omvat IPFS-pinning + store-backend registratie. Tier-filtering bepaalt welke DApps zichtbaar zijn per gebruikersniveau.

1. Architectuur

Publisher (DApp-developer)
    │
    ├── GET /dapps
    │       └── Lijst van alle geregistreerde DApps
    │           ├── Tier-filtering (optie)
    │           └── Paginering (page, size)
    │
    ├── POST /dapps/register
    │       ├── Ontvang manifest.json + bundle
    │       ├── 1. JSON Schema validatie
    │       ├── 2. Ed25519-signatuur verificatie
    │       ├── 3. CID-verificatie (hash-match)
    │       └── 4. Status: staged (wacht op auto-scan)
    │
    ├── PUT /dapps/:cid/update
    │       ├── Valideer dat publisher == eigenaar
    │       ├── Herhaal manifest-validatie
    │       └── Bijwerk versie + beschrijving
    │
    └── POST /dapps/:cid/publish
            ├── 1. CID-resolutie (IPFS)
            ├── 2. Bundle download + hash-verificatie
            ├── 3. Pin bij Kubo + externe providers
            ├── 4. Store-backend registratie
            └── 5. Auto-scan triggeren

SharedWorker (client-side):
    ├── Manifest Ed25519 verificatie bij mount
    ├── Capability-check per VAPI-call
    └── Tier-filtering bij listing

2. Endpoints

EndpointMethodeBeschrijvingAuth
/dappsGETLijst van alle geregistreerde DAppsSession cookie
/dapps/registerPOSTNieuwe DApp registrerenSession + Ed25519 sig
/dapps/:cid/updatePUTBestaande DApp bijwerkenSession + eigenaar
/dapps/:cid/publishPOSTDApp publiceren (IPFS pin + store)Session + eigenaar

3. Manifest-schema

{
  "name": "string (verplicht)",
  "cid": "string (verplicht) — IPFS Content Identifier",
  "version": "semver (verplicht)",
  "minCore": "semver (verplicht) — minimale MAOS versie",
  "tier": "0|1|2 (verplicht) — 0=free, 1=pro, 2=premium",
  "vapi": "string (verplicht) — VAPI endpoint",
  "capabilities": {
    "grants": ["method:path/prefix", ...]
  },
  "sig": "ed25519-signature (verplicht)",
  "pubkey": "ed25519-pubkey (verplicht)",
  "allowlist": ["wallet-address", ...] (optioneel)
}

4. Manifest-validatie flow

Ontvangen manifest.json
    │
    ├── 1. JSON Schema validatie
    │       ├── name: string, niet leeg
    │       ├── cid: geldige IPFS CID (v0 of v1)
    │       ├── version: semver formát
    │       ├── minCore: semver formát
    │       ├── tier: een van [0, 1, 2]
    │       ├── vapi: niet leeg
    │       ├── capabilities: object met grants array
    │       ├── sig: ed25519 signature (base64)
    │       └── pubkey: ed25519 pubkey (base64)
    │
    ├── 2. Ed25519-signatuur verificatie
    │       ├── Canonical JSON van manifest (gesorteerde keys, geen whitespace)
    │       ├── Signature over canonical JSON bytes
    │       └── 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)

5. Ed25519 verificatie

6. Publish-flow

Publisher: POST /dapps/:cid/publish
    │
    ├── 1. CID-resolutie (IPFS)
    │       └── Kubo RPC: cat CID → bundle bytes
    │
    ├── 2. Bundle download + hash-verificatie
    │       ├── SHA-256 van bundle == CID hash?
    │       └── Nee → reject (corruptie of manipulatie)
    │
    ├── 3. Pin bij eigen Kubo + externe providers
    │       ├── Eigen Kubo node
    │       ├── Pinata / Infura / etc. (configurable)
    │       └── Minimaal 2 providers voor redundancy
    │
    ├── 4. Store-backend registratie
    │       ├── huidige CID
    │       ├── status: staged
    │       ├── tier (uit manifest)
    │       ├── minCore (uit manifest)
    │       └── publishedAt, updatedAt timestamps
    │
    └── 5. Auto-scan triggeren
            │
            ├── Geen issues → handmatige review → verified
            └── Issues gevonden → untrusted

7. Tier-filtering

TierBeschrijvingZichtbaar voor
0Free tierAlle gebruikers (explorer, basic, pro, gold)
1Pro tierBasic, pro, gold gebruikers
2Premium tierGold gebruikers

8. Request / Response voorbeelden

8.1 GET /dapps

GET /dapps?page=1&size=20&tier=0 HTTP/1.1

Response:
{
  "dapps": [
    {
      "cid": "bafybeig...",
      "name": "Wallet DApp",
      "version": "1.2.0",
      "tier": 0,
      "status": "verified",
      "publishedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 45 }
}

8.2 POST /dapps/register

POST /dapps/register HTTP/1.1
Content-Type: multipart/form-data

manifest: { ... manifest.json ... }
bundle:   { ... dapp-bundle.tar.gz ... }

Response:
{
  "cid": "bafybeig...",
  "status": "staged",
  "message": "DApp registered, pending auto-scan"
}

8.3 POST /dapps/:cid/publish

POST /dapps/bafybeig.../publish HTTP/1.1

Response:
{
  "cid": "bafybeig...",
  "status": "staged",
  "pinned": ["kubo", "pinata"],
  "publishedAt": "2025-01-15T10:05:00Z"
}

9. Acceptatiecriteria

10. Risico's en aanbevelingen

RisicoImpactMitigatie
Ed25519 verificatie complexiteitHighGebruik @noble/ed25519 of tweetnacl. Test met bekende testvectors.
IPFS-afhankelijkheid voor pinningHighMulti-provider strategie: eigen Kubo + Pinata/Infura. Fallback: local storage.
Auto-scan kan blokkeren bij grote bundlesMediumAsync processing met queue. Geen blocking op publish-endpoint.
Canonical JSON inconsistentiesMediumTest suite met JSON fixtures. Sorted keys deterministic maken via JSON.stringify(Object.keys(obj).sort()).

11. Verwijzingen

Fase 1B Nog niet geimplementeerd. Ontwerp gebaseerd op dapps-vapi.html + P0-tickets. Vereist: Ed25519 library, IPFS Kubo client, store-backend.