Web3-website bridge

Bridge-contract tussen MAOS kernel en web3-website • maos.fetch allowlist via Worker-proxy • EIP-6963 provider • sessie/wallet-connect • QR-approver • DApp-tiers • status: ontwerp, nog geen code

Kerndefinitie: De web3-website bridge is de verbindingslaag tussen de MAOS kernel (blockchain source-of-truth) en de web3-website (gebruikersinterface). Alles wat de web3-website met de blockchain communiceert loopt door deze bridge. DApps hebben geen directe toegang tot de blockchain — alles via Worker-proxy met allowlist.

1. Bridge-contract architectuur

Web3-website (Next.js / Vite) ──▶ MAOS Kernel (Hono + SharedWorker)
        │                                    │
        │                                    ├── chain:call (lees, vrij)
        │                                    ├── chain:send (schrijf, approval)
        │                                    └── wallet:sign (handtekening, preview)
        │
        └── bridge-contract
            ├── connect (wallet-koppeling)
            ├── sessie (7d heartbeat + revoke)
            ├── QR-approver (mobile als signer)
            └── tier-routing (0/1/2)

1.1 connect (wallet-koppeling)

StapActieWaar
1Web3-website vraagt connectie aan via maos.request('wallet:connect')Bridge-shim in iframe
2SharedWorker filtert EIP-6963 announces (alleen OS-gesigneerde wallets)SharedWorker
3Wallet-keuze tonen aan gebruikerWallet-DApp (Tier-0)
4Selectie vastzetten (freeze) — 1 provider per sessieSharedWorker
5Attest genereren (pubkey + sessie-id + expiratie)Kernel
6Connectie bevestigd → DApp krijgt maos.providerBridge-shim

1.2 sessie (7d heartbeat + revoke)

ParameterWaardeToelichting
Sessie-lifetime7 dagenNa 7d: sessie verlopen, opnieuw inloggen vereist
HeartbeatElke 5 minutenClient stuurt ping. Bij 3 missed: sessie-pauze
Instant revokeDirectGebruiker kan op elk moment intrekken
Hibernate trigger15 min inactiviteitSnapshot + suspend, geen revoke

1.3 QR-approver (mobile als signer)

QR-login stelt gebruikers in staat om sessies te authenticeren met hun mobiele apparaat als approver+signer.

Desktop/Mobile browser ──▶ /auth/qr-login ──▶ genereer challenge (32 bytes, 120s expiry)
        │
        │ QR-code: { type:"maos-session", challenge, sessionId, exp }
        │
Mobile MAOS-app ──scan QR──▶ toon sessie-details (device, IP-range, tijd)
        │
        │ User approve ──▶ sign challenge op apparaat (ed25519)
        │
        │ response: { sessionId, signature, pubkey, timestamp }
        │
Desktop browser ──◀── POST /api/auth/session/verify ──◀── server verifieert
        │
        └──▶ sessie aangemaakt: cookie + heartbeat + 7d lifetime
VEILIGHEIDSREGEL: QR-code bevat alleen challenge + sessie-metadata. Nooit private keys, seeds, mnemonics. Handtekening gebeurt op het mobiele apparaat. Private key verlaat het apparaat nooit.

2. maos.fetch allowlist via Worker-proxy

DApps hebben geen directe toegang tot fetch(). Alle netwerkverzoeken lopen door de SharedWorker-proxy met allowlist-check.

2.1 Architectuur

DApp iframe ──maos.fetch(url, opts)──▶ SharedWorker proxy
        │                                    │
        │                                    ├── URL checken tegen manifest.allowlist
        │                                    │
        │                                    ├── Match? ──▶ fetch() uitvoeren ──▶ response terug
        │                                    │
        │                                    └── Geen match? ──▶ deny + audit

2.2 Allowlist-regels

2.3 Toegestane URL-patronen

PatroonVoorbeeldToelichting
https://api.example.com/*https://api.example.com/v1/dataWildcard op pad-niveau
https://ipfs.io/ipfs/*https://ipfs.io/ipfs/bafy…IPFS gateway (alleen private trustless)
wss://stream.example.comwss://stream.example.com/eventsWebSocket (alleen SSE in praktijk)

3. DApp-tiers (0/1/2)

Tier-0 (core gebundeld)
Wallet, settings, permissions. Direct in shell, geen iframe. Volledige kernel-toegang. Updates via core-release.
Tier-1 (signed manifest)
Eigen store, Ed25519-gesigneerd. Iframe + allow-same-origin, preloaded bridge. Reviews + auto-scan vereist.
Tier-2 (untrusted strict)
Default voor alle third-party DApps. Iframe sandbox zonder allow-same-origin. Beperkte capabilities, geen raw fetch, geen wallet:sign zonder step-up.

3.1 Tier-gedrag per capability

CapabilityTier-0Tier-1Tier-2
chain:callAltijdAltijdAltijd (within manifest)
chain:sendAltijdNa approvalNa approval + step-up
wallet:signAltijdNa approvalNa approval + step-up
storage:readAltijdVolgens manifestBeperkt (geen kernel-paden)
storage:writeAltijdVolgens manifestAlleen eigen namespace
network:fetchAltijdAlleen allowlistAlleen allowlist + verificatie

4. Store: staged → verified met auto-scan

Elke DApp begint als staged (openbaar zichtbaar), wordt verified na auto-scan + handmatige review, of untrusted bij deny-list hits.

4.1 Auto-scan deny-list

CategoriePatroonGevolg
eval / Function()eval(...), new Function(...)Direct untrusted
innerHTML.innerHTML =, document.write(...)Direct untrusted
remote fetchfetch(...) naar niet-allowlist URLDirect untrusted
inline remote scripts<script src="https://…">Direct untrusted

4.2 Statusovergangen

publish (staged) ──▶ auto-scan ──┬── geen issues ──▶ handmatige review ──┬── goedgekeurd ──▶ verified
                                  │                                      │
                                  └── issues gevonden ──────────────────-─┘── afgewezen ──▶ untrusted
                                                                                              │
                                                                  handmatige review ──────────-─┘── alsnog goedgekeurd ──▶ verified

5. Sessie-interactie: web3-website ↔ kernel

5.1 Connect-flow (samenvatting)

┌─────────────────────────────────────────────────────────────────┐
│                     WEB3-WEBSITE CONNECT-FLOW                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Web3-website: maos.request('wallet:connect')                │
│     ↓                                                           │
│  2. SharedWorker: EIP-6963 filteren (alleen OS-gesigneerd)      │
│     ↓                                                           │
│  3. Wallet-DApp: keuze tonen + freeze na selectie               │
│     ↓                                                           │
│  4. Attest genereren (pubkey + sessie-id + exp)                 │
│     ↓                                                           │
│  5. Connectie bevestigd → maos.provider beschikbaar             │
│     ↓                                                           │
│  6. Heartbeat elke 5 min (3 missed = pause)                     │
│     ↓                                                           │
│  7. 15 min inactief → hibernate (snapshot + suspend)            │
│     ↓                                                           │
│  8. Bij logout/revoke: instant kill (cookie + token delete)     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5.2 QR-login flow (mobile approver+signer)

┌─────────────────────────────────────────────────────────────────┐
│                     QR-LOGIN APPROVER-FLOW                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Desktop/Mobile: /auth/qr-login → challenge (32B, 120s)      │
│     ↓                                                           │
│  2. QR-code toont: { type, challenge, sessionId, exp }          │
│     ↓                                                           │
│  3. Mobile MAOS-app scan → sessie-details → user approve        │
│     ↓                                                           │
│  4a. Mobile sessie: sign op apparaat (ed25519)                  │
│  4b. Desktop sessie: push naar extension → extension sign         │
│     ↓                                                           │
│  5. POST /api/auth/session/verify (pubkey + signature)           │
│     ↓                                                           │
│  6. Server verifieert → sessie aangemaakt (7d)                  │
│     ↓                                                           │
│  7. 7d sessie-lifetime + 5min heartbeat + 15min hibernate       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

6. Verwijzingen naar verwante specs

Volgende stap Na akkoord: implementatie van bridge-contract in SharedWorker + maos.fetch proxy + QR-login API-route + tier-routing in capability-check.

7. Beslissingen (web3-website bridge)

#BeslissingRationaleHerziening
WB1Wallet-allowlist signed-only via signed config-fileUUID-dedup en rdns onbetrouwbaar; dynamisch beheer veiliger dan hardcoded—

7.1 Open Grillvragen