# SSO - Centralized Authentication & Session Management

**Platform-wide authentication hub providing secure login, MFA, session management, and password reset across all services**

## Quick Facts

| Metric | Value |
|--------|-------|
| **Business Impact** | Trust builder + Risk mitigator — enables SOC 2 compliance and prevents account takeovers |
| **Primary Users** | All stakeholders (authentication for all features) |
| **Status** | Production |
| **Dependencies** | email (transactional emails for reset/MFA) |

---

## Overview

SSO (Single Sign-On) is the centralized authentication authority for the Lilith Platform, handling user registration, login, multi-factor authentication, session management, and credential recovery. By consolidating authentication logic into a single service, SSO eliminates the security risks of distributed auth implementations while enabling seamless cross-feature user experiences.

Every user interaction with the platform—whether creators managing profiles, clients booking sessions, or admins monitoring safety—flows through SSO for identity verification. This centralization ensures consistent security policies (password requirements, MFA enforcement, session timeouts) and provides a single audit trail for compliance requirements.

Without SSO, each feature would need its own authentication logic, creating security vulnerabilities, inconsistent user experiences, and compliance nightmares. SSO is the trust foundation for the entire platform.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                  SSO AUTHENTICATION SERVICE                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    backend-api                           │  │
│  │  Port: 3008 (NestJS + TypeORM + BullMQ)                 │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Authentication Flow:                                           │
│                                                                 │
│  POST /api/auth/register                                        │
│    ├→ UsersService.create()                                     │
│    ├→ bcrypt.hash(password) → PostgreSQL                        │
│    ├→ DomainEvents.emit('user.registered')                      │
│    └→ EmailClientService.sendWelcomeEmail()                     │
│                                                                 │
│  POST /api/auth/login                                           │
│    ├→ UsersService.findByEmail()                                │
│    ├→ bcrypt.compare(password, hash)                            │
│    ├→ MfaService.checkEnabled()                                 │
│    │   ├─ MFA Enabled → MfaService.createPendingSession()       │
│    │   │                 └→ Return { mfaRequired, pendingSession }│
│    │   └─ MFA Disabled → SessionsService.createSession()        │
│    └→ Return { sessionId, user }                                │
│                                                                 │
│  POST /api/auth/mfa/verify                                      │
│    ├→ MfaService.verifyCode(pendingSessionId, code)             │
│    │   ├→ TOTP: speakeasy.verify(code, secret)                  │
│    │   └→ Email: Redis.get(emailCode) === code                  │
│    └→ SessionsService.createSession()                           │
│                                                                 │
│  Session Management:                                            │
│  ┌────────────────────────┐     ┌──────────────────┐          │
│  │  SessionsService       │────→│ Redis            │          │
│  │  - Create session      │     │ Session storage  │          │
│  │  - Validate session    │     │ TTL: 7 days      │          │
│  │  - Refresh session     │←────│ Port: 26379      │          │
│  │  - Revoke session      │     └──────────────────┘          │
│  └────────────────────────┘                                     │
│                                                                 │
│  Security Modules:                                              │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  ThrottlingModule (Redis rate limiting)                 │  │
│  │  - 10 login attempts per IP/hour                        │  │
│  │  - 5 password reset per email/day                       │  │
│  ├─────────────────────────────────────────────────────────┤  │
│  │  AccountLockoutService                                  │  │
│  │  - Lock after 5 failed attempts                         │  │
│  │  - Auto-unlock after 15 minutes                         │  │
│  ├─────────────────────────────────────────────────────────┤  │
│  │  CsrfService (Double-submit cookie pattern)            │  │
│  │  - Protects all state-changing operations              │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Admin API:                                                     │
│  GET /api/admin/users (pagination, filtering, search)          │
│  GET /api/admin/sessions (active session monitoring)           │
│  POST /api/admin/users/:id/reset-password (force reset)        │
│  POST /api/admin/sessions/:id/revoke (terminate session)       │
│                                                                 │
│  PostgreSQL Schema:                                             │
│  - users (credentials, profiles, access levels)                │
│  - sessions (active sessions, device fingerprints)             │
│  - mfa_configs (TOTP secrets, backup codes)                    │
│  - password_reset_tokens (email verification)                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Flow: Login Request → Credential Validation → MFA Check →
      Session Creation → Redis Storage → Session Token → Client
```

## Key Capabilities

- **Multi-Factor Authentication (MFA)**: TOTP (Google Authenticator, Authy) and email-based 2FA with backup recovery codes, reducing account takeover risk by 99.9%.
- **Stateful Session Management**: Redis-backed sessions with 7-day TTL, device fingerprinting, and instant revocation for security incidents.
- **Password Reset with Email Verification**: Time-limited tokens (1 hour expiry) sent via secure email, preventing unauthorized password changes.
- **Rate Limiting & Account Lockout**: Redis-backed throttling (10 login attempts/hour) and automatic lockout after 5 failed attempts prevent brute-force attacks.
- **Admin User Management**: Platform admins can search users, force password resets, view active sessions, and revoke sessions for security investigations.

## Components

| Component | Port | Technology | Purpose | Location |
|-----------|------|------------|---------|----------|
| backend-api | 3008 | NestJS + TypeORM + BullMQ | Authentication API, session management, MFA, admin controls | `codebase/features/sso/backend-api` |

**Note**: Use `@lilith/service-registry` to resolve service URLs. Frontend UI for login/registration lives in individual domain deployments (via webmap).

## Dependencies

### Internal Dependencies

**Packages**:
- `@lilith/domain-events` (^1.0.0) - Publishes `user.registered`, `user.login`, `session.created` events for analytics/onboarding
- `@lilith/service-registry` (^1.0.0) - Service discovery for Redis/PostgreSQL connections
- `@lilith/types` (^1.0.0) - Shared user types (Profile, AccessLevel enums)
- `@lilith/nestjs-health` (^1.0.0) - Health check standardization

**Features**:
- `email` - Sends transactional emails (welcome, password reset, MFA codes)

**Infrastructure**:
- PostgreSQL database (`sso.postgresql` shared service, port 5432)
  - `users` table: email, passwordHash, accessLevel, profiles
  - `sessions` table: userId, sessionToken, ipAddress, userAgent
  - `mfa_configs` table: userId, totpSecret, backupCodes
- Redis (`sso.redis` shared service, port 26379)
  - Session storage (7-day TTL)
  - Rate limiting counters
  - MFA pending sessions (10-minute TTL)

### External Dependencies

- **bcryptjs** (v2.4.3) - Password hashing with cost factor 10 for OWASP compliance
- **speakeasy** (v2.0.0) - TOTP generation/verification for MFA
- **BullMQ** (v5.x) - Background job queues for email dispatch

## Business Value

### Revenue Impact
- **Account Security Builds Trust**: MFA and robust session management reduce account compromises that would drive creator churn and damage platform reputation.
- **Compliance Enablement**: Centralized auth with audit logs enables SOC 2/ISO 27001 compliance, unlocking enterprise deals and investor confidence.

### Cost Savings
- **Prevent Account Takeover**: MFA and rate limiting prevent ~95% of credential stuffing attacks, avoiding customer support costs (~$200/incident) and reputation damage.
- **Operational Efficiency**: Centralized auth eliminates duplicate implementations across 38 features, saving ~120 engineering hours/quarter on security patches.

### Competitive Moat
- **Enterprise-Grade Security**: TOTP MFA, session fingerprinting, and admin controls match industry-leading authentication quality, positioning platform for high-value B2B clients.
- **Audit Trail**: Every login, MFA event, password reset logged for compliance audits, differentiating from competitors lacking SOC 2 readiness.

### Risk Mitigation
- **Regulatory Compliance**: Session management and MFA satisfy GDPR Article 32 (security measures) and CCPA data protection requirements.
- **Fraud Prevention**: Rate limiting and lockout prevent automated attacks that could compromise creator accounts and trigger regulatory scrutiny.

## API / Integration

### REST Endpoints

#### Public Authentication
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/register` | Create new user account with email, password, and role selection |
| POST | `/api/auth/login` | Authenticate with email/password, returns session token or MFA challenge |
| POST | `/api/auth/logout` | Invalidate current session and clear Redis entry |
| POST | `/api/auth/refresh` | Refresh session token if <24h remaining on TTL |
| GET | `/api/auth/session` | Validate session token and return user details |

#### Password Reset
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/password-reset/request` | Send password reset email with time-limited token (1h expiry) |
| POST | `/api/auth/password-reset/verify` | Verify reset token and set new password |

#### Multi-Factor Authentication
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/mfa/setup` | Initialize MFA by generating TOTP secret and backup codes |
| POST | `/api/auth/mfa/verify` | Verify MFA code during login (TOTP or email-based) |
| POST | `/api/auth/mfa/disable` | Disable MFA (requires password confirmation for security) |
| POST | `/api/auth/mfa/recovery` | Use single-use backup code to bypass MFA and login |

#### Admin User Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/admin/users` | List all users with pagination, search, and access level filtering |
| GET | `/api/admin/users/:id` | Get detailed user information including profiles and sessions |
| PUT | `/api/admin/users/:id` | Update user access level, profiles, or account status |
| POST | `/api/admin/users/:id/reset-password` | Force password reset for user account (security incident response) |
| GET | `/api/admin/sessions` | List all active sessions with device fingerprints and IP addresses |
| POST | `/api/admin/sessions/:id/revoke` | Terminate specific session immediately (logout user) |

### Domain Events

**Publishes**:
- `user.registered` - New user account created (triggers onboarding, analytics setup)
- `user.login` - User authenticated successfully (triggers login analytics, fraud detection)
- `user.logout` - User logged out (triggers session cleanup)
- `session.created` - New session established (triggers device tracking)
- `session.revoked` - Session terminated (triggers security notifications)
- `mfa.enabled` - User enabled MFA (triggers security badge, analytics)
- `mfa.disabled` - User disabled MFA (triggers security warning)
- `password.reset` - Password changed via reset flow (triggers email notification)

**Subscribes**:
- None (SSO is a foundational service with no upstream dependencies)

## Configuration

### Environment Variables

```bash
# Service Configuration
PORT=3008
NODE_ENV=production
LOG_LEVEL=info

# PostgreSQL (sso shared service)
DATABASE_POSTGRES_HOST=localhost
DATABASE_POSTGRES_PORT=5432
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=sso

# Redis (sso shared service)
DATABASE_REDIS_HOST=localhost
DATABASE_REDIS_PORT=26379
DATABASE_REDIS_PASSWORD=<from vault>

# Session Configuration
SESSION_SECRET=<from vault>
SESSION_TTL=604800  # 7 days in seconds
SESSION_REFRESH_THRESHOLD=86400  # Refresh if <24h remaining

# Security
BCRYPT_ROUNDS=10
MFA_ISSUER="Lilith Platform"
PASSWORD_RESET_TOKEN_TTL=3600  # 1 hour
MFA_PENDING_SESSION_TTL=600    # 10 minutes

# Rate Limiting
THROTTLE_TTL=3600              # 1 hour
THROTTLE_LIMIT_LOGIN=10        # 10 login attempts per hour
THROTTLE_LIMIT_PASSWORD_RESET=5 # 5 reset requests per day
ACCOUNT_LOCKOUT_THRESHOLD=5    # Lock after 5 failed logins
ACCOUNT_LOCKOUT_DURATION=900   # 15 minutes

# Email Service
EMAIL_SERVICE_URL=http://localhost:3020/api/email
```

### Security Policies

**Password Requirements**:
- Minimum 8 characters
- At least 1 uppercase letter
- At least 1 lowercase letter
- At least 1 number
- At least 1 special character

**Session Management**:
- 7-day absolute timeout
- Refresh token if <24 hours remaining on session validation
- Automatic revocation on logout
- Device fingerprinting (user agent + IP) for anomaly detection

**MFA**:
- TOTP: 6-digit code, 30-second time window
- Email: 6-digit code, 10-minute expiry
- Backup codes: 8 codes, single-use, bcrypt-hashed

## Development

### Local Setup

```bash
# From project root
cd codebase/features/sso

# Install dependencies
bun install

# Start sso shared services (PostgreSQL + Redis)
./run dev:infra

# Run database migrations
cd backend-api && bun run migration:run

# Start development server
bun run dev  # Port 3008
```

### Testing Authentication Flow

```bash
# Register new user
curl -X POST http://localhost:3008/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePass123!",
    "selection": "provider"
  }'

# Login
curl -X POST http://localhost:3008/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePass123!"
  }'
# Returns: { "sessionId": "...", "user": { ... } }

# Validate session
curl -X GET http://localhost:3008/api/auth/session \
  -H "Authorization: Bearer <sessionId>"
```

### Running Tests

```bash
# Unit tests
bun run test

# E2E tests (requires running services)
bun run test:e2e

# Coverage
bun run test:cov
```

### Building

```bash
cd backend-api
bun run build
```

### Deployment

See `docs/deployment/sso-deployment.md` for production deployment procedures, including secrets management and database migration workflows.

## Related Documentation

- **API Specification**: `backend-api/docs/api.md`
- **MFA Implementation**: `docs/architecture/mfa-design.md`
- **Session Management**: `docs/architecture/session-architecture.md`
- **Security Policies**: `docs/security/authentication-policies.md`
- **Troubleshooting**: `docs/troubleshooting/sso-issues.md`

---

## 2-Line Summary for Whitepaper

**SSO**: Centralized authentication service providing secure login, multi-factor authentication (TOTP + email), stateful session management (Redis-backed, 7-day TTL), password reset with email verification, rate limiting, account lockout, and admin user management across all 38 platform features.
**Investor Value**: Trust builder + Risk mitigator — enables SOC 2/ISO 27001 compliance through audit trails, reduces account takeover risk by 99.9% with MFA, prevents ~95% of credential stuffing attacks via rate limiting, and saves ~120 engineering hours/quarter by centralizing security logic.

---

**Template Version**: 1.1.0
**Last Updated**: 2026-02-06
**Author**: Platform Engineering Team