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.

StapActieSuccesFout
startShell initialiseren, DOM + Workers aanmaken→ step→ restart (max 3x)
stepKernmodules laden: SW registreren, SharedWorker starten, vault openen→ verify→ retry (idempotent, max 5x)
verifyIntegriteitscheck: core-bundle hash, SW versie, worker gezondheid→ complete→ retry of fallback (nieuwe SW-claim)
completeShell ready, LockGate wacht op unlockUI 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

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.

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

2.2 LockGate 60s grace

GebeurtenisActieReden
Tabrefresher / navigatie60 seconden grace-periodVoorkomt herhaald unlock bij normaal browsen
60s verlopen zonder unlockHard lock: sessie gesloten, ports dichtBeveiliging tegen onbevoegde toegang
Hibernate (15 min inactiviteit)Snapshot + hard lock directRAM-besparing + veiligheid
Unlock binnen 60sDirect hervatten, geen extra verificatieUX-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

RetryGedrag
1-4Onmiddellijk opnieuw proberen. Geen extra restrictie.
5e mislukking15 minuten lockout. Alle verdere unlock-pogingen geweigerd.
Lockout-duur15 minuten, gedeeld over alle tabs (SharedWorker houdt staat bij).
Na lockoutReset naar 0 retries. Eerste poging is weer vrij.

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

3.3 Communicatie: poll + SSE, geen WebSocket

MethodeGebruikWaarom
SSE (Server-Sent Events)Push van wallet-DApp naar extensie bij nieuwe intentUnidirectionaal, MV3-compatibel, geen keepalive-probleem
Polling (30s)Backup als SSE niet beschikbaar is (MV3 service worker killed)Guaranteed delivery, ook na SW-restart
WebSocketVERBODENMV3 killt sockets bij service-worker-suspend. Geen betrouwbare verbinding mogelijk.

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

4. Integratie met bestaande specs

SpecKoppeling
container.htmlLockGate bepaalt wanneer maos-app mag mounten. spawn() vereist bootState === 'complete' + unlock.
vfs-spec.htmlVFS-encryptie-key wordt pas na unlock uit vault geladen. Geen data-lek vóór authenticatie.
wallet-spec.htmlWallet-signature challenge volgt dezelfde flow als wallet:sign intent-queue.
store-auth.htmlQR-login sessies valideren na boot-completion. LockGate reset sessie bij hard-lock.
core-vs-ipfs.htmlCore-versie wordt in step-fase geladen. minCore-check gebeurt bij mount na unlock.

5. Security-verplichtingen

Volgende stap Na akkoord: P0-tickets voor boot-stappen (Fase 1C) + LockGate-implementatie + extension bridge-check + audit-logging.