API: CSRF-token generatie + validatie
Ticket 1A-01 • Bron: src/routes/csrf.ts + src/middleware/csrf.ts • Status: geimplementeerd • Risico: laag
Kerndefinitie: CSRF-bescherming via double-submit cookie pattern. De client haalt een token op via POST /csrf, slaat het op in een httpOnly cookie en stuurt het mee als x-csrf-token header bij mutaties. De csrfGuard middleware vergelijkt cookie met header. Tokens hebben een levensduur van 1 uur.
1. Architectuur
Client (DApp / Browser)
│
├── 1. POST /csrf → genereer nieuw token
│ ├── crypto.randomBytes(32).toString("hex")
│ ├── setCookie("csrf-token", token, { httpOnly, sameSite: Strict })
│ └── return { token } (header-component slaat op)
│
├── 2. GET /csrf → refresh / health check
│ ├── Cookie bestaand + geldig? → return { refreshed: false }
│ └── Nee? → genereer nieuw, set cookie, return { refreshed: true }
│
├── 3. Mutaties (POST/PUT/DELETE/PATCH)
│ ├── Header: x-csrf-token =
│ └── Cookie: csrf-token =
│
└── 4. csrfGuard middleware
├── GET/HEAD? → doorlaten (geen check)
├── Exempt route? (/csrf, /help, /stripe, /verify) → doorlaten
└── Anders → validateCsrf(c)
├── Cookie == Header? → doorlaten
└── Nee → 403 { error: "CSRF validation failed" }
2. Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/csrf | POST | Genereer nieuw CSRF-token + cookie | Geen |
/csrf | GET | Health check / token refresh | Geen |
3. Middleware: csrfGuard
src/middleware/csrf.ts
class csrfGuard:
method = c.req.method.toUpperCase()
pathname = new URL(c.req.url).pathname
if method in [POST, PUT, DELETE, PATCH]:
if not isExempt(pathname):
headerToken = c.req.header("x-csrf-token")
cookieToken = parseCookie(c, "csrf-token")
if cookieToken != headerToken:
return 403 { error: "CSRF validation failed. Refresh the page and try again." }
await next()
3.1 Exempt-routes
| Route | Reden |
/csrf | Token generatie moet zonder token werken |
/help | Read-only, geen state-wijzigingen |
/stripe | Wordt intern aangeroepen, CSRF check via webhook-signature |
/verify | State-loze verificatie, geen mutaties |
4. Request / Response voorbeelden
4.1 POST /csrf (token generatie)
POST /csrf HTTP/1.1
Content-Type: application/json
Response:
{
"success": true,
"token": "a1b2c3d4e5f6...64 hex chars"
}
Cookie set:
csrf-token=a1b2c3d4e5f6...; HttpOnly; SameSite=Strict; Path=/; Max-Age=3600
4.2 GET /csrf (refresh)
GET /csrf HTTP/1.1
Cookie: csrf-token=a1b2c3d4e5f6...
Response (token geldig):
{
"success": true,
"token": "a1b2c3d4e5f6...",
"refreshed": false
}
Response (token verlopen/ontbrekend):
{
"success": true,
"token": "nieuw...",
"refreshed": true
}
4.3 Mutatie met CSRF-check
POST /api/dapps/register HTTP/1.1
Cookie: csrf-token=a1b2c3d4e5f6...
x-csrf-token: a1b2c3d4e5f6...
→ csrfGuard: cookie == header → doorlaten → handler voert uit
4.4 Mutatie zonder CSRF-token
POST /api/dapps/register HTTP/1.1
Cookie: csrf-token=a1b2c3d4e5f6...
(geen x-csrf-token header)
→ csrfGuard: header ontbreekt → 403
{
"error": "CSRF validation failed. Refresh the page and try again."
}
5. Token lifecycle
Generatie: crypto.randomBytes(32) → 64 hex chars
Opslag: In-memory Map (token → token) — voor productie: Redis
Cookie: httpOnly, sameSite=Strict, secure (production), maxAge=3600
Validatie: Cookie-header regex parse → vergelijk met x-csrf-token header
Cleanup: Geen — tokens verlopen via cookie maxAge server-side store leegdraait niet
(optioneel: periodic sweep in productie)
6. Acceptatiecriteria
- POST /csrf geeft nieuw token + cookie terug
- GET /csrf geeft bestaand token terug (refreshed: false) of nieuw (refreshed: true)
- POST/PUT/DELETE/PATCH zonder geldig token → 403 via csrfGuard
- Cookie httpOnly → niet leesbaar via JavaScript (XSS-bescherming)
- sameSite=Strict → cookie niet meegezonden bij cross-site requests
- Exempt-routes werken zonder token (GET, bootstrap routes)
- Levensduur: cookie maxAge = 3600 seconden (1 uur)
7. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| In-memory store verliest tokens bij herstart | Medium | Vervang door Redis in productie. Herstart = alle clients moeten opnieuw /csrf aanroepen. |
| Geen periodic cleanup van verlopen tokens | Low | Voeg setInterval toe die tokens ouder dan 1 uur opkuist. Of gebruik Redis TTL. |
| Cookie not secure in development | Low | Acceptabel voor dev. In production: secure: true via NODE_ENV check. |
| Double-submit kan niet stuk door XSS | High | httpOnly cookie voorkomt JavaScript-leesbaarheid. XSS kan echter nog steeds requests sturen met cookie meegestuurd. Dit is inherent aan double-submit pattern. Overweeg SameSite=Strict (al ingesteld). |
8. Verwijzingen
Fase 1A Implementatie in src/routes/csrf.ts + src/middleware/csrf.ts. Geen kernel-afhankelijkheid. Volledig operationeel.