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

VeldTypeValidatieBeschrijving
namestringLowercase kebab-case, 3-64 charsUnieke naam. Pipeline-validatie: lowercase, geen spaties, geen speciale tekens behalve -
cidstringCIDv1 prefix bafy, 55+ charsIPFS CID van de bundle. Bij register wordt de CID geverifieerd tegen de inhoud.
versionstringSemver (major.minor.patch)Versie van de DApp. Bij update moet versie hoger zijn dan huidige.
minCorestringSemver (major.minor.patch)Minimale MAOS-core versie. Kernel weigert mount bij mismatch.
tierinteger0, 1, of 2Trust-tier. Tier-0 alleen voor systeem-DApps. Tier-1 vereist verified-status.
vapistringN.x formaatVAPI-versie. "1.x" = kernel blijft 1 minor backwards compatible.
capabilitiesobjectMinimaal 1 capabilityGevraagde permissies. Boolean = aan/uit, array = specifieke paden.
sigstringed25519:base64Ed25519 handtekening over canonical JSON van het manifest (zonder sig-veld).

3. Optionele velden

VeldTypeStandaardBeschrijving
allowliststring[][]Toegestane URLs voor network:fetch. Bij ontbreken: geen externe fetch toegestaan.
storage.maxBytesinteger5.242.880 (5MB)Maximale opslag. Minimum 1MB, maximum 50MB.
network.timeoutinteger5.000 msNetwerk-timeout per verzoek.
network.retryCountinteger2Aantal 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

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)

6. Verificatie-momenten

MomentWaarWatBij falen
RegisterServer (Hono)JSON Schema + Ed25519 + CIDReject + 400 response
UpdateServer (Hono)JSON Schema + Ed25519 + CID + versie-bumpReject + 400 response
MountSharedWorkerEd25519 + minCore checkDApp niet mounten
Capability-checkSharedWorkerMethod+pad match met manifest-grants403 + 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

#CriteriaMeting
AC-1JSON Schema validatie weigert manifests met ontbrekende verplichte veldenTest met incomplete manifests
AC-2Ed25519 verificatie faalt bij ongeldige of ontbrekende sigTest met fake/manipulated sig
AC-3Canonical JSON is deterministisch (zelfde input = zelfde output)Test met verschillende JSON-formattering
AC-4CID-verificatie detecteert corruptie (hash mismatch)Test met gemanipuleerde bundle
AC-5Tier-0 DApps vereisen ook een geldige sigTest: geen uitzonderingen
AC-6Capability-check blokkeert ongeautoriseerde method+pad combinatiesTest met niet-toegestane paden
AC-7Manifest met additionalProperties wordt verworpenTest met onbekende velden

9. Risico's en aanbevelingen

RisicoImpactAanbeveling
Canonical JSON verschilt tussen implementatieshoogExacte sorteerregels documenteren + referentie-implementatie in TypeScript
Private key van publisher wordt gecompromitteerdhoogKey rotation via /api/dapps/:cid/rotate-key + onmiddellijke her-signing
CID-brute-force aanval (fake CID die hash matcht)laagSHA-256 is collision-resistant. CIDv1 = veilig genoeg.
Manifest-manipulatie na signing (canonical JSON wijziging)hoogEd25519 verificatie bij elke stap (register, update, mount)
Capacities worden te ruim gedeclareerdmiddelAuto-scan detecteert overbodige capabilities + handmatige review

10. Verwijzingen naar verwante specs

Volgende stap Na akkoord: referentie-implementatie van canonical JSON + JSON Schema validatie in Hono-middleware + Ed25519 verify-functie in SharedWorker.

11. Grillvragen