feat: implement CSRF protection using server-side tokens #WP-186

[dvrd]

Implements Cross-Site Request Forgery (CSRF) protection following industry best
practices and security guidelines:

Implementation Details

Architecture

• Token Generation: Cryptographically secure random tokens (256 bits) generated
  per session using crypto/rand
• Server-Side Storage: Tokens stored in PostgreSQL sessions table tied to user
  sessions for immediate revocation capability
• Constant-Time Verification: Uses hmac.Equal() to prevent timing attacks

Components Added

1. internal/security/csrf.go: Token manager for secure random generation

   • Generates 64-character hex tokens (256 bits)
   • No database lookups during verification (done by middleware)

2. internal/middleware/csrf.go: CSRF validation middleware

   • Validates on state-changing requests (POST, PUT, DELETE, PATCH)
   • Skips safe methods (GET, HEAD, OPTIONS)
   • Exempts endpoints: /health, /metrics, /ws/* (WebSocket uses different auth)
   • Extracts tokens from: form data, X-CSRF-Token header, X-XSRF-Token header
   • Logs security events on validation failure with context (user_id, method, path)

3. internal/middleware/csrf_test.go: Comprehensive middleware tests

   • Tests token validation from multiple sources
   • Tests security event logging
   • Tests exemption of safe methods and endpoints

Database Changes

• Migration 000003: Adds csrf_token column to sessions table
  • Unique constraint prevents token reuse across sessions
  • Index on csrf_token for efficient validation

Session Management

• Session struct now includes CSRFToken field
• SessionRepository extended with:
  • GetByCSRFToken(): Retrieve session by CSRF token
  • UpdateCSRFToken(): Associate token with session

Auth Handler Integration

• Generates CSRF token on successful login
• Returns token in LoginResponse JSON
• Token stored server-side for immediate revocation on logout

Frontend Integration

• Login/Register: Store CSRF token in sessionStorage
  • sessionStorage chosen over localStorage (cleared on tab close)
  • Safer than localStorage (XSS vulnerable)
• API Calls: Include token in X-CSRF-Token header for all state-changing requests
• Helper function added to index.html for consistent token handling

Security Properties

✓ Prevents cross-site request forgery from attacker-controlled domains
✓ Tokens tied to session - invalidated on logout/session expiration
✓ Stateless verification possible but implemented server-side for:

• Immediate revocation capability
• Better logging and monitoring
• Scales to load-balanced deployments (shared PostgreSQL)
  ✓ Constant-time comparison prevents timing attacks
  ✓ Security event logging for monitoring and alerting
  ✓ SameSite cookie attribute already set (Lax mode)
  ✓ No token leakage - never in URLs or cookies alone

Complementary Protections

• Rate limiting on auth endpoints (already implemented)
• HTTPS enforcement (configure in deployment)
• CORS policies (already implemented)
• Session timeout (already implemented)

Testing

• Unit tests for token generation (uniqueness, format, entropy)
• Integration tests for middleware (validation, exemption, logging)
• All existing tests updated and passing
• Handler and service tests updated with mock CSRF methods

Notes

• Implementation uses per-session tokens (simpler than per-request)
• WebSocket endpoints exempt from CSRF (use session token in query param)
• Tokens persist for session lifetime (no per-request rotation)