DApp overzicht
Tiersysteem (0/1/2) • volledige levenscyclus register t/m mount • manifest als vertrouwensbasis • SharedWorker-communicatie • Store-integratie • status: ontwerp, nog geen code
Kerndefinitie: Een DApp in MAOS is een content-addressed bundle (IPFS CID) met een gesigneerd manifest dat capabilities declareert. DApps worden geclassificeerd op basis van vertrouwen (tier) en communiceren uitsluitend via de SharedWorker VAPI-router. De Store biedt een uniform publicatie- en ontdekkingskanaal.
1. Architectuur-overzicht
┌─────────────────────────────────────────────────────────────┐
│ MAOS Shell │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Tier-0 │ │ Tier-1 │ │ Tier-2 │ │
│ │ Systeem │ │ Verified │ │ Third- │ │
│ │ │ │ │ │ Party │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SharedWorker VAPI-router │ │
│ │ capability-check + rate-limit + session-manager │ │
│ └──────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼──────────────────────────────┐ │
│ │ Kernel / Hono │ │
│ │ wallet / storage / chain / extension handlers │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌────────────────────────────┐ │
│ │ Store (catalogus) │ │ IPFS (pin + gateway) │ │
│ │ register/publish │ │ verified-fetch + Helia │ │
│ └──────────────────────┘ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
2. Trust-tiers
| Tier | Naam | Herkomst | Sandbox | Capabilities |
| Tier-0 | Systeem | Ingebouwd (wallet, settings, permissions, boot) | Geen iframe, direct in shell | Volledig (kernel-level) |
| Tier-1 | Verified | Eigen store, gesigneerd + audit | Iframe + allow-same-origin | Volledig volgens manifest |
| Tier-2 | Third-party | Externe publish (default, 10k-schaal) | Iframe strict sandbox="allow-scripts allow-popups" | Beperkt, via capabilities |
2.1 Tier-gedrag
Tier-0: Systeem
Wallet, settings, permissions, boot. Direct in shell, geen iframe. Vite-code + handmatige review. Kernel-level permissions: storage:read, storage:write, wallet:sign, chain:call.
Tier-1: Verified
Eigen store, Ed25519-gesigneerd + auto-scan + handmatige review. Iframe met allow-same-origin. Preloaded bridge. SW-cache. Volledige capabilities volgens manifest.
Tier-2: Third-party (default)
Iframe strict sandbox zonder allow-same-origin. Opaque origin. Alles via Worker-capabilities. Beperkte network-access. Waarschuwing bij gebruiker. network:fetch alleen naar manifest-allowlist.
3. DApp levenscyclus
register ──▶ stage ──▶ scan ──▶ verify ──▶ publish ──▶ mount
│ │ │ │ │ │
│ │ │ │ │ └── DApp draait in iframe
│ │ │ │ │ SharedWorker port actief
│ │ │ │ │
│ │ │ │ └── IPFS pin + store-registratie
│ │ │ │ status: published
│ │ │ │
│ │ │ └── Handmatige review (min. 1 reviewer)
│ │ │ status: verified
│ │ │
│ │ └── Automatische scan (deny-list, CSP, bundle)
│ │ status: scanning
│ │
│ └── Openbaar zichtbaar in store
│ status: staged (default tier-2)
│
└── Publisher uploadt manifest + bundle
status: registered
3.1 Statusovergangen
| Van | Naar | Voorwaarde |
registered | staged | Automatisch na succesvolle upload |
staged | scanning | Auto-scan gestart |
scanning | verified | Geen deny-list hits + handmatige review goedgekeurd |
scanning | untrusted | Deny-list hits gevonden |
untrusted | verified | Handmatige review + eventuele code-wijzigingen |
verified | published | IPFS pin voltooid + store-registratie |
published | mounted | DApp gestart in iframe + SharedWorker port actief |
4. DApp manifest structuur
Het manifest is de vertrouwensbasis van elke DApp. Het wordt gesigneerd met Ed25519 en geverifieerd bij register, update, en mount.
{
"name": "mijn-dapp",
"cid": "bafybeigdyr...",
"version": "1.2.0",
"minCore": "1.0.0",
"tier": 2,
"vapi": "1.x",
"capabilities": {
"storage:read": true,
"wallet:sign": false,
"network:fetch": ["https://api.example.com"]
},
"sig": "ed25519:base64...",
"allowlist": ["https://api.example.com"],
"storage": { "maxBytes": 5242880 },
"network": { "timeout": 5000 }
}
| Veld | Type | Verplicht | Beschrijving |
name | string | Ja | Unieke naam van de DApp |
cid | string | Ja | IPFS CID van de bundle |
version | semver | Ja | Versie van de DApp |
minCore | semver | Ja | Minimale MAOS-core versie |
tier | 0|1|2 | Ja | Trust-tier (bepaalt sandbox + capabilities) |
vapi | string | Ja | VAPI-versie ("1.x" = backwards compatible) |
capabilities | object | Ja | Gevraagde permissies (method + pad) |
sig | string | Ja | Ed25519 handtekening over canonical JSON |
allowlist | string[] | Nee | Toegestane URLs voor network:fetch |
storage | object | Nee | Storage-limieten (maxBytes) |
network | object | Nee | Netwerk-instellingen (timeout, retryCount) |
REGEL: Geen sig = geen mount. Bij mount wordt de sig opnieuw geverifieerd tegen de canonical JSON van het manifest. Ongeldige sig = reject + audit.
5. DApp communicatie via SharedWorker
DApp (iframe) ──postMessage(MessageChannel)──▶ <maos-app> ──▶ SharedWorker
│ │
│ window.maos.request('wallet:sign', {...}) │ capability-check
│ window.maos.fetch('https://...', opts) │ rate-limit
│ window.maos.on('capability-revoked', cb) │ session-manager
│ │
└──────────────────────────────────────────────────┘
5.1 Communicatiepad
| Stap | Actie | Waar |
| 1 | DApp roept window.maos.request(method, params) | Iframe (DApp-context) |
| 2 | SDK-shim verstuurt postMessage via MessageChannel | Iframe → <maos-app> |
| 3 | <maos-app> forward naar SharedWorker | Main-thread → SharedWorker |
| 4 | Capability-check: method+pad match met manifest-grants | SharedWorker |
| 5 | Rate-limit check (multi-tier) | SharedWorker |
| 6 | Door naar kernel-handler (Hono) | SharedWorker → Kernel |
| 7 | Resultaat retour via MessageChannel | Kernel → SharedWorker → Iframe |
5.2 Capability-check detail
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
6. Store integratie
De Store is het ontdekkings- en publicatiekanaal voor DApps. Het biedt een uniforme interface voor het registreren, scannen, reviewen en monteren van DApps.
6.1 Store-states
| Status | Betekenis | Tier | Zichtbaar |
staged | Pas gepubliceerd, wacht op scan | Tier-2 (default) | Ja, in store |
verified | Auto-scan + review goedgekeurd | Tier-1 (na goedkeuring) | Ja, prominent |
untrusted | Issues gevonden, niet goedgekeurd | Tier-2 (strict) | Ja, met waarschuwing |
6.2 Store-publish-flow
Publisher: maos publish
│
├── 1. Vite-build → bundle + manifest.json
│
├── 2. Ed25519-sign over canonical JSON
│
├── 3. POST /api/dapps/register (manifest + sig)
│
├── 4. Server-side validatie
│ ├── JSON Schema check
│ ├── Ed25519 verificatie
│ └── CID-verificatie
│
├── 5. IPFS pin (multi-provider)
│
├── 6. Store-backend registratie
│ status: staged
│
└── 7. Auto-scan triggeren
│
├── Geen issues → handmatige review → verified
└── Issues gevonden → untrusted
7. Acceptatiecriteria
| # | Criteria | Meting |
| AC-1 | Elke DApp heeft een geldig manifest met alle verplichte velden | JSON Schema validatie geslaagd |
| AC-2 | Tier-0 DApps hebben geen iframe-sandbox | Direct in shell, geen <iframe> |
| AC-3 | Tier-2 DApps hebben strict sandbox zonder allow-same-origin | iframe attributen gecontroleerd |
| AC-4 | Elke VAPI-call wordt gecontroleerd op capabilities | 403 bij ongeautoriseerde call |
| AC-5 | SharedWorker leeft bij open tabs (niet per tab) | één SharedWorker voor meerdere tabs |
| AC-6 | Store toont alleen geregistreerde DApps | Geen ongeldige DApps in catalogus |
| AC-7 | Publish-flow doorloopt alle stappen (register → scan → verify → pin → mount) | Volledige keten getest |
8. Risico's en aanbevelingen
| Risico | Impact | Aanbeveling |
| Tier-2 DApp omzeilt sandbox via postMessage | hoog | MessageChannel port = credential. Bij intrekken: port.close() + iframe reload |
| SharedWorker crash verliest alle DApp-sessies | middel | Auto-restart via ProcessAutoRestart + sessie-herstel via VFS |
| Store toont malware na publicatie voor scan | hoog | Staged = beperkte capabilities, pas volledig na verified |
| Capability-check faalt door verkeerde manifest-match | middel | Exact method+pad matching, geen family-matching |
| 10k+ DApps overloaden SharedWorker | middel | Multi-tier rate-limiter (500/100/100 req/min) |
9. Verwijzingen naar verwante specs
- DApp manifest schema — JSON Schema, Ed25519, canonical JSON
- DApp lifecycle — Mount, active, suspend, resume, destroy
- Container-spec — <maos-app>, iframe, bridge-shim
- API: DApps + VAPI — Registry, handlers, capability-check
- Kernel orchestrator — SharedWorker, rate-limiting, sessies
- Store approval + QR-login — Auto-scan, handmatige review
- IPFS pinning — Multi-provider pin-strategie
- IPFS gateway — Verified-fetch, cache-strategie
Volgende stap Na akkoord: manifest-schema uitwerken (JSON Schema + Ed25519 verificatie) + lifecycle-spec (mount/suspend/resume/destroy) + store-catalog integratie.
10. Grillvragen
- Vraag 1: Moet een tier-2 DApp na publicatie direct zichtbaar zijn in de store, of eerst een vertraging van 24 uur (koelteperiode) krijgen?
- Vraag 2: Hoe wordt het geval afgehandeld dat een tier-1 DApp na een update terugvalt naar tier-2 (bijvoorbeeld bij het vinden van nieuwe issues)?
- Vraag 3: Is er een maximum aantal gelijktijdig actieve DApps per gebruiker, of is dat puur een kwestie van resource-budget?