Fusion
40a940304b
- Create enhanced health endpoints with /health and /health/db - Add comprehensive docstrings to all API endpoints - Add Pydantic response models with Field descriptions - Create apps/api/README.md with setup guide - Create ADR-001 for session auth decision - Create ADR-002 for async SQLAlchemy decision - Quality gates: Python syntax OK, TypeScript OK
2.1 KiB
2.1 KiB
ADR-001: Session-Based Authentication with httpOnly Cookies
Status
Accepted
Context
The application needs an authentication mechanism for the OAuth2 flow with Authentik. We need to decide between:
- JWT tokens stored in localStorage (common SPA pattern)
- Session cookies with httpOnly flag
- JWT tokens in httpOnly cookies
Constraints
- Frontend and API run on different subdomains in production (e.g.,
app.example.comandapi.example.com) - Must support OAuth2 authorization code flow
- Must work with Traefik reverse proxy
- Must be secure against XSS attacks
Decision
We will use session-based authentication with HMAC-signed httpOnly cookies.
Implementation
- After OAuth callback, the API creates a session token (HMAC-SHA256 signed)
- Token is stored in an httpOnly, Secure, SameSite cookie
- Frontend never sees or stores the token
- Cookie is sent automatically with every request via
withCredentials: true - Session is stateless - token contains user_id and expiry
Consequences
Positive
- XSS protection: Token is never exposed to JavaScript
- Simpler frontend: No token management, refresh logic, or storage
- Immediate revocation: Can invalidate sessions server-side if needed
- Standards compliant: Uses well-established cookie security mechanisms
- Works across subdomains: Cookie domain can be set to parent domain
Negative
- CSRF risk: Requires CSRF protection for state-changing operations (mitigated by SameSite=Lax/Strict)
- Less flexible: Harder to use with non-browser clients (mitigated by API key support if needed)
- Cookie size: Session token adds ~100 bytes to every request
Alternatives Considered
JWT in localStorage
- Pros: Simple implementation, works with any client
- Cons: Vulnerable to XSS, requires manual token refresh, complex frontend logic
- Rejected due to XSS vulnerability
JWT in httpOnly cookies
- Pros: XSS protection, standard JWT benefits
- Cons: Complex refresh token rotation, no easy revocation, larger token size
- Rejected in favor of simpler session cookies
Date
2026-05-18
Participants
- Development Team