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
69 lines
2.1 KiB
Markdown
69 lines
2.1 KiB
Markdown
# 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:
|
|
|
|
1. **JWT tokens** stored in localStorage (common SPA pattern)
|
|
2. **Session cookies** with httpOnly flag
|
|
3. **JWT tokens** in httpOnly cookies
|
|
|
|
### Constraints
|
|
|
|
- Frontend and API run on different subdomains in production (e.g., `app.example.com` and `api.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
|
|
|
|
1. After OAuth callback, the API creates a session token (HMAC-SHA256 signed)
|
|
2. Token is stored in an httpOnly, Secure, SameSite cookie
|
|
3. Frontend never sees or stores the token
|
|
4. Cookie is sent automatically with every request via `withCredentials: true`
|
|
5. 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
|