# Auth Module

Authentication and authorization for the Customer Portal.

## Architecture Overview

```
auth/
├── application/           # Orchestration layer
│   ├── auth.facade.ts     # Main entry point for auth operations
│   ├── auth-login.service.ts
│   └── auth-health.service.ts
├── decorators/
│   └── public.decorator.ts  # @Public, @PublicNoSession, @OptionalAuth
├── presentation/http/
│   ├── auth.controller.ts   # Login, signup, password endpoints
│   ├── get-started.controller.ts  # OTP-based onboarding
│   ├── guards/
│   │   ├── global-auth.guard.ts   # JWT validation (APP_GUARD)
│   │   ├── local-auth.guard.ts    # Credential validation
│   │   └── failed-login-throttle.guard.ts
│   └── interceptors/
│       └── login-result.interceptor.ts
└── infra/                 # Infrastructure services
    ├── token/             # JWT & token management
    ├── otp/               # OTP & session management
    ├── rate-limiting/     # Auth-specific rate limits
    └── workflows/         # Multi-step auth flows
```

## Security Features

### Token Management

| Feature                       | Description                             |
| ----------------------------- | --------------------------------------- |
| **Access Token**              | 15-min expiry, HS256 HMAC-signed        |
| **Refresh Token**             | 7-day expiry with family-based rotation |
| **Single-Use Password Reset** | Redis-tracked tokens prevent replay     |
| **Token Blacklist**           | Immediate revocation on logout          |

### OTP Security

| Feature                 | Description                                     |
| ----------------------- | ----------------------------------------------- |
| **Code Generation**     | Cryptographically secure 6-digit codes          |
| **Expiration**          | 10 minutes (configurable)                       |
| **Max Attempts**        | 3 attempts before invalidation                  |
| **Fingerprint Binding** | Logs warning if verified from different context |

### Rate Limiting

| Endpoint       | Limit       | Window     |
| -------------- | ----------- | ---------- |
| Login          | 5 attempts  | 15 minutes |
| Signup         | 5 attempts  | 15 minutes |
| Password Reset | 5 attempts  | 15 minutes |
| OTP Send       | 5 codes     | 5 minutes  |
| OTP Verify     | 10 attempts | 5 minutes  |

## Authentication Flows

### 1. Login Flow

```
POST /auth/login
    │
    ▼
LocalAuthGuard (validates credentials)
    │
    ▼
FailedLoginThrottleGuard (rate limiting)
    │
    ▼
AuthFacade.login()
    │
    ├─► Generate token pair
    ├─► Set httpOnly cookies
    └─► Return user + session metadata
```

### 2. Password Reset Flow (Single-Use)

```
POST /auth/request-password-reset
    │
    ▼
PasswordResetTokenService.create()
    │
    ├─► Generate JWT with tokenId
    ├─► Store tokenId in Redis (15-min TTL)
    └─► Send email with reset link

POST /auth/reset-password
    │
    ▼
PasswordResetTokenService.consume()
    │
    ├─► Verify JWT signature & expiry
    ├─► Check tokenId exists in Redis
    ├─► Delete tokenId (single-use enforcement)
    └─► If already deleted → "Token already used"
```

### 3. Get Started Flow (OTP)

```
POST /auth/get-started/send-code
    │
    ▼
OtpService.generateAndStore(email, fingerprint)
    │
    ├─► Generate 6-digit code
    ├─► Store in Redis with fingerprint
    └─► Send email

POST /auth/get-started/verify-code
    │
    ▼
OtpService.verify(email, code, fingerprint)
    │
    ├─► Check fingerprint (warn if mismatch)
    ├─► Validate code
    └─► Determine account status

    Account Status:
    ├─► PORTAL_EXISTS → Redirect to login
    ├─► WHMCS_UNMAPPED → Redirect to migration
    ├─► SF_UNMAPPED → Complete account
    └─► NEW_CUSTOMER → Full signup
```

## Configuration

### Environment Variables

```bash
# JWT Configuration
JWT_SECRET=                    # Required: HMAC signing key
JWT_SECRET_PREVIOUS=           # Optional: Previous keys for rotation (comma-separated)
JWT_ISSUER=                    # Optional: Token issuer claim
JWT_AUDIENCE=                  # Optional: Token audience claim

# Token Expiry
ACCESS_TOKEN_EXPIRY=900        # 15 minutes (seconds)
REFRESH_TOKEN_EXPIRY=604800    # 7 days (seconds)
PASSWORD_RESET_TTL_SECONDS=900 # 15 minutes

# OTP Configuration
OTP_TTL_SECONDS=600            # 10 minutes
OTP_MAX_ATTEMPTS=3             # Max verification attempts

# Rate Limiting
LOGIN_RATE_LIMIT_LIMIT=5       # Max attempts
LOGIN_RATE_LIMIT_TTL=900000    # Window in ms (15 min)
LOGIN_CAPTCHA_AFTER_ATTEMPTS=3 # CAPTCHA threshold

# Redis Behavior
AUTH_ALLOW_REDIS_TOKEN_FAILOPEN=false  # Continue without Redis
AUTH_REQUIRE_REDIS_FOR_TOKENS=false    # Strict Redis requirement
AUTH_MAINTENANCE_MODE=false            # Disable auth service
```

## Route Protection

### Decorators

```typescript
// Anyone can access, optionally attach user if token exists
@Public()

// Strict public - no session attachment, no cookies read
@PublicNoSession()

// No token = allow (user=null), invalid token = 401
@OptionalAuth()

// Default: requires valid access token (401 if missing/invalid)
```

### Guard Behavior

| Decorator          | Missing Token | Invalid Token | Valid Token     |
| ------------------ | ------------- | ------------- | --------------- |
| (none)             | 401           | 401           | ✓ user attached |
| @Public()          | ✓             | ✓             | ✓ user attached |
| @PublicNoSession() | ✓             | ✓             | ✓ no user       |
| @OptionalAuth()    | ✓ null user   | 401           | ✓ user attached |

## External Integrations

The auth module integrates with:

- **WHMCS**: Account discovery, client creation, credential validation
- **Salesforce**: Account lookup, portal status updates
- **Redis**: Token storage, OTP codes, session management
- **Email (SendGrid)**: OTP codes, password reset links

## Directory Reference

| Directory                   | Purpose                                        |
| --------------------------- | ---------------------------------------------- |
| `infra/token/`              | JWT signing, refresh token rotation, blacklist |
| `infra/otp/`                | OTP codes, get-started sessions                |
| `infra/rate-limiting/`      | Auth-specific rate limiters                    |
| `infra/workflows/`          | Multi-step flows (signup, password, migration) |
| `presentation/http/guards/` | Request validation, token verification         |