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
| Endpoint | Methode | Beschrijving | Auth |
/dapps | GET | Lijst van alle geregistreerde DApps | Session cookie |
/dapps/register | POST | Nieuwe DApp registreren | Session + Ed25519 sig |
/dapps/:cid/update | PUT | Bestaande DApp bijwerken | Session + eigenaar |
/dapps/:cid/publish | POST | DApp 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
- 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 uitzonderingen: Ongeldige signature = reject + audit log. Geen fallback.
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
| Tier | Beschrijving | Zichtbaar voor |
0 | Free tier | Alle gebruikers (explorer, basic, pro, gold) |
1 | Pro tier | Basic, pro, gold gebruikers |
2 | Premium tier | Gold 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
- Manifest-validatie: JSON Schema + Ed25519 + CID verificatie
- Ed25519 canonical JSON: gesorteerde keys, geen whitespace
- CID-verificatie: hash-match met bundle inhoud
- Publish-flow: IPFS pin + store registratie + auto-scan trigger
- Tier-filtering: correcte filtering per gebruikersniveau
- Eigenaar-check: update/publish alleen door eigenaar
- Audit logging: ongeldige signatures + ongeautoriseerde pogingen
10. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Ed25519 verificatie complexiteit | High | Gebruik @noble/ed25519 of tweetnacl. Test met bekende testvectors. |
| IPFS-afhankelijkheid voor pinning | High | Multi-provider strategie: eigen Kubo + Pinata/Infura. Fallback: local storage. |
| Auto-scan kan blokkeren bij grote bundles | Medium | Async processing met queue. Geen blocking op publish-endpoint. |
| Canonical JSON inconsistenties | Medium | Test 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.