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

EndpointMethodeBeschrijvingAuth
/csrfPOSTGenereer nieuw CSRF-token + cookieGeen
/csrfGETHealth check / token refreshGeen

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

RouteReden
/csrfToken generatie moet zonder token werken
/helpRead-only, geen state-wijzigingen
/stripeWordt intern aangeroepen, CSRF check via webhook-signature
/verifyState-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

7. Risico's en aanbevelingen

RisicoImpactMitigatie
In-memory store verliest tokens bij herstartMediumVervang door Redis in productie. Herstart = alle clients moeten opnieuw /csrf aanroepen.
Geen periodic cleanup van verlopen tokensLowVoeg setInterval toe die tokens ouder dan 1 uur opkuist. Of gebruik Redis TTL.
Cookie not secure in developmentLowAcceptabel voor dev. In production: secure: true via NODE_ENV check.
Double-submit kan niet stuk door XSSHighhttpOnly 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.