556f74b196
Approved proposals:
- Data Model v1: Consolidated schema with PHI/PII classification
- Authentication System: OAuth2/OIDC with RBAC & pseudonym support
- Design System: Unified components with WCAG 2.2 AA+ compliance
Applied to specs:
- openspec/specs/data-model.md (updated with full schema)
- openspec/specs/authentication.md (new)
- openspec/specs/design-system.md (new)
- openspec/specs/architecture.md (added infrastructure references)
All infrastructure proposals now approved and ready for implementation.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
137 lines
5 KiB
Markdown
137 lines
5 KiB
Markdown
# 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?
|