DApp manifest schema
JSON Schema specificatie • verplichte + optionele velden • Ed25519 signature verificatie • CID-verificatie • canonical JSON voor signing • status: ontwerp, nog geen code
Kerndefinitie: Het DApp manifest is een JSON-bestand dat alle metadata van een DApp bevat: naam, CID, versie, tier, capabilities en handtekening. Het wordt geverifieerd bij vier momenten: register (server), update (server), mount (SharedWorker), en bij elke capability-check. Ed25519 signing over canonical JSON voorkomt manipulatie.
1. JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://maos.dev/schemas/dapp-manifest-v1.json",
"type": "object",
"required": ["name", "cid", "version", "minCore", "tier", "vapi", "capabilities", "sig"],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$",
"description": "Unieke naam van de DApp (lowercase, kebab-case)"
},
"cid": {
"type": "string",
"pattern": "^bafy[a-zA-Z0-9]{50,}$",
"description": "IPFS CIDv1 van de DApp-bundle"
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$",
"description": "Semver versie van de DApp"
},
"minCore": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+$",
"description": "Minimale MAOS-core versie (semver)"
},
"tier": {
"type": "integer",
"enum": [0, 1, 2],
"description": "Trust-tier: 0=systeem, 1=verified, 2=third-party"
},
"vapi": {
"type": "string",
"pattern": "^\\d+\\.x$",
"description": "VAPI-versie (backwards compatible)"
},
"capabilities": {
"type": "object",
"description": "Gevraagde permissies (method: waarde)",
"additionalProperties": {
"oneOf": [
{ "type": "boolean" },
{
"type": "array",
"items": { "type": "string" }
}
]
}
},
"sig": {
"type": "string",
"pattern": "^ed25519:[A-Za-z0-9+/]+=*$",
"description": "Ed25519 handtekening over canonical JSON"
},
"allowlist": {
"type": "array",
"items": { "type": "string", "format": "uri" },
"description": "Toegestane URLs voor network:fetch"
},
"storage": {
"type": "object",
"properties": {
"maxBytes": {
"type": "integer",
"minimum": 1048576,
"maximum": 52428800,
"description": "Maximale storage in bytes (1MB-50MB)"
}
}
},
"network": {
"type": "object",
"properties": {
"timeout": {
"type": "integer",
"minimum": 1000,
"maximum": 30000,
"description": "Netwerk-timeout in ms"
},
"retryCount": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "Aantal retries"
}
}
}
}
}
2. Verplichte velden
| Veld | Type | Validatie | Beschrijving |
name | string | Lowercase kebab-case, 3-64 chars | Unieke naam. Pipeline-validatie: lowercase, geen spaties, geen speciale tekens behalve - |
cid | string | CIDv1 prefix bafy, 55+ chars | IPFS CID van de bundle. Bij register wordt de CID geverifieerd tegen de inhoud. |
version | string | Semver (major.minor.patch) | Versie van de DApp. Bij update moet versie hoger zijn dan huidige. |
minCore | string | Semver (major.minor.patch) | Minimale MAOS-core versie. Kernel weigert mount bij mismatch. |
tier | integer | 0, 1, of 2 | Trust-tier. Tier-0 alleen voor systeem-DApps. Tier-1 vereist verified-status. |
vapi | string | N.x formaat | VAPI-versie. "1.x" = kernel blijft 1 minor backwards compatible. |
capabilities | object | Minimaal 1 capability | Gevraagde permissies. Boolean = aan/uit, array = specifieke paden. |
sig | string | ed25519:base64 | Ed25519 handtekening over canonical JSON van het manifest (zonder sig-veld). |
3. Optionele velden
| Veld | Type | Standaard | Beschrijving |
allowlist | string[] | [] | Toegestane URLs voor network:fetch. Bij ontbreken: geen externe fetch toegestaan. |
storage.maxBytes | integer | 5.242.880 (5MB) | Maximale opslag. Minimum 1MB, maximum 50MB. |
network.timeout | integer | 5.000 ms | Netwerk-timeout per verzoek. |
network.retryCount | integer | 2 | Aantal retries bij netwerkfouten. |
REGEL: Optionele velden met defaults worden automatisch ingevuld bij ontbreken. De publisher kan ze overschrijven binnen de toegestane ranges.
4. Ed25519 signature verificatie
4.1 Signing-flow
Publisher: maos sign manifest.json
│
├── 1. Canonical JSON maken
│ ├── Sorteer alle keys alfabetisch (diep)
│ ├── Verwijder whitespace
│ ├── Verwijder het "sig"-veld
│ └── Resultaat: string (canonical JSON)
│
├── 2. Ed25519 sign over canonical JSON
│ ├── Private key van publisher
│ └── Resultaat: base64-gecodeerde signature
│
├── 3. Sig toevoegen aan manifest
│ └── "sig": "ed25519:BASE64..."
│
└── 4. Manifest + sig versturen naar server
4.2 Verificatie-flow
Server/SharedWorker ontvangt manifest
│
├── 1. JSON Schema validatie
│ └── Alle verplichte velden aanwezig + types correct?
│
├── 2. Canonical JSON maken
│ ├── Sorteer alle keys alfabetisch (diep)
│ ├── Verwijder whitespace
│ ├── Sla het "sig"-veld over
│ └── Resultaat: dezelfde string als bij signing
│
├── 3. Sig extraheren
│ ├── "sig": "ed25519:BASE64..."
│ └── Decodeer base64 → bytes
│
├── 4. Pubkey ophalen
│ ├── Server: uit store-backend (gekoppeld aan publisher)
│ └── SharedWorker: uit opgeslagen configuratie
│
├── 5. Ed25519 verify
│ ├── verify(canonicalJSON, signature, pubkey)
│ ├── Geldig? → door naar volgende stap
│ └── Ongeldig? → reject + audit + event
│
└── 6. CID-verificatie (zie sectie 5)
4.3 Canonical JSON regels
- Keys sorteren: Alfabetisch, diep (genest).
{"b":1,"a":2} → {"a":2,"b":1}.
- Geen whitespace: Geen spaties, tabs, newlines tussen keys/values.
- Geen wijzigingen: Waarden blijven exact zoals in het origineel.
- Sig-veld overslaan: Het
"sig"-veld wordt niet opgenomen in de canonical JSON.
- Implementatie:
JSON.stringify(Object.fromEntries(Object.entries(manifest).filter(([k]) => k !== 'sig').sort(([a],[b]) => a.localeCompare(b))))
VEILIGHEIDSREGEL: Ed25519 is niet optioneel. Elk manifest zonder geldige sig wordt verworpen. Er zijn geen uitzonderingen, ook niet voor tier-0 systeem-DApps.
5. CID verificatie
5.1 CID-check bij register/update
CID-verificatie (server-side)
│
├── 1. CID parsen
│ ├── CIDv1 formaat (bafy...)
│ └── Multihash extraheren
│
├── 2. Bundle downloaden via IPFS
│ ├── Eigen Kubo-node (preferentie)
│ └── Fallback: pinning-provider
│
├── 3. Hash berekenen
│ ├── SHA-256 van gedownloade bundle
│ └── Vergelijk met CID-multihash
│
├── 4. Match?
│ ├── Ja → CID geldig, door naar pin
│ └── Nee → reject: "CID mismatch, mogelijke corruptie"
│
└── 5. Bundle-structuur checken
├── manifest.json aanwezig?
├── index.html aanwezig?
└── Geen onverwachte bestanden?
5.2 CID-check bij mount (client-side)
- Tijdstip: Bij elke DApp-mount in SharedWorker.
- Methode: CID is de cache-key. SW haalt content op via verified-fetch. Hash-verificatie bij elke stap.
- Bij mismatch: Content niet laden, DApp niet mounten, audit-log schrijven.
6. Verificatie-momenten
| Moment | Waar | Wat | Bij falen |
| Register | Server (Hono) | JSON Schema + Ed25519 + CID | Reject + 400 response |
| Update | Server (Hono) | JSON Schema + Ed25519 + CID + versie-bump | Reject + 400 response |
| Mount | SharedWorker | Ed25519 + minCore check | DApp niet mounten |
| Capability-check | SharedWorker | Method+pad match met manifest-grants | 403 + audit |
7. Voorbeeld manifest
{
"name": "crypto-wallet-ext",
"cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
"version": "2.1.0",
"minCore": "1.0.0",
"tier": 2,
"vapi": "1.x",
"capabilities": {
"wallet:sign": true,
"storage:read": ["/app/crypto-wallet-ext/*"],
"network:fetch": [
"https://api.coingecko.com",
"https://rpc.ankr.com/eth"
]
},
"sig": "ed25519:k7G2hSz1x4d3qR8...",
"allowlist": [
"https://api.coingecko.com",
"https://rpc.ankr.com/eth"
],
"storage": {
"maxBytes": 10485760
},
"network": {
"timeout": 10000,
"retryCount": 3
}
}
8. Acceptatiecriteria
| # | Criteria | Meting |
| AC-1 | JSON Schema validatie weigert manifests met ontbrekende verplichte velden | Test met incomplete manifests |
| AC-2 | Ed25519 verificatie faalt bij ongeldige of ontbrekende sig | Test met fake/manipulated sig |
| AC-3 | Canonical JSON is deterministisch (zelfde input = zelfde output) | Test met verschillende JSON-formattering |
| AC-4 | CID-verificatie detecteert corruptie (hash mismatch) | Test met gemanipuleerde bundle |
| AC-5 | Tier-0 DApps vereisen ook een geldige sig | Test: geen uitzonderingen |
| AC-6 | Capability-check blokkeert ongeautoriseerde method+pad combinaties | Test met niet-toegestane paden |
| AC-7 | Manifest met additionalProperties wordt verworpen | Test met onbekende velden |
9. Risico's en aanbevelingen
| Risico | Impact | Aanbeveling |
| Canonical JSON verschilt tussen implementaties | hoog | Exacte sorteerregels documenteren + referentie-implementatie in TypeScript |
| Private key van publisher wordt gecompromitteerd | hoog | Key rotation via /api/dapps/:cid/rotate-key + onmiddellijke her-signing |
| CID-brute-force aanval (fake CID die hash matcht) | laag | SHA-256 is collision-resistant. CIDv1 = veilig genoeg. |
| Manifest-manipulatie na signing (canonical JSON wijziging) | hoog | Ed25519 verificatie bij elke stap (register, update, mount) |
| Capacities worden te ruim gedeclareerd | middel | Auto-scan detecteert overbodige capabilities + handmatige review |
10. Verwijzingen naar verwante specs
- DApp overzicht — Tiers, levenscyclus, communicatie
- DApp lifecycle — Mount, active, suspend, resume, destroy
- API: DApps + VAPI — Registry, handlers, capability-check
- Container-spec — <maos-app>, iframe, bridge-shim
- Security enforcement — Permission enforcement, rate-limiting
- IPFS pinning — Multi-provider pin-strategie
Volgende stap Na akkoord: referentie-implementatie van canonical JSON + JSON Schema validatie in Hono-middleware + Ed25519 verify-functie in SharedWorker.
11. Grillvragen
- Vraag 1: Moet het manifest ook een
repository-veld bevatten (URL naar broncode) voor transparantie, of is de CID-volledigheid voldoende?
- Vraag 2: Hoe wordt key-rotation geïmplementeerd: via nieuw manifest met
rotateKey-veld, of via apart server-endpoint?
- Vraag 3: Moet
minCore ook een maximum versie ondersteunen ("minCore": "1.0.0", "maxCore": "2.0.0") voor forward-compatibiliteit?