31 lines
1.2 KiB
Markdown
31 lines
1.2 KiB
Markdown
# ADR 0002: Session-based authentication with HttpOnly cookies
|
|
|
|
## Status
|
|
|
|
Accepted — 2026-06-26
|
|
|
|
## Context
|
|
|
|
Phase 1 requires secure user authentication without binding to external identity providers. The web app (Next.js) and API (NestJS) run on different origins in development (`localhost:3000` / `localhost:3001`) but share credentials via CORS.
|
|
|
|
## Decision
|
|
|
|
- Use opaque session tokens (32 random bytes), stored as SHA-256 hash in `UserSession`.
|
|
- Deliver sessions via HttpOnly cookie `hgc_session` with `SameSite=lax` and `Secure` in production.
|
|
- Password hashing with Argon2id via `@node-rs/argon2`.
|
|
- TOTP 2FA with `otplib`; recovery codes stored hashed.
|
|
- Login challenges for 2FA stored in Redis (5 min TTL).
|
|
- Transactional emails via BullMQ `notifications` queue processed by worker + SMTP.
|
|
|
|
## Consequences
|
|
|
|
- Browser clients must use `credentials: 'include'`.
|
|
- API CORS must allow `APP_URL` with credentials.
|
|
- Session revocation is immediate via DB `revokedAt`.
|
|
- No JWT in localStorage (reduces XSS token theft risk).
|
|
|
|
## Alternatives considered
|
|
|
|
- JWT in Authorization header — rejected for Phase 1 due to refresh complexity and XSS exposure in SPA storage.
|
|
- External auth (Auth0, Clerk) — rejected per product requirements.
|