# Authentication & Authorization System

Status: approved
Owners: Security, Identity, Architecture
Last updated: 2025-11-18
Related proposal: `openspec/changes/2025-11-17-authentication-system/proposal.md`

## Overview

OAuth2/OIDC-based authentication system with role-based access control (RBAC), pseudonym support, session management, and compliance-friendly audit logging.

## User Stories

- As a user, I can sign up with email/password and verify my email
- As a user, I can log in securely and stay logged in across devices
- As a user, I can use a pseudonym in the community without exposing my real name
- As a moderator, I have elevated permissions to manage flagged content
- As an admin, I can view audit logs of authentication events

## Authentication Flow

### Sign Up
- Email/password registration with email verification
- Password hashing: Argon2id (preferred) or bcrypt with high work factor
- Verification email with time-limited token

### Sign In
- OAuth2 authorization code flow with PKCE
- Support for refresh token rotation (30-day expiry)
- Access tokens: short-lived (15 min), JWT signed
- Refresh tokens: opaque, stored server-side, rotated

### Session Management
- Access tokens: 15 min expiry
- Refresh tokens: 30 days, rotated on use
- HttpOnly, Secure, SameSite cookies for web
- Secure storage for mobile apps

## API Endpoints

- `POST /api/v1/auth/signup` — register new user
- `POST /api/v1/auth/verify-email` — verify email with token
- `POST /api/v1/auth/login` — OAuth2 authorization code flow
- `POST /api/v1/auth/token` — exchange code for tokens (PKCE)
- `POST /api/v1/auth/refresh` — rotate refresh token
- `POST /api/v1/auth/logout` — revoke refresh token
- `POST /api/v1/auth/password-reset-request` — send reset email
- `POST /api/v1/auth/password-reset-confirm` — reset password with token
- `POST /api/v1/auth/mfa/enable` — enable TOTP MFA
- `POST /api/v1/auth/mfa/verify` — verify TOTP code
- `GET /api/v1/auth/me` — get current user info

## Roles & Permissions

### Roles
- **member**: read public content, write forum, read own profile
- **moderator**: manage flagged content, moderate forum
- **admin**: admin panel, user management, system audit logs

### RBAC Enforcement
- Middleware-based permission checks on protected endpoints
- Role-based scopes in JWT tokens
- Fine-grained permissions per resource

## Multi-Factor Authentication (MFA)

- TOTP (time-based one-time password) support
- Opt-in (not mandatory initially)
- QR code + manual entry for setup
- Accessible to users with assistive tech

## Account Security

- Password reset: time-limited tokens (15 min)
- Account lockout: after 5 failed login attempts, lock for 30 min
- Brute force protection: rate limit login endpoint (10 attempts per IP per minute)
- Password reset rate limit: 3 per hour per email
- Lockout notification via email

## Pseudonym Support

- User profile includes optional `pseudonym` field
- Forum/community contexts display pseudonym (if set), otherwise display_name
- Moderation/admin views show both pseudonym and real identity
- Audit logging for identity reveals

## Privacy & Compliance

- Email is PII, never logged in plain text
- Passwords never logged
- Audit log: login attempts, password resets, MFA changes (no credentials)
- DSR support: export auth history, delete purges tokens and auth records
- Consistent error messages for signup/login (prevent email enumeration)

## Data Model

- **User**: id, email (PII, unique), password_hash, email_verified, mfa_enabled, mfa_secret (encrypted), locked_until, failed_login_attempts, created_at, updated_at, deleted_at
- **Role**: id, name, permissions
- **UserRole**: id, user_id (FK), role_id (FK)
- **RefreshToken**: id, user_id (FK), token_hash, expires_at, created_at, revoked_at
- **AuthAuditLog**: id, user_id (FK, nullable), event_type, ip_address, user_agent, created_at

## Security Standards

- PKCE required for mobile/SPA
- No custom auth protocol; OAuth2/OIDC standards only
- Rate limiting on all auth endpoints
- Token rotation for refresh tokens
- Session invalidation on logout
- Audit trail for all auth events

## Observability & Telemetry

- Metrics: login success/failure rates, MFA adoption, lockout frequency
- Alerts: spike in failed logins, lockout rate anomalies
- Traces: auth flow latency (signup, login, token exchange)

## Testing

- Unit tests: password hashing, token generation/validation, RBAC
- Integration tests: full auth flows (signup, login, refresh, logout, MFA)
- Security tests: brute force protection, PKCE validation, token expiry
- Accessibility tests: keyboard nav on auth forms, screen reader labels
- Compliance tests: DSR export includes auth history, delete purges tokens

## Rollout Plan

- Deploy to staging; test with pilot users
- Migrate existing users with password reset flow
- Feature flag for MFA (opt-in)
- Monitor login success rates; rollback on anomalies

## Open Questions

- Social login (Google, Apple) support timeline? (Future proposal)
- Passkey/WebAuthn support? (Future proposal)
- Session timeout for inactivity?