API: Boot state-machine + status

Ticket 1C-02 • Bron: src/routes/boot.ts (gepland) • Status: ontwerp • Risico: medium

Kerndefinitie: Boot-endpoints die de initialisatie van MAOS beheren. De boot state-machine doorloopt vier fasen: start, step, verify, complete. Idempotente retry zorgt dat mislukte stappen opnieuw uitgevoerd kunnen worden. Stray-step deny blokkeert stappen buiten de verwachte volgorde. SessionStorage bewaart bootState tussen herladingen.

1. Architectuur

Client (Browser)
    │
    ├── GET /boot/status
    │       └── Huidige boot-state ophalen
    │
    ├── POST /boot/start
    │       └── Boot-flow initialiseren
    │           → state: "started"
    │
    ├── POST /boot/step
    │       ├── Stap uitvoeren (wallet-check, permission-init, etc.)
    │       ├── Idempotent: zelfde stap opnieuw = zelfde resultaat
    │       └── → state: "step_complete" of "step_failed"
    │
    ├── POST /boot/verify
    │       ├── Verifieer dat alle stappen voltooid zijn
    │       ├── Stray-step deny: onverwachte stappen blokkeren
    │       └── → state: "verified" of "incomplete"
    │
    └── POST /boot/complete
            └── Boot-flow afsluiten
                → state: "completed"
                → SessionStorage: bootState = "completed"

State machine:
  start → step₁ → step₂ → ... → verify → complete
                                    ↓
                              incomplete → step (retry)

SessionStorage:
  bootState = "completed" (voorkomt herboot)

2. Endpoints

EndpointMethodeBeschrijvingAuth
/boot/statusGETHuidige boot-state ophalenGeen
/boot/startPOSTBoot-flow initialiserenGeen
/boot/stepPOSTEnkele stap uitvoerenSession cookie
/boot/verifyPOSTVerificatie van volledigheidSession cookie
/boot/completePOSTBoot-flow afsluitenSession cookie

3. Boot state-machine

Toegestane transities:

  ┌──────────┐
  │  START   │ ← POST /boot/start
  └────┬─────┘
       │
       ▼
  ┌──────────┐
  │  STEP₁   │ ← POST /boot/step { step: "wallet-init" }
  └────┬─────┘
       │
       ▼
  ┌──────────┐
  │  STEP₂   │ ← POST /boot/step { step: "permission-init" }
  └────┬─────┘
       │
       ▼
  ┌──────────┐
  │  STEP₃   │ ← POST /boot/step { step: "extension-init" }
  └────┬─────┘
       │
       ▼
  ┌──────────┐
  │  VERIFY  │ ← POST /boot/verify
  └────┬─────┘
       │
       ├── incomplete → terug naar STEP (ontbrekende stappen)
       │
       ▼
  ┌──────────┐
  │ COMPLETE │ ← POST /boot/complete
  └──────────┘

Onbekende transitie → 400 { error: "Invalid state transition" }

3.1 Bekende stappen

StapBeschrijvingIdempotent
wallet-initWallet-verbinding initialiserenJa
permission-initRechten controleren/initialiserenJa
extension-initExtension-connectie opzettenJa
session-initSessie validatie/aanmaakJa
storage-initLokale storage initialiserenJa

4. Idempotente retry

Regel: elke stap is idempotent.

POST /boot/step { step: "wallet-init" } (eerste keer)
→ { step: "wallet-init", status: "complete", result: { connected: true } }

POST /boot/step { step: "wallet-init" } (opnieuw)
→ { step: "wallet-init", status: "complete", result: { connected: true } }

Reden: browser herlaadt pagina tijdens boot-flow.
       Stap opnieuw uitvoeren moet zelfde resultaat geven.
       Geen dubbele initialisatie, geen fouten.

5. Stray-step deny

POST /boot/step { step: "extension-init" } (terwijl wallet nog niet geinitialiseerd)
→ 400 {
    "error": "Stray step denied",
    "currentStep": "wallet-init",
    "expected": ["wallet-init"],
    "received": "extension-init"
  }

POST /boot/verify (niet alle stappen voltooid)
→ 400 {
    "error": "Verification failed",
    "completed": ["wallet-init"],
    "missing": ["permission-init", "extension-init", "session-init"]
  }

Reden: voorkomt onvolledige boot-state.
       Stappen moeten in volgorde worden uitgevoerd.

6. SessionStorage voor bootState

Client-side opslag:
  key: "maos-boot-state"
  value: "completed" | "inbidden" | null

Logica:
  1. Pagina laadt
  2. Check SessionStorage: maos-boot-state
  3. "completed" → skip boot-flow, direct naar app
  4. null of ontbreekt → start boot-flow
  5. Na POST /boot/complete → zet maos-boot-state = "completed"

Waarom SessionStorage (niet localStorage)?
  ├── Tab-specifiek: elke tab heeft eigen boot-state
  ├── Session: verloopt bij tab-sluiting
  └── Geen persistente localStorage-rotzooi

7. Request / Response voorbeelden

7.1 GET /boot/status

GET /boot/status HTTP/1.1

Response:
{
  "state": "step_complete",
  "completedSteps": ["wallet-init", "permission-init"],
  "currentStep": "extension-init",
  "startedAt": "2025-01-15T10:00:00Z",
  "elapsed": 5432
}

7.2 POST /boot/start

POST /boot/start HTTP/1.1

Response:
{
  "state": "started",
  "bootId": "boot_abc123",
  "steps": ["wallet-init", "permission-init", "extension-init", "session-init"],
  "startedAt": "2025-01-15T10:00:00Z"
}

7.3 POST /boot/step

POST /boot/step HTTP/1.1
Content-Type: application/json

{ "step": "wallet-init" }

Response:
{
  "step": "wallet-init",
  "status": "complete",
  "result": { "connected": true, "address": "0x742d35Cc..." },
  "completedSteps": ["wallet-init"],
  "nextStep": "permission-init"
}

7.4 POST /boot/complete

POST /boot/complete HTTP/1.1

Response:
{
  "state": "completed",
  "bootId": "boot_abc123",
  "totalTime": 1234,
  "stepsCompleted": 4
}

8. Acceptatiecriteria

9. Risico's en aanbevelingen

RisicoImpactMitigatie
Boot-flow kan blokkeren bij network issuesMediumRetry met exponential backoff per stap. Timeout na 30s per stap.
Stray-step deny kan te streng zijnLowDebug-mode: log warnings i.p.v. errors bij stray steps.
SessionStorage niet beschikbaar (privacy mode)LowFallback: check via GET /boot/status i.p.v. localStorage.
Boot-flow herstart bij elke page loadMediumSessionStorage check: als "completed" → skip boot-flow.

10. Verwijzingen

Fase 1C Nog niet geimplementeerd. Vereist: state-machine implementatie, SessionStorage client-side, step-handlers. Prioriteit: medium (ondersteunt snelle app-start).