morethanadiagnosis-hub/openspec/specs/authentication.md

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?