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)
| Stap | Actie | Waar |
| 1 | Web3-website vraagt connectie aan via maos.request('wallet:connect') | Bridge-shim in iframe |
| 2 | SharedWorker filtert EIP-6963 announces (alleen OS-gesigneerde wallets) | SharedWorker |
| 3 | Wallet-keuze tonen aan gebruiker | Wallet-DApp (Tier-0) |
| 4 | Selectie vastzetten (freeze) — 1 provider per sessie | SharedWorker |
| 5 | Attest genereren (pubkey + sessie-id + expiratie) | Kernel |
| 6 | Connectie bevestigd → DApp krijgt maos.provider | Bridge-shim |
1.2 sessie (7d heartbeat + revoke)
| Parameter | Waarde | Toelichting |
| Sessie-lifetime | 7 dagen | Na 7d: sessie verlopen, opnieuw inloggen vereist |
| Heartbeat | Elke 5 minuten | Client stuurt ping. Bij 3 missed: sessie-pauze |
| Instant revoke | Direct | Gebruiker kan op elk moment intrekken |
| Hibernate trigger | 15 min inactiviteit | Snapshot + 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
- Manifest-gebaseerd: Elke DApp specificeert in
manifest.allowlist welke URLs benaderd mogen worden.
- Exact match: Geen wildcard-matching voor het complete pad.
https://api.example.com matcht niet met https://api.example.com/v2 tenzij expliciet opgenomen.
- Geen raw fetch: DApp heeft geen toegang tot
window.fetch, XMLHttpRequest, of WebSocket.
- Proxy-cache: Worker-proxy kan responses cachen (immutable CIDs, 30s TTL voor mutables).
- CORS: Worker-proxy regelt CORS headers. DApp hoeft zich geen zorgen te maken over CORS-configuratie.
- Signed-only wallet-allowlist: BESLIST: Wallet-providers worden gefilterd via een dynamisch signed config-file (niet hardcoded). Alleen OS-gesigneerde providers worden getoond. Unsigned providers worden geblokkeerd + audit-log. UUID-dedup en rdns worden niet vertrouwd voor verificatie.
2.3 Toegestane URL-patronen
| Patroon | Voorbeeld | Toelichting |
https://api.example.com/* | https://api.example.com/v1/data | Wildcard op pad-niveau |
https://ipfs.io/ipfs/* | https://ipfs.io/ipfs/bafy… | IPFS gateway (alleen private trustless) |
wss://stream.example.com | wss://stream.example.com/events | WebSocket (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
| Capability | Tier-0 | Tier-1 | Tier-2 |
chain:call | Altijd | Altijd | Altijd (within manifest) |
chain:send | Altijd | Na approval | Na approval + step-up |
wallet:sign | Altijd | Na approval | Na approval + step-up |
storage:read | Altijd | Volgens manifest | Beperkt (geen kernel-paden) |
storage:write | Altijd | Volgens manifest | Alleen eigen namespace |
network:fetch | Altijd | Alleen allowlist | Alleen 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
| Categorie | Patroon | Gevolg |
| eval / Function() | eval(...), new Function(...) | Direct untrusted |
| innerHTML | .innerHTML =, document.write(...) | Direct untrusted |
| remote fetch | fetch(...) naar niet-allowlist URL | Direct 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)
| # | Beslissing | Rationale | Herziening |
| WB1 | Wallet-allowlist signed-only via signed config-file | UUID-dedup en rdns onbetrouwbaar; dynamisch beheer veiliger dan hardcoded | — |
7.1 Open Grillvragen
- Vraag 1: Moet de web3-website ook een
chain:read (= chain:call) bridge bieden voor niet-DApp context (bijv. wallet-overzicht), of alleen voor DApps in iframes?
- Vraag 3: Wat is het gedrag als een Tier-2 DApp een
network:fetch aanvraagt naar een URL die niet in de allowlist staat: deny + audit, of deny + melding aan gebruiker?