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
| Endpoint | Methode | Beschrijving | Auth |
/auth/challenge | POST | Genereer QR-login challenge | Geen |
/auth/events | GET | SSE stream voor scan-events | Challenge token |
/auth/scan | POST | Mobile scant QR + verifieert challenge | Device key |
/auth/verify | POST | Sessie aanmaken na succesvolle scan | Challenge token |
/auth/login | POST | Wachtwoord-gebaseerde login | Geen |
/auth/logout | POST | Sessie beëindigen | Session cookie |
/auth/revoke | POST | Sessie intrekken (admin) | Admin session |
/auth/me | GET | Huidige sessie informatie | Session cookie |
/auth/refresh | POST | Sessie verlengen | Session cookie |
/auth/sessions | GET | Lijst van actieve sessies | Session 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
| Parameter | Waarde | Beschrijving |
| Session lifetime | 7 dagen (604800 seconden) | Cookie Max-Age |
| Challenge lifetime | 5 minuten (300 seconden) | QR-code verloopt na 5 min |
| Refresh window | 24 uur voor expiry | Sessie kan verlengd worden |
| Max sessies per user | 5 | Oude 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
| Event | Data | Wanneer |
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
- QR-login flow: challenge → scan → verify → sessie werkt end-to-end
- SSE stream: levert scan-events in real-time aan desktop
- Sessie-revoke: sessie intrekken verwijdert cookie + server-side state
- 7-dagen sessie-lifetime: cookie Max-Age = 604800
- Challenge lifetime: 5 minuten, daarna verlopen
- Max sessies: 5 per gebruiker, oudste automatisch gerevokeerd
- httpOnly cookie: niet leesbaar via JavaScript
- SameSite=Strict: geen cross-site cookies
8. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| SSE connectie kan blokkeren bij network issues | Medium | Exponential backoff reconnect. Client-side timeout na 60s zonder events. |
| Challenge brute-force | High | Challenge = 32 random bytes (256 bits). Rate-limit op /auth/scan (5/min per IP). |
| Sessie fixation | High | Nieuw sessie-ID bij elke verificatie. Geen hergebruik van challenge-sessionId. |
| Mobile app kan niet verifiëren | Medium | Fallback: 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).