# Epic: Authentication & Identity

## Overview

This epic covers user authentication, identity management, and account security.

## Business Value

- Enable personalized experiences through user accounts
- Protect user data and privacy
- Support multiple authentication methods for convenience
- Build trust through secure identity management

---

## Stories

### US-AUTH-001: Email Registration

**As a** new user  
**I want to** create an account with my email  
**So that** I can save my progress and preferences

**Acceptance Criteria**:

- [ ] User can enter email and password
- [ ] Email validation prevents invalid formats
- [ ] Password strength requirements enforced (8+ chars, mixed case, number)
- [ ] Confirmation email sent
- [ ] Account not active until email confirmed

**Priority**: P0  
**Points**: 5  
**Status**: ✅ Done

---

### US-AUTH-002: Email Login

**As a** registered user  
**I want to** log in with my email and password  
**So that** I can access my account

**Acceptance Criteria**:

- [ ] Login form accepts email and password
- [ ] Invalid credentials show generic error (security)
- [ ] Account lockout after 5 failed attempts
- [ ] Remember me option persists session
- [ ] Redirect to previous page after login

**Priority**: P0  
**Points**: 3  
**Status**: ✅ Done

---

### US-AUTH-003: Social Login

**As a** user  
**I want to** log in with Google or Apple  
**So that** I can quickly access the app without a new password

**Acceptance Criteria**:

- [ ] Google Sign-In button visible
- [ ] Apple Sign-In button visible (iOS)
- [ ] Account linked if email matches existing account
- [ ] New account created if no match
- [ ] Privacy-preserving (minimal data requested)

**Priority**: P1  
**Points**: 5  
**Status**: ✅ Done

---

### US-AUTH-004: Password Reset

**As a** user who forgot my password  
**I want to** reset it via email  
**So that** I can regain access to my account

**Acceptance Criteria**:

- [ ] "Forgot password" link on login page
- [ ] Email sent with secure reset link
- [ ] Link expires after 1 hour
- [ ] Link can only be used once
- [ ] User must create new password meeting requirements

**Priority**: P0  
**Points**: 3  
**Status**: ✅ Done

---

### US-AUTH-005: Multi-Factor Authentication

**As a** security-conscious user  
**I want to** enable MFA on my account  
**So that** my account is protected even if my password is compromised

**Acceptance Criteria**:

- [ ] MFA option in security settings
- [ ] Support TOTP (Google Authenticator, etc.)
- [ ] Support WebAuthn (biometric/security key)
- [ ] Recovery codes provided at setup
- [ ] MFA required at login when enabled

**Priority**: P1  
**Points**: 8  
**Status**: ✅ Done

---

### US-AUTH-006: Session Management

**As a** user with multiple devices  
**I want to** view and manage my active sessions  
**So that** I can ensure my account is secure

**Acceptance Criteria**:

- [ ] List of active sessions in settings
- [ ] Shows device type, location, last active
- [ ] Can sign out individual sessions
- [ ] Can sign out all sessions except current
- [ ] Notification sent when new device logs in

**Priority**: P2  
**Points**: 5  
**Status**: ✅ Done

---

### US-AUTH-007: Account Deletion

**As a** user  
**I want to** delete my account  
**So that** my data is removed from the platform

**Acceptance Criteria**:

- [ ] Delete account option in settings
- [ ] Confirmation required (re-enter password)
- [ ] Explanation of what will be deleted
- [ ] 30-day grace period before permanent deletion
- [ ] Email confirmation of deletion request

**Priority**: P1  
**Points**: 5  
**Status**: ✅ Done

---

### US-AUTH-008: Web3 Wallet Login

**As a** crypto-native user  
**I want to** log in with my Ethereum wallet  
**So that** I can use Web3 features without traditional credentials

**Acceptance Criteria**:

- [ ] "Connect Wallet" button visible
- [ ] Support MetaMask and WalletConnect
- [ ] Sign message to verify ownership
- [ ] Link wallet to existing account or create new
- [ ] Show wallet address in profile

**Priority**: P2  
**Points**: 8  
**Status**: ✅ Done

---

## Technical Notes

### Security Requirements

- Passwords hashed with bcrypt (cost factor 12)
- JWT tokens with short TTL (1 hour)
- Refresh tokens rotated on use
- All auth endpoints rate-limited

### Data Privacy

- Email stored as SHA-256 hash (salted)
- Minimal PII in JWT claims
- GDPR-compliant deletion

### Dependencies

- Auth Service (`services/auth/`)
- User Preferences Service (`services/user-preferences/`)
- Notification Service (for emails)

## Related Documentation

- [API Authentication](../api/http-api.md#authentication)
- [Security Architecture](../architecture.md#security-architecture)
