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

TierNaamHerkomstSandboxCapabilities
Tier-0SysteemIngebouwd (wallet, settings, permissions, boot)Geen iframe, direct in shellVolledig (kernel-level)
Tier-1VerifiedEigen store, gesigneerd + auditIframe + allow-same-originVolledig volgens manifest
Tier-2Third-partyExterne 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

VanNaarVoorwaarde
registeredstagedAutomatisch na succesvolle upload
stagedscanningAuto-scan gestart
scanningverifiedGeen deny-list hits + handmatige review goedgekeurd
scanninguntrustedDeny-list hits gevonden
untrustedverifiedHandmatige review + eventuele code-wijzigingen
verifiedpublishedIPFS pin voltooid + store-registratie
publishedmountedDApp 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 }
}
VeldTypeVerplichtBeschrijving
namestringJaUnieke naam van de DApp
cidstringJaIPFS CID van de bundle
versionsemverJaVersie van de DApp
minCoresemverJaMinimale MAOS-core versie
tier0|1|2JaTrust-tier (bepaalt sandbox + capabilities)
vapistringJaVAPI-versie ("1.x" = backwards compatible)
capabilitiesobjectJaGevraagde permissies (method + pad)
sigstringJaEd25519 handtekening over canonical JSON
allowliststring[]NeeToegestane URLs voor network:fetch
storageobjectNeeStorage-limieten (maxBytes)
networkobjectNeeNetwerk-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

StapActieWaar
1DApp roept window.maos.request(method, params)Iframe (DApp-context)
2SDK-shim verstuurt postMessage via MessageChannelIframe → <maos-app>
3<maos-app> forward naar SharedWorkerMain-thread → SharedWorker
4Capability-check: method+pad match met manifest-grantsSharedWorker
5Rate-limit check (multi-tier)SharedWorker
6Door naar kernel-handler (Hono)SharedWorker → Kernel
7Resultaat retour via MessageChannelKernel → 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

StatusBetekenisTierZichtbaar
stagedPas gepubliceerd, wacht op scanTier-2 (default)Ja, in store
verifiedAuto-scan + review goedgekeurdTier-1 (na goedkeuring)Ja, prominent
untrustedIssues gevonden, niet goedgekeurdTier-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

#CriteriaMeting
AC-1Elke DApp heeft een geldig manifest met alle verplichte veldenJSON Schema validatie geslaagd
AC-2Tier-0 DApps hebben geen iframe-sandboxDirect in shell, geen <iframe>
AC-3Tier-2 DApps hebben strict sandbox zonder allow-same-originiframe attributen gecontroleerd
AC-4Elke VAPI-call wordt gecontroleerd op capabilities403 bij ongeautoriseerde call
AC-5SharedWorker leeft bij open tabs (niet per tab) één SharedWorker voor meerdere tabs
AC-6Store toont alleen geregistreerde DAppsGeen ongeldige DApps in catalogus
AC-7Publish-flow doorloopt alle stappen (register → scan → verify → pin → mount)Volledige keten getest

8. Risico's en aanbevelingen

RisicoImpactAanbeveling
Tier-2 DApp omzeilt sandbox via postMessagehoogMessageChannel port = credential. Bij intrekken: port.close() + iframe reload
SharedWorker crash verliest alle DApp-sessiesmiddelAuto-restart via ProcessAutoRestart + sessie-herstel via VFS
Store toont malware na publicatie voor scanhoogStaged = beperkte capabilities, pas volledig na verified
Capability-check faalt door verkeerde manifest-matchmiddelExact method+pad matching, geen family-matching
10k+ DApps overloaden SharedWorkermiddelMulti-tier rate-limiter (500/100/100 req/min)

9. Verwijzingen naar verwante specs

Volgende stap Na akkoord: manifest-schema uitwerken (JSON Schema + Ed25519 verificatie) + lifecycle-spec (mount/suspend/resume/destroy) + store-catalog integratie.

10. Grillvragen