Boot step-machine + LockGate + wallet-unlock + extension trust
Browser-only MUST • wallet-signature = enige unlockbron • LockGate 60s grace • extension = Tier-1 signed • geen WebSocket • status: ontwerp, nog geen code
Besluit in 1 zin: Boot is een sequentieel step-machine met idempotente retry + stray-step deny; unlock gebeurt uitsluitend via wallet-signature (viem recoverMessageAddress); LockGate geeft 60s grace bij refresh daarna hard lock; extensions zijn Tier-1 met signed manifest + minimale grants en communiceren nooit direct, alleen via wallet-DApp queue.
1. Boot step-machine
Elke sessie doorloopt een vaste, sequentiele reeks stappen. Elke stap is idempotent: opnieuw uitvoeren geeft hetzelfde resultaat. Een stap die niet correct volgt op de vorige = stray-step deny.
| Stap | Actie | Succes | Fout |
start | Shell initialiseren, DOM + Workers aanmaken | → step | → restart (max 3x) |
step | Kernmodules laden: SW registreren, SharedWorker starten, vault openen | → verify | → retry (idempotent, max 5x) |
verify | Integriteitscheck: core-bundle hash, SW versie, worker gezondheid | → complete | → retry of fallback (nieuwe SW-claim) |
complete | Shell ready, LockGate wacht op unlock | UI zichtbaar (lock-scherm) | → restart |
start --> step --> verify --> complete --> [LockGate wacht]
| | | |
+- retry -+- retry -+- retry ---+
max 5x per stap, stray-step = deny + audit
1.1 Idempotente retry
- Elke stap registreert een
bootStep in sessionStorage. Bij herlading wordt de laatste succesvolle stap herkend en hervat.
- Stap-fout: wacht 500ms, herhaal. Na 5 mislukkingen: toon foutmelding + audit-log + optie voor handmatige reset.
- Geen stap mag parallel draaien.
step wacht op start-succes, verify op step-succes.
1.2 Stray-step deny
REGEL: Elke VAPI-call of DApp-mount die een stap aanroept buiten de verwachte volgorde wordt geweigerd. Boot-stappen zijn exclusief: er is geen skip-optie.
- Boot-stap-state wordt opgeslagen in een state-machine object (niet in zustand).
- Bij
mount() van een DApp controleert de Worker of bootState === 'complete'. Anders = 403 boot-incomplete.
- Try-out: foutieve states debuggen via
/debug/boot (alleen dev).
2. LockGate (unlock-mechanisme)
Na complete toont de shell een lock-scherm. De gebruiker moet zich authenticeren via hun wallet. Er is geen ander authenticatie-mechanisme.
2.1 Wallet-signature = enige unlockbron
ENIGE BRON: Unlock gebeurt uitsluitend door een wallet-signature. Geen wachtwoord, geen passkey, geen biometrie als fallback. De wallet is de identiteit.
LockGate toont challenge:
{ type: "maos-unlock", sessionId: "...", nonce: random(32), exp: now+120s }
Browser-wallet / MAOS-extension:
1. Sign de challenge-tekst (personal_sign)
2. Stuur { signature, pubkey, timestamp } terug
Kernel verifieert (viem recoverMessageAddress):
recovered = recoverMessageAddress({ message: challengeTekst, signature })
if recovered === userAddress -> unlock
else -> deny + audit
- viem recoverMessageAddress is de enige bron van waarheid. Geen ethers.utils.verifyMessage, geen eigen crypto-implementatie.
- Challenge verloopt na 120 seconden. Nieuwe challenge = nieuwe nonce.
- Geen window.ethereum direct; alles via
maos.request('wallet:sign') → Worker → wallet-DApp queue.
2.2 LockGate 60s grace
| Gebeurtenis | Actie | Reden |
| Tabrefresher / navigatie | 60 seconden grace-period | Voorkomt herhaald unlock bij normaal browsen |
| 60s verlopen zonder unlock | Hard lock: sessie gesloten, ports dicht | Beveiliging tegen onbevoegde toegang |
| Hibernate (15 min inactiviteit) | Snapshot + hard lock direct | RAM-besparing + veiligheid |
| Unlock binnen 60s | Direct hervatten, geen extra verificatie | UX-vriendelijk bij korte onderbrekingen |
refresh/navigatie --> LockGate start 60s timer
|
+-- unlock binnen 60s --> sessie hervat (geen extra check)
|
+-- 60s verlopen --> hard lock: sessie dicht, ports revoke
|
volgende interactie = nieuw unlock vereist
2.3 Foutief gedrag: retries + lockout
| Retry | Gedrag |
| 1-4 | Onmiddellijk opnieuw proberen. Geen extra restrictie. |
| 5e mislukking | 15 minuten lockout. Alle verdere unlock-pogingen geweigerd. |
| Lockout-duur | 15 minuten, gedeeld over alle tabs (SharedWorker houdt staat bij). |
| Na lockout | Reset naar 0 retries. Eerste poging is weer vrij. |
- Audit: elke mislukte unlock: log met
timestamp, recovered, expected, retryCount.
- 5x mislukt in 1 sessie =
unlock-lockout event + wallet-DApp toont waarschuwing.
- Geen brute-force mogelijk: challenge expireert na 120s, retry telt niet mee bij nieuwe challenge.
3. Extension trust model
De MAOS-browser-extensie communiceert nooit direct met DApps of de kernel. Alle communicatie loopt via de wallet-DApp queue (Tier-0). De extensie is een geverifieerde tool, geen onafhankelijke actor.
3.1 Tier-1 signed manifest
{
"name": "MAOS Extension",
"version": "1.0.0",
"type": "extension",
"chromeExtensionId": "abcdefghijklmnopabcdefghijklmnop",
"capabilities": {
"extension:queue": true,
"extension:sign": true
},
"sig": "ed25519:...",
"minCore": "1.0.0"
}
Minimale grants: De extensie vraagt alleen extension:queue (intent-queue toegang) en extension:sign (handtekening zetten). Geen wallet:send, geen storage:read, geen network:fetch. De extensie is een signer, geen browser.
3.2 Chrome Extension ID allowlist + per-versie sig-check
- 1 ID per release: Elke versie van de extensie heeft een unieke Chrome Extension ID. Deze staat in het signed manifest.
- Signature check: SharedWorker verifieert bij elke communicatie of het chrome.runtime.id overeenkomt met het gesigneerde manifest.
- Wijziging = re-attest: Bij wijziging van de extensie (nieuwe build, nieuwe key) moet een nieuw manifest worden gesigneerd en geregistreerd. Oude ID wordt ongeldig.
- Geen andere extensies: Alleen extensies met een geldig, gesigneerd manifest worden toegelaten. Chrome Web Store-verificatie is niet voldoende (eigen build = eigen key).
3.3 Communicatie: poll + SSE, geen WebSocket
| Methode | Gebruik | Waarom |
| SSE (Server-Sent Events) | Push van wallet-DApp naar extensie bij nieuwe intent | Unidirectionaal, MV3-compatibel, geen keepalive-probleem |
| Polling (30s) | Backup als SSE niet beschikbaar is (MV3 service worker killed) | Guaranteed delivery, ook na SW-restart |
| WebSocket | VERBODEN | MV3 killt sockets bij service-worker-suspend. Geen betrouwbare verbinding mogelijk. |
- Extensie opent SSE-kanaal naar
/api/vapi/extension-events. Bij connectie: ID + manifest-sig meesturen.
- SharedWorker verifieert extensie-ID bij elke SSE-verbinding.
- Bij MV3 service-worker-herstart: extensie heropent SSE + pollt laatste status op.
3.4 Altijd via wallet-DApp queue
REGEL: De extensie mag nooit direct een transactie broadcasten of een VAPI-call doen naar de kernel. Alle acties lopen via de wallet-DApp queue, waar ze dezelfde goedkeuring krijgen als elke andere DApp-intent.
Extensie wil signen:
1. Extensie -> POST /api/vapi/extension-intent { method: "extension:sign", payload }
2. Wallet-DApp queue: pending intent + SSE push
3. Gebruiker keurt goed in wallet-DApp
4. Kernel voert uit -> SSE response naar extensie
5. Extensie ontvangt resultaat
- Geen shortcuts: extensie heeft geen
broadcast:true flag, geen internal-tier omzeiling.
- Elk bedrag volle prompt, ook voor extensie-intents.
- Audit: extensie-intents worden apart gelogd met
extensionId + version.
4. Integratie met bestaande specs
| Spec | Koppeling |
| container.html | LockGate bepaalt wanneer maos-app mag mounten. spawn() vereist bootState === 'complete' + unlock. |
| vfs-spec.html | VFS-encryptie-key wordt pas na unlock uit vault geladen. Geen data-lek vóór authenticatie. |
| wallet-spec.html | Wallet-signature challenge volgt dezelfde flow als wallet:sign intent-queue. |
| store-auth.html | QR-login sessies valideren na boot-completion. LockGate reset sessie bij hard-lock. |
| core-vs-ipfs.html | Core-versie wordt in step-fase geladen. minCore-check gebeurt bij mount na unlock. |
5. Security-verplichtingen
- Challenge-nonce is cryptografisch willekeurig (crypto.getRandomValues), 32 bytes, opgeslagen in sessionStorage (niet in URL).
- LockGate-timer draait in SharedWorker (niet in main thread). Tab-sluiting = direct revoke.
- Geen localStorage voor unlock-state; alles in SharedWorker + IndexedDB (versleuteld).
- Extension-ID-check gebeurt bij elke communicatie, niet alleen bij connectie.
- Audit-logging naar
vfs://tmp/boot-audit/ (versleuteld, 30 dagen bewaard).
Volgende stap Na akkoord: P0-tickets voor boot-stappen (Fase 1C) + LockGate-implementatie + extension bridge-check + audit-logging.