API: Auth + QR-login (10 endpoints)

Ticket 1C-01 • Bron: src/routes/auth.ts (gepland) • Status: ontwerp • Risico: hoog (authenticatie-core)

Kerndefinitie: Tien auth-endpoints die het authenticatiesysteem van MAOS vormen. Kern is de QR-login flow: mobile app genereert challenge, desktop toont QR, mobile scant en verifieert. SSE stream levert scan-events aan desktop. Sessies hebben 7-dagen lifetime. Alle routes zijn stateless behalve de SSE-stream.

1. Architectuur

Desktop (Browser)                    Mobile App
    │                                     │
    ├── POST /auth/challenge              │
    │       └── Genereer QR-payload       │
    │           { challenge, sessionId,   │
    │             expiresAt }             │
    │                                     │
    ├── GET /auth/events (SSE)            │
    │       └── Wacht op scan-event       │
    │                                     │
    │                                     ├── POST /auth/scan
    │                                     │       ├── QR scannen
    │                                     │       ├── Challenge verifiëren
    │                                     │       └── Return { verified: true }
    │
    ├── SSE: event: scanned               │
    │       { "status": "scanned",        │
    │         "deviceInfo": {...} }        │
    │                                     │
    ├── POST /auth/verify                 │
    │       └── Sessie aanmaken           │
    │           → httpOnly cookie         │
    │           → session lifetime 7d     │
    │                                     │
    ├── POST /auth/revoke                 │
    │       └── Sessie intrekken          │
    │                                     │
    └── GET /auth/me                      │
            └── Huidige sessie info

Sessie lifecycle:
  challenge → scan → verify → sessie (7d) → revoke of expiry

2. Endpoints

EndpointMethodeBeschrijvingAuth
/auth/challengePOSTGenereer QR-login challengeGeen
/auth/eventsGETSSE stream voor scan-eventsChallenge token
/auth/scanPOSTMobile scant QR + verifieert challengeDevice key
/auth/verifyPOSTSessie aanmaken na succesvolle scanChallenge token
/auth/loginPOSTWachtwoord-gebaseerde loginGeen
/auth/logoutPOSTSessie beëindigenSession cookie
/auth/revokePOSTSessie intrekken (admin)Admin session
/auth/meGETHuidige sessie informatieSession cookie
/auth/refreshPOSTSessie verlengenSession cookie
/auth/sessionsGETLijst van actieve sessiesSession cookie

3. QR-login flow (detail)

Stap 1: Desktop genereert challenge
  POST /auth/challenge
  → { challenge: "abc123...", sessionId: "sess_xyz", expiresAt: "..." }
  → QR-code tonen (bevat challenge + sessionId)

Stap 2: Desktop opent SSE
  GET /auth/events?sessionId=sess_xyz
  → Event stream wacht op scan-events

Stap 3: Mobile scant QR
  POST /auth/scan
  Body: { challenge: "abc123...", deviceInfo: {...} }
  → Mobile verifieert challenge against device key
  → { verified: true, deviceName: "iPhone 15" }

Stap 4: SSE triggert event
  event: scanned
  data: { "status": "scanned", "deviceInfo": { "name": "iPhone 15" } }

Stap 5: Desktop verifieert sessie
  POST /auth/verify
  Body: { sessionId: "sess_xyz", challenge: "abc123..." }
  → { sessionToken: "...", user: {...} }
  → Set-Cookie: maos-session=...; HttpOnly; SameSite=Strict; Max-Age=604800

Stap 6: Sessie actief
  GET /auth/me
  → { user: { id, name, email }, sessionId, expiresAt }

4. Sessie lifetime

ParameterWaardeBeschrijving
Session lifetime7 dagen (604800 seconden)Cookie Max-Age
Challenge lifetime5 minuten (300 seconden)QR-code verloopt na 5 min
Refresh window24 uur voor expirySessie kan verlengd worden
Max sessies per user5Oude sessies automatisch gerevokeerd

5. Request / Response voorbeelden

5.1 POST /auth/challenge

POST /auth/challenge HTTP/1.1
Content-Type: application/json

Response:
{
  "challenge": "a1b2c3d4e5f6...",
  "sessionId": "sess_abc123",
  "qrPayload": "maos://login?c=a1b2c3d4e5f6...&s=sess_abc123",
  "expiresAt": "2025-01-15T10:05:00Z"
}

5.2 POST /auth/scan (mobile)

POST /auth/scan HTTP/1.1
Content-Type: application/json

{
  "challenge": "a1b2c3d4e5f6...",
  "deviceInfo": {
    "name": "iPhone 15",
    "os": "iOS 17.2",
    "appVersion": "1.0.0"
  }
}

Response:
{
  "verified": true,
  "deviceName": "iPhone 15",
  "scannedAt": "2025-01-15T10:01:30Z"
}

5.3 POST /auth/verify

POST /auth/verify HTTP/1.1
Content-Type: application/json

{
  "sessionId": "sess_abc123",
  "challenge": "a1b2c3d4e5f6..."
}

Response:
{
  "sessionToken": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "user_001",
    "name": "Maik",
    "email": "maik@example.com"
  },
  "expiresAt": "2025-01-22T10:01:30Z"
}

Set-Cookie:
  maos-session=eyJhbGci...; HttpOnly; SameSite=Strict; Path=/; Max-Age=604800

5.4 POST /auth/revoke

POST /auth/revoke HTTP/1.1
Cookie: maos-session=admin_token...
Content-Type: application/json

{ "sessionId": "sess_abc123" }

Response:
{
  "revoked": true,
  "sessionId": "sess_abc123"
}

5.5 Foutafhandeling

// Challenge verlopen
POST /auth/verify { "sessionId": "oud", "challenge": "..." }
→ 400 { "error": "Challenge expired" }

// Ongeldige scan
POST /auth/scan { "challenge": "ongeldig" }
→ 400 { "error": "Invalid challenge" }

// Teveel sessies
POST /auth/verify (user heeft al 5 sessies)
→ 200 (oudste sessie automatisch gerevokeerd, nieuwe aangemaakt)

6. SSE event types

EventDataWanneer
scanned{ status, deviceInfo }Mobile heeft QR gescand
verified{ sessionId, user }Desktop heeft sessie geverifieerd
rejected{ reason }Gebruiker heeft login geweigerd
expired{}Challenge verlopen (5 min)
heartbeat{ ts }Elke 30 seconden (keepalive)

7. Acceptatiecriteria

8. Risico's en aanbevelingen

RisicoImpactMitigatie
SSE connectie kan blokkeren bij network issuesMediumExponential backoff reconnect. Client-side timeout na 60s zonder events.
Challenge brute-forceHighChallenge = 32 random bytes (256 bits). Rate-limit op /auth/scan (5/min per IP).
Sessie fixationHighNieuw sessie-ID bij elke verificatie. Geen hergebruik van challenge-sessionId.
Mobile app kan niet verifiërenMediumFallback: wachtwoord-login via /auth/login. QR is convenience, niet verplicht.

9. Verwijzingen

Fase 1C Nog niet geimplementeerd. Vereist: QR-code generatie, SSE infrastructure, sessie state management (Redis). Prioriteit: hoog (authenticatie-core van het hele systeem).