nucleus-core-ts 0.8.0

package/public/components/docs/content/authentication.ts

@@ -0,0 +1,1670 @@
+import type { DocItem } from "../docsData";
+
+export const authenticationItems: DocItem[] = [
+	{
+		id: "tokens",
+		title: "Tokens",
+		subItems: [
+			{
+				id: "high-overview",
+				title: "High Overview",
+				content: `
+## Token Architecture Overview
+
+Nucleus implements a **three-token security model** designed for enterprise applications. This architecture balances security with user experience.
+
+### Why Three Tokens?
+
+\`\`\`mermaid
+flowchart TB
+    subgraph Problem["Single Token Problems"]
+        P1[Long-lived = Security risk]
+        P2[Short-lived = Poor UX]
+    end
+    
+    subgraph Solution["Three Token Solution"]
+        S1[Access Token<br/>Short-lived for security]
+        S2[Refresh Token<br/>Long-lived for UX]
+        S3[Session Token<br/>Device tracking]
+    end
+    
+    Problem --> Solution
+\`\`\`
+
+### Token Responsibilities
+
+| Token | Lifetime | Purpose | Revocable |
+|-------|----------|---------|-----------|
+| **Access Token** | 15 minutes | Authenticate API requests | No (stateless) |
+| **Refresh Token** | 7 days | Obtain new access tokens | Yes (rotation) |
+| **Session Token** | 30 days | Track device/session | Yes (immediate) |
+
+### Complete Auth Flow
+
+\`\`\`mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Client
+    participant S as Server
+    participant R as Redis
+    participant D as Database
+
+    Note over U,D: Login Flow
+    U->>C: Enter credentials
+    C->>S: POST /auth/login
+    S->>D: Verify credentials
+    D-->>S: User data
+    S->>S: Generate 3 tokens
+    S->>R: Store session
+    S->>D: Save session record
+    S-->>C: Tokens (cookies + JSON)
+    
+    Note over U,D: API Request Flow
+    C->>S: Request + Access Token
+    S->>S: Verify JWT
+    alt Token Valid
+        S->>S: Process request
+        S-->>C: Response
+    else Token Expired
+        S->>S: Check Refresh Token
+        S->>S: Generate new Access Token
+        S-->>C: Response + New Token
+    end
+    
+    Note over U,D: Logout Flow
+    C->>S: POST /auth/logout
+    S->>R: Delete session
+    S->>D: Mark session revoked
+    S-->>C: Clear cookies
+\`\`\`
+
+### Security Features
+
+- **Short-lived access tokens** - 15 minute window limits damage from stolen tokens
+- **Refresh token rotation** - New refresh token on each use, old ones invalidated
+- **Session binding** - Tokens are bound to specific sessions
+- **Device fingerprinting** - Track and verify device identity
+- **Trust scoring** - Automatic risk assessment for each login
+        `,
+			},
+			{
+				id: "access-token",
+				title: "Access Token",
+				content: `
+## Access Token
+
+The access token is the primary authentication credential for API requests. It's a stateless JWT that contains user identity information.
+
+### Configuration
+
+\`\`\`typescript
+accessToken: {
+  secret: string,
+  expiresIn: string,
+  algorithm: Algorithm,
+  issuer: string,
+  audience: string,
+  name: string,
+  setHeadersEnabled: boolean,
+  returnJson: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`secret\` | string | **Yes** | - | JWT signing secret. Must be at least 32 characters. Use a cryptographically secure random string. **Never commit to version control.** |
+| \`expiresIn\` | string | No | \`'15m'\` | Token lifetime. Accepts formats: \`'15m'\` (minutes), \`'1h'\` (hours), \`'7d'\` (days). Keep short (15-30 min) for security. |
+| \`algorithm\` | string | No | \`'HS256'\` | JWT signing algorithm. Options: \`HS256\`, \`HS384\`, \`HS512\`. HS256 is recommended for most cases. |
+| \`issuer\` | string | No | - | JWT \`iss\` claim. Identifies your application. Example: \`'my-app'\` |
+| \`audience\` | string | No | - | JWT \`aud\` claim. Identifies intended recipients. Example: \`'my-api'\` |
+| \`name\` | string | No | \`'access_token'\` | Cookie name when setting via HTTP headers. |
+| \`setHeadersEnabled\` | boolean | No | \`true\` | If \`true\`, token is set as an HTTP-only, Secure, SameSite=Strict cookie. |
+| \`returnJson\` | boolean | No | \`true\` | If \`true\`, token is included in the JSON response body for client-side storage. |
+
+### JWT Payload Structure
+
+\`\`\`typescript
+{
+  sub: string,      // User ID (UUID)
+  iat: number,      // Issued at (Unix timestamp)
+  exp: number,      // Expiration (Unix timestamp)
+  iss?: string,     // Issuer (if configured)
+  aud?: string,     // Audience (if configured)
+}
+\`\`\`
+
+### Best Practices
+
+1. **Use environment variables** for secrets
+2. **Keep expiration short** (15 minutes recommended)
+3. **Enable both cookie and JSON** for flexibility
+4. **Use HTTPS only** in production
+5. **Rotate secrets periodically** (quarterly recommended)
+
+### Example
+
+\`\`\`typescript
+accessToken: {
+  secret: process.env.ACCESS_TOKEN_SECRET!,
+  expiresIn: '15m',
+  algorithm: 'HS256',
+  issuer: 'my-company-api',
+  audience: 'my-company-clients',
+  name: 'access_token',
+  setHeadersEnabled: true,
+  returnJson: true,
+}
+\`\`\`
+        `,
+			},
+			{
+				id: "refresh-token",
+				title: "Refresh Token",
+				content: `
+## Refresh Token
+
+The refresh token allows obtaining new access tokens without re-authentication. It implements automatic rotation for enhanced security.
+
+### Configuration
+
+\`\`\`typescript
+refreshToken: {
+  secret: string,
+  expiresIn: string,
+  algorithm: Algorithm,
+  issuer: string,
+  audience: string,
+  name: string,
+  setHeadersEnabled: boolean,
+  returnJson: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`secret\` | string | **Yes** | - | JWT signing secret. **Must be different from access token secret!** At least 32 characters. |
+| \`expiresIn\` | string | No | \`'7d'\` | Token lifetime. Typically 7-30 days. Longer than access token but not indefinite. |
+| \`algorithm\` | string | No | \`'HS256'\` | JWT signing algorithm. Should match access token for consistency. |
+| \`issuer\` | string | No | - | JWT \`iss\` claim. Can be same as access token. |
+| \`audience\` | string | No | - | JWT \`aud\` claim. Can be same as access token. |
+| \`name\` | string | No | \`'refresh_token'\` | Cookie name. |
+| \`setHeadersEnabled\` | boolean | No | \`true\` | Should be \`true\` - refresh tokens should always be in HTTP-only cookies. |
+| \`returnJson\` | boolean | No | \`false\` | Should be \`false\` - don't expose refresh token in response body for security. |
+
+### Token Rotation
+
+Nucleus implements **refresh token rotation** automatically:
+
+\`\`\`mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    
+    Note over C,S: First Refresh
+    C->>S: POST /auth/refresh (RT-1)
+    S->>S: Verify RT-1
+    S->>S: Generate new Access Token
+    S->>S: Generate RT-2 (new refresh token)
+    S->>S: Invalidate RT-1
+    S-->>C: New tokens (AT + RT-2)
+    
+    Note over C,S: Second Refresh
+    C->>S: POST /auth/refresh (RT-2)
+    S->>S: Verify RT-2
+    S->>S: Generate new Access Token
+    S->>S: Generate RT-3
+    S->>S: Invalidate RT-2
+    S-->>C: New tokens (AT + RT-3)
+    
+    Note over C,S: Attempted Replay Attack
+    C->>S: POST /auth/refresh (RT-1 - stolen)
+    S->>S: RT-1 already used!
+    S->>S: Revoke ALL user sessions
+    S-->>C: 401 Unauthorized
+\`\`\`
+
+### Security Benefits
+
+- **Single-use tokens** - Each refresh token can only be used once
+- **Replay detection** - Reusing old tokens triggers security response
+- **Limited exposure** - Compromised token has limited validity window
+        `,
+			},
+			{
+				id: "session-token",
+				title: "Session Token",
+				content: `
+## Session Token
+
+The session token uniquely identifies a user's session and enables device management, activity tracking, and remote logout capabilities.
+
+### Configuration
+
+\`\`\`typescript
+sessionToken: {
+  secret: string,
+  expiresIn: string,
+  algorithm: Algorithm,
+  name: string,
+  setHeadersEnabled: boolean,
+  returnJson: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`secret\` | string | **Yes** | - | JWT signing secret. **Must be unique** from other token secrets. At least 32 characters. |
+| \`expiresIn\` | string | No | \`'30d'\` | Session lifetime. Can be longer since sessions are tracked server-side and revocable. |
+| \`algorithm\` | string | No | \`'HS256'\` | JWT signing algorithm. |
+| \`name\` | string | No | \`'session_token'\` | Cookie name for the session identifier. |
+| \`setHeadersEnabled\` | boolean | No | \`true\` | Should be \`true\` for cookie-based session tracking. |
+| \`returnJson\` | boolean | No | \`false\` | Usually \`false\` - session ID is primarily for server-side tracking. |
+
+### Session Data Model
+
+Each session stores comprehensive information:
+
+\`\`\`mermaid
+erDiagram
+    USER_SESSION {
+        uuid id PK "Session identifier"
+        uuid userId FK "Owner of session"
+        string tokenHash "Hashed session token"
+        string deviceFingerprint "Browser+OS+Device hash"
+        string deviceName "Human-readable device name"
+        string deviceType "desktop/mobile/tablet"
+        string browserName "Chrome/Firefox/Safari/etc"
+        string browserVersion "Browser version number"
+        string osName "Windows/MacOS/Linux/iOS/Android"
+        string osVersion "OS version number"
+        string ipAddress "Login IP address"
+        string loginMethod "password/magic-link/oauth"
+        int trustScore "0-100 security score"
+        timestamp lastActivityAt "Last API request time"
+        timestamp createdAt "Session creation time"
+        timestamp expiresAt "Session expiration time"
+        boolean isActive "Is session valid"
+        timestamp revokedAt "When revoked (if revoked)"
+        string revokedReason "Why revoked"
+    }
+\`\`\`
+
+### Trust Score Calculation
+
+The trust score (0-100) is calculated based on:
+
+| Factor | Impact |
+|--------|--------|
+| New device | -25 points |
+| Unknown IP address | -20 points |
+| Missing browser info | -15 points |
+| Missing OS info | -15 points |
+| Unknown device type | -10 points |
+| Generic device name | -5 points |
+| Known device fingerprint | +20 points |
+| Known IP address | +15 points |
+
+### Low Trust Score Actions
+
+When trust score falls below 50:
+- Email notification sent to user
+- Session flagged for review
+- Additional verification may be required
+
+### Dual Storage
+
+Sessions are stored in both Redis and PostgreSQL:
+
+| Storage | Purpose |
+|---------|---------|
+| **Redis** | Fast validation on every request |
+| **PostgreSQL** | Persistent history, analytics, compliance |
+        `,
+			},
+		],
+	},
+	{
+		id: "classic-routes",
+		title: "Classic Routes",
+		subItems: [
+			{
+				id: "login",
+				title: "Login",
+				content: `
+## Login Route
+
+**POST** \`/auth/login\`
+
+Authenticates a user with email and password, creating a new session.
+
+### Configuration
+
+\`\`\`typescript
+login: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+  rememberMe: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/login'\` | Custom route path for the login endpoint. |
+| \`enabled\` | boolean | No | \`true\` | Enable or disable the login route entirely. |
+| \`isPublic\` | boolean | No | \`true\` | Must be \`true\` - unauthenticated users need to login. |
+| \`rememberMe\` | boolean | No | \`true\` | Enable "remember me" option for extended session duration. |
+
+### Request
+
+\`\`\`typescript
+POST /auth/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "userpassword123",
+  "rememberMe": true  // Optional, extends session
+}
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "email": "user@example.com",
+      "name": "John Doe",
+      "role": "user",
+      "createdAt": "2024-01-01T00:00:00.000Z"
+    },
+    "accessToken": "eyJhbGciOiJIUzI1NiIs...",  // If returnJson: true
+    "sessionId": "660e8400-e29b-41d4-a716-446655440001"
+  }
+}
+
+// Also sets HTTP-only cookies:
+// - access_token
+// - refresh_token  
+// - session_token
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 400 | "Email and password are required" | Missing fields |
+| 401 | "Invalid credentials" | Wrong email or password |
+| 403 | "Account is disabled" | User account deactivated |
+| 429 | "Too many attempts" | Rate limit exceeded |
+
+### Login Flow
+
+\`\`\`mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    participant D as Database
+    participant R as Redis
+
+    C->>S: POST /auth/login
+    S->>S: Validate input
+    S->>D: Find user by email
+    
+    alt User not found
+        S-->>C: 401 Invalid credentials
+    else User found
+        S->>S: Verify password (bcrypt)
+        alt Password invalid
+            S-->>C: 401 Invalid credentials
+        else Password valid
+            S->>S: Generate tokens
+            S->>S: Calculate trust score
+            S->>D: Save session
+            S->>R: Cache session
+            S->>S: Set cookies
+            S-->>C: 200 Success + tokens
+        end
+    end
+\`\`\`
+        `,
+			},
+			{
+				id: "register",
+				title: "Register",
+				content: `
+## Register Route
+
+**POST** \`/auth/register\`
+
+Creates a new user account.
+
+### Configuration
+
+\`\`\`typescript
+register: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/register'\` | Custom route path for registration. |
+| \`enabled\` | boolean | No | \`true\` | Enable/disable registration. Set \`false\` to prevent new signups. |
+| \`isPublic\` | boolean | No | \`true\` | Must be \`true\` for self-registration. |
+
+### Request
+
+\`\`\`typescript
+POST /auth/register
+Content-Type: application/json
+
+{
+  "email": "newuser@example.com",
+  "password": "securepassword123",
+  "name": "Jane Doe"  // Optional
+}
+\`\`\`
+
+### Success Response (201)
+
+\`\`\`typescript
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "email": "newuser@example.com",
+      "name": "Jane Doe",
+      "role": "user",
+      "createdAt": "2024-01-15T10:30:00.000Z"
+    }
+  }
+}
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 400 | "Email and password are required" | Missing fields |
+| 400 | "Invalid email format" | Email validation failed |
+| 400 | "Password too weak" | Doesn't meet requirements |
+| 409 | "Email already registered" | Duplicate email |
+
+### Password Requirements
+
+- Minimum 8 characters
+- Passwords are hashed with bcrypt (cost factor 12)
+- Original password is never stored
+        `,
+			},
+			{
+				id: "logout",
+				title: "Logout",
+				content: `
+## Logout Route
+
+**POST** \`/auth/logout\`
+
+Terminates the current session and clears authentication cookies.
+
+### Configuration
+
+\`\`\`typescript
+logout: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/logout'\` | Custom route path. |
+| \`enabled\` | boolean | No | \`true\` | Enable/disable logout functionality. |
+| \`isPublic\` | boolean | No | \`false\` | Should be \`false\` - only authenticated users can logout. |
+
+### Request
+
+\`\`\`typescript
+POST /auth/logout
+// Cookies automatically sent by browser
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "Logged out successfully"
+}
+
+// Clears cookies:
+// - access_token (expired)
+// - refresh_token (expired)
+// - session_token (expired)
+\`\`\`
+
+### What Happens
+
+\`\`\`mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    participant R as Redis
+    participant D as Database
+
+    C->>S: POST /auth/logout
+    S->>S: Extract session from cookie
+    S->>R: Delete session from cache
+    S->>D: Update session record
+    Note over D: isActive = false<br/>revokedAt = now()<br/>revokedReason = 'user_logout'
+    S->>S: Clear all auth cookies
+    S-->>C: 200 OK
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 401 | "Not authenticated" | No valid session |
+        `,
+			},
+			{
+				id: "refresh",
+				title: "Refresh",
+				content: `
+## Refresh Route
+
+**POST** \`/auth/refresh\`
+
+Obtains a new access token using the refresh token. Implements automatic token rotation.
+
+### Configuration
+
+\`\`\`typescript
+refresh: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/refresh'\` | Custom route path. |
+| \`enabled\` | boolean | No | \`true\` | Enable token refresh. |
+| \`isPublic\` | boolean | No | \`true\` | Should be \`true\` - access token may be expired when refreshing. |
+
+### Request
+
+\`\`\`typescript
+POST /auth/refresh
+// refresh_token cookie automatically sent
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIs..."  // If returnJson: true
+  }
+}
+
+// Sets new cookies:
+// - access_token (new)
+// - refresh_token (new - rotated)
+\`\`\`
+
+### Token Rotation Flow
+
+\`\`\`mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+
+    C->>S: POST /auth/refresh
+    Note over C: Sends refresh_token cookie
+    
+    S->>S: Verify refresh token JWT
+    
+    alt Invalid or expired
+        S-->>C: 401 Unauthorized
+    else Valid
+        S->>S: Generate new access token
+        S->>S: Generate new refresh token
+        S->>S: Invalidate old refresh token
+        S->>S: Set new cookies
+        S-->>C: 200 OK + new tokens
+    end
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 401 | "Invalid refresh token" | Token invalid or expired |
+| 401 | "Refresh token reuse detected" | Possible token theft |
+        `,
+			},
+			{
+				id: "password-change",
+				title: "Password Change",
+				content: `
+## Password Change Route
+
+**POST** \`/auth/password/change\`
+
+Allows authenticated users to change their password.
+
+### Configuration
+
+\`\`\`typescript
+passwordChange: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/password/change'\` | Custom route path. |
+| \`enabled\` | boolean | No | \`true\` | Enable password change. |
+| \`isPublic\` | boolean | No | \`false\` | Must be \`false\` - requires authentication. |
+
+### Request
+
+\`\`\`typescript
+POST /auth/password/change
+Content-Type: application/json
+
+{
+  "currentPassword": "oldpassword123",
+  "newPassword": "newsecurepassword456"
+}
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "Password changed successfully"
+}
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 400 | "Current and new password required" | Missing fields |
+| 400 | "New password too weak" | Doesn't meet requirements |
+| 401 | "Current password incorrect" | Wrong current password |
+| 401 | "Not authenticated" | No valid session |
+        `,
+			},
+			{
+				id: "me",
+				title: "Me",
+				content: `
+## Me Route
+
+**GET** \`/auth/me\`
+
+Returns information about the currently authenticated user.
+
+### Configuration
+
+\`\`\`typescript
+me: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+  includeProfile: boolean,
+  includeAddresses: boolean,
+  includePhones: boolean,
+  includeFiles: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/me'\` | Custom route path. |
+| \`enabled\` | boolean | No | \`true\` | Enable the me endpoint. |
+| \`isPublic\` | boolean | No | \`false\` | Must be \`false\` - requires authentication. |
+| \`includeProfile\` | boolean | No | \`true\` | Include data from \`profiles\` table if it exists. |
+| \`includeAddresses\` | boolean | No | \`false\` | Include data from \`addresses\` table if it exists. |
+| \`includePhones\` | boolean | No | \`false\` | Include data from \`phones\` table if it exists. |
+| \`includeFiles\` | boolean | No | \`false\` | Include data from user's files if file management is enabled. |
+
+### Request
+
+\`\`\`typescript
+GET /auth/me
+// Auth cookies automatically sent
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "user",
+    "createdAt": "2024-01-01T00:00:00.000Z",
+    "updatedAt": "2024-01-15T10:30:00.000Z",
+    
+    // If includeProfile: true
+    "profile": {
+      "bio": "Software developer",
+      "avatar": "https://...",
+      "website": "https://johndoe.com"
+    },
+    
+    // If includeAddresses: true
+    "addresses": [
+      {
+        "id": "...",
+        "street": "123 Main St",
+        "city": "New York",
+        "country": "USA"
+      }
+    ],
+    
+    // If includePhones: true
+    "phones": [
+      {
+        "id": "...",
+        "number": "+1234567890",
+        "type": "mobile"
+      }
+    ]
+  }
+}
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 401 | "Not authenticated" | No valid session |
+        `,
+			},
+		],
+	},
+	{
+		id: "password-reset",
+		title: "Password Reset",
+		subItems: [
+			{
+				id: "password-reset-how",
+				title: "How It Works",
+				content: `
+## Password Reset System
+
+Password reset allows users to recover access to their account when they've forgotten their password. It uses a secure token-based flow.
+
+### Prerequisites
+
+Password reset requires an **email provider** to be configured:
+
+\`\`\`typescript
+email: {
+  gmail: {
+    enabled: true,
+    json_file_path: './gmail-credentials.json',
+  }
+}
+\`\`\`
+
+### Complete Flow
+
+\`\`\`mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Client App
+    participant S as Nucleus Server
+    participant E as Email Service
+    participant D as Database
+
+    Note over U,D: Step 1: Request Reset
+    U->>C: Click "Forgot Password"
+    U->>C: Enter email address
+    C->>S: POST /auth/password/reset/request
+    S->>D: Find user by email
+    
+    alt User exists
+        S->>S: Generate secure token
+        S->>S: Hash token for storage
+        S->>D: Store hashed token
+        S->>E: Send reset email
+        E-->>U: Email with reset link
+    end
+    
+    S-->>C: "Check your email"
+    Note over S,C: Same response whether user exists or not (security)
+
+    Note over U,D: Step 2: Reset Password
+    U->>U: Open email
+    U->>C: Click reset link
+    C->>C: Extract token from URL
+    U->>C: Enter new password
+    C->>S: POST /auth/password/reset/confirm
+    S->>D: Find token (hashed)
+    
+    alt Token valid & not expired
+        S->>S: Hash new password
+        S->>D: Update user password
+        S->>D: Delete used token
+        S-->>C: "Password reset successful"
+    else Token invalid or expired
+        S-->>C: "Invalid or expired token"
+    end
+\`\`\`
+
+### Configuration
+
+\`\`\`typescript
+passwordReset: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+  redirectUrl: string,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/password/reset'\` | Base route. Creates \`/request\` and \`/confirm\` sub-routes. |
+| \`enabled\` | boolean | No | \`true\` | Enable password reset. **Automatically disabled if no email provider.** |
+| \`isPublic\` | boolean | No | \`true\` | Must be \`true\` - users who forgot password can't authenticate. |
+| \`redirectUrl\` | string | **Yes** | - | URL for the reset link in email. Token appended as \`?token=xxx\`. Example: \`'https://myapp.com/reset-password'\` |
+
+### Security Features
+
+- **Token hashing** - Only hashed tokens stored in database
+- **Single use** - Tokens deleted after successful use
+- **Expiration** - Tokens expire after 1 hour
+- **Rate limiting** - Prevents abuse
+- **Vague responses** - Same response whether email exists or not
+        `,
+			},
+			{
+				id: "password-reset-request",
+				title: "Request Route",
+				content: `
+## Request Password Reset
+
+**POST** \`/auth/password/reset/request\`
+
+Initiates the password reset process by sending a reset link to the user's email.
+
+### Request
+
+\`\`\`typescript
+POST /auth/password/reset/request
+Content-Type: application/json
+
+{
+  "email": "user@example.com"
+}
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "If an account exists with this email, a reset link has been sent"
+}
+\`\`\`
+
+> **Security Note:** The response is intentionally vague. It doesn't reveal whether the email exists in the system. This prevents email enumeration attacks.
+
+### Email Sent
+
+If the email exists, the user receives:
+
+\`\`\`
+Subject: Password Reset Request
+
+Click the link below to reset your password:
+https://yourapp.com/reset-password?token=abc123def456...
+
+This link expires in 1 hour.
+
+If you didn't request this, please ignore this email.
+\`\`\`
+
+### Token Storage
+
+\`\`\`typescript
+// passwordResetTokens table
+{
+  id: 'uuid',
+  userId: 'uuid',
+  tokenHash: 'hashed-token',  // bcrypt hash
+  email: 'user@example.com',
+  expiresAt: '2024-01-15T11:30:00Z',  // 1 hour from creation
+  createdAt: '2024-01-15T10:30:00Z'
+}
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 400 | "Email is required" | Missing email field |
+| 400 | "Invalid email format" | Email validation failed |
+| 429 | "Too many requests" | Rate limit exceeded |
+| 503 | "Email service unavailable" | Email provider error |
+        `,
+			},
+			{
+				id: "password-reset-confirm",
+				title: "Confirm Route",
+				content: `
+## Confirm Password Reset
+
+**POST** \`/auth/password/reset/confirm\`
+
+Completes the password reset using the token from the email link.
+
+### Request
+
+\`\`\`typescript
+POST /auth/password/reset/confirm
+Content-Type: application/json
+
+{
+  "token": "abc123def456...",  // From email link
+  "newPassword": "mynewsecurepassword123"
+}
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "Password has been reset successfully"
+}
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 400 | "Token and new password required" | Missing fields |
+| 400 | "Password too weak" | Doesn't meet requirements |
+| 400 | "Invalid or expired token" | Token not found or expired |
+
+### What Happens
+
+1. Server looks up token hash in database
+2. Verifies token hasn't expired (1 hour limit)
+3. Hashes new password with bcrypt
+4. Updates user's password in database
+5. Deletes the reset token (single use)
+6. Optionally: Revokes all existing sessions
+
+### Client Implementation
+
+\`\`\`typescript
+// Your reset password page
+const ResetPasswordPage = () => {
+  const token = new URLSearchParams(location.search).get('token')
+  
+  const handleSubmit = async (newPassword: string) => {
+    const response = await fetch('/auth/password/reset/confirm', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token, newPassword })
+    })
+    
+    if (response.ok) {
+      // Redirect to login
+      window.location.href = '/login'
+    }
+  }
+}
+\`\`\`
+        `,
+			},
+		],
+	},
+	{
+		id: "magic-link",
+		title: "Magic Link",
+		subItems: [
+			{
+				id: "magic-link-how",
+				title: "How It Works",
+				content: `
+## Magic Link Authentication
+
+Magic links provide **passwordless authentication** - users sign in by clicking a link sent to their email, with no password required.
+
+### Prerequisites
+
+Magic link requires an **email provider**:
+
+\`\`\`typescript
+email: {
+  gmail: {
+    enabled: true,
+    json_file_path: './gmail-credentials.json',
+  }
+}
+\`\`\`
+
+### Complete Flow
+
+\`\`\`mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Client App
+    participant S as Nucleus Server
+    participant E as Email Service
+    participant D as Database
+    participant R as Redis
+
+    Note over U,R: Step 1: Request Magic Link
+    U->>C: Enter email address
+    C->>S: POST /auth/magic-link
+    S->>D: Check if user exists
+    
+    alt New user
+        S->>D: Create user account
+    end
+    
+    S->>S: Generate secure token
+    S->>D: Store magic link token
+    S->>E: Send magic link email
+    E-->>U: Email with login link
+    S-->>C: "Check your email"
+
+    Note over U,R: Step 2: Verify & Login
+    U->>U: Open email
+    U->>S: GET /auth/magic-link/verify?token=xxx
+    S->>D: Find and validate token
+    
+    alt Token valid
+        S->>S: Generate auth tokens
+        S->>R: Create session
+        S->>D: Save session
+        S->>D: Delete magic token
+        S-->>U: Redirect to app with cookies
+    else Token invalid
+        S-->>U: Error page
+    end
+\`\`\`
+
+### Configuration
+
+\`\`\`typescript
+magicLink: {
+  route: string,
+  verifyRoute: string,
+  enabled: boolean,
+  isPublic: boolean,
+  expiresIn: string,
+  redirectUrl: string,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/magic-link'\` | Route for requesting magic link. |
+| \`verifyRoute\` | string | No | \`'/auth/magic-link/verify'\` | Route for verifying magic link token. |
+| \`enabled\` | boolean | No | \`true\` | Enable magic link. **Auto-disabled if no email provider.** |
+| \`isPublic\` | boolean | No | \`true\` | Must be \`true\` for passwordless login. |
+| \`expiresIn\` | string | No | \`'15m'\` | Token expiration. Keep short (10-30 min). |
+| \`redirectUrl\` | string | **Yes** | - | Where to redirect after successful verification. Example: \`'https://myapp.com/dashboard'\` |
+
+### Benefits
+
+| Feature | Password Auth | Magic Link |
+|---------|---------------|------------|
+| Password management | Required | Not needed |
+| Credential stuffing risk | High | None |
+| Phishing resistance | Low | Higher |
+| User friction | Medium | Low |
+| Account recovery | Complex | Built-in |
+
+### Use Cases
+
+- **SaaS applications** - Reduce signup friction
+- **Infrequent users** - No password to remember
+- **B2B portals** - Verified corporate emails
+- **Email verification** - Magic link = verified email
+        `,
+			},
+			{
+				id: "magic-link-request",
+				title: "Request Route",
+				content: `
+## Request Magic Link
+
+**POST** \`/auth/magic-link\`
+
+Sends a magic link to the user's email for passwordless authentication.
+
+### Request
+
+\`\`\`typescript
+POST /auth/magic-link
+Content-Type: application/json
+
+{
+  "email": "user@example.com"
+}
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "Magic link sent to your email"
+}
+\`\`\`
+
+### Email Sent
+
+\`\`\`
+Subject: Your Login Link
+
+Click below to sign in:
+https://api.yourapp.com/auth/magic-link/verify?token=abc123...
+
+This link expires in 15 minutes.
+
+If you didn't request this, please ignore this email.
+\`\`\`
+
+### Auto-Registration
+
+If the email doesn't exist:
+1. A new user account is created automatically
+2. User gets the same magic link email
+3. Clicking the link logs them in to their new account
+
+This is great for reducing signup friction!
+
+### Token Storage
+
+\`\`\`typescript
+// magicLinkTokens table
+{
+  id: 'uuid',
+  userId: 'uuid',
+  tokenHash: 'hashed-token',
+  email: 'user@example.com',
+  expiresAt: '2024-01-15T10:45:00Z',  // 15 min from creation
+  createdAt: '2024-01-15T10:30:00Z'
+}
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 400 | "Email is required" | Missing email |
+| 400 | "Invalid email format" | Validation failed |
+| 429 | "Too many requests" | Rate limit |
+| 503 | "Email service unavailable" | Provider error |
+        `,
+			},
+			{
+				id: "magic-link-verify",
+				title: "Verify Route",
+				content: `
+## Verify Magic Link
+
+**GET** \`/auth/magic-link/verify?token=xxx\`
+
+Verifies the magic link token and creates an authenticated session.
+
+### Request
+
+\`\`\`
+GET /auth/magic-link/verify?token=abc123def456...
+\`\`\`
+
+### Success Flow
+
+On successful verification:
+
+1. Token is validated against database
+2. User session is created
+3. Auth cookies are set
+4. User is redirected to \`redirectUrl\`
+
+\`\`\`
+HTTP/1.1 302 Found
+Location: https://myapp.com/dashboard
+Set-Cookie: access_token=...; HttpOnly; Secure; SameSite=Strict
+Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Strict
+Set-Cookie: session_token=...; HttpOnly; Secure; SameSite=Strict
+\`\`\`
+
+### Error Response
+
+On invalid or expired token:
+
+\`\`\`typescript
+{
+  "success": false,
+  "message": "Invalid or expired magic link"
+}
+\`\`\`
+
+### Security Notes
+
+- **Single use** - Token deleted after verification
+- **Short expiration** - 15 minutes default
+- **HTTPS only** - Token in URL is sensitive
+- **Rate limited** - Prevents brute force
+
+### Client-Side Handling
+
+The magic link points directly to your API. After verification, users are redirected to your app with cookies already set:
+
+\`\`\`typescript
+// In your dashboard component
+useEffect(() => {
+  // User arrives here already authenticated
+  // Cookies are set by the redirect
+  fetchUserData()  // Will work immediately
+}, [])
+\`\`\`
+        `,
+			},
+		],
+	},
+	{
+		id: "sessions",
+		title: "Sessions",
+		subItems: [
+			{
+				id: "sessions-how",
+				title: "How It Works",
+				content: `
+## Session Management System
+
+Nucleus provides enterprise-grade session management with device tracking, security monitoring, and remote control capabilities.
+
+### Architecture
+
+\`\`\`mermaid
+flowchart TB
+    subgraph Client
+        C1[Browser]
+        C2[Mobile App]
+        C3[Another Browser]
+    end
+    
+    subgraph Server
+        S[Session Middleware]
+    end
+    
+    subgraph Storage
+        R[Redis Cache<br/>Fast validation]
+        D[PostgreSQL<br/>Persistent storage]
+    end
+    
+    C1 -->|session_token| S
+    C2 -->|session_token| S
+    C3 -->|session_token| S
+    S -->|Read/Write| R
+    S -->|Persist| D
+\`\`\`
+
+### Dual Storage Strategy
+
+| Storage | Purpose | Data |
+|---------|---------|------|
+| **Redis** | Fast session validation | Session ID, user ID, last activity |
+| **PostgreSQL** | Persistent record | Full session details, history |
+
+### Configuration
+
+\`\`\`typescript
+sessions: {
+  route: string,
+  enabled: boolean,
+  isPublic: boolean,
+  maxActiveSessions: number,
+  inactivityTimeout: string,
+  allowMultipleDevices: boolean,
+  trustNewDevices: boolean,
+  notifyOnNewDevice: boolean,
+}
+\`\`\`
+
+### Configuration Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`route\` | string | No | \`'/auth/sessions'\` | Base route for session management endpoints. |
+| \`enabled\` | boolean | No | \`true\` | Enable session management features. |
+| \`isPublic\` | boolean | No | \`false\` | Must be \`false\` - requires authentication. |
+| \`maxActiveSessions\` | number | No | \`5\` | Maximum concurrent sessions per user. When exceeded, oldest session is revoked. |
+| \`inactivityTimeout\` | string | No | \`'30d'\` | Auto-expire sessions after this period of inactivity. Format: \`'1h'\`, \`'7d'\`, \`'30d'\`. |
+| \`allowMultipleDevices\` | boolean | No | \`true\` | If \`false\`, new login revokes all other sessions (single device mode). |
+| \`trustNewDevices\` | boolean | No | \`true\` | If \`false\`, new device logins require additional verification. |
+| \`notifyOnNewDevice\` | boolean | No | \`true\` | Send email alert when user logs in from new device. |
+
+### Session Lifecycle
+
+\`\`\`mermaid
+stateDiagram-v2
+    [*] --> Active: Login
+    Active --> Active: Activity
+    Active --> Expired: Inactivity Timeout
+    Active --> Revoked: Manual Logout
+    Active --> Revoked: Remote Revoke
+    Active --> Revoked: Max Sessions Exceeded
+    Expired --> [*]
+    Revoked --> [*]
+\`\`\`
+        `,
+			},
+			{
+				id: "sessions-list",
+				title: "List Sessions",
+				content: `
+## List User Sessions
+
+**GET** \`/auth/sessions\`
+
+Returns all active sessions for the authenticated user.
+
+### Request
+
+\`\`\`typescript
+GET /auth/sessions
+// Auth cookies required
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "data": [
+    {
+      "id": "session-uuid-1",
+      "deviceName": "Chrome on MacOS",
+      "deviceType": "desktop",
+      "browserName": "Chrome",
+      "browserVersion": "120.0.0",
+      "osName": "MacOS",
+      "osVersion": "14.2",
+      "ipAddress": "192.168.1.1",
+      "trustScore": 85,
+      "lastActivityAt": "2024-01-15T10:30:00Z",
+      "createdAt": "2024-01-01T08:00:00Z",
+      "isCurrent": true
+    },
+    {
+      "id": "session-uuid-2",
+      "deviceName": "Safari on iPhone",
+      "deviceType": "mobile",
+      "browserName": "Safari",
+      "browserVersion": "17.0",
+      "osName": "iOS",
+      "osVersion": "17.2",
+      "ipAddress": "10.0.0.5",
+      "trustScore": 90,
+      "lastActivityAt": "2024-01-14T15:20:00Z",
+      "createdAt": "2024-01-10T12:00:00Z",
+      "isCurrent": false
+    }
+  ]
+}
+\`\`\`
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`id\` | string | Unique session identifier |
+| \`deviceName\` | string | Human-readable device name |
+| \`deviceType\` | string | \`'desktop'\` \\| \`'mobile'\` \\| \`'tablet'\` |
+| \`browserName\` | string | Browser name |
+| \`browserVersion\` | string | Browser version |
+| \`osName\` | string | Operating system |
+| \`osVersion\` | string | OS version |
+| \`ipAddress\` | string | Login IP address |
+| \`trustScore\` | number | Security score (0-100) |
+| \`lastActivityAt\` | string | Last API request timestamp |
+| \`createdAt\` | string | Session creation timestamp |
+| \`isCurrent\` | boolean | Is this the requesting session |
+
+### Use Cases
+
+- Show user their active devices
+- Security dashboard
+- Identify suspicious sessions
+        `,
+			},
+			{
+				id: "sessions-revoke",
+				title: "Revoke Session",
+				content: `
+## Revoke Single Session
+
+**DELETE** \`/auth/sessions/:id\`
+
+Revokes (terminates) a specific session.
+
+### Request
+
+\`\`\`typescript
+DELETE /auth/sessions/session-uuid-123
+// Auth cookies required
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "Session revoked successfully"
+}
+\`\`\`
+
+### What Happens
+
+\`\`\`mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    participant R as Redis
+    participant D as Database
+
+    C->>S: DELETE /auth/sessions/:id
+    S->>S: Verify session belongs to user
+    S->>R: Delete session from cache
+    S->>D: Update session record
+    Note over D: isActive = false<br/>revokedAt = now()<br/>revokedReason = 'user_revoked'
+    S-->>C: 200 Success
+    
+    Note over C,D: Next request from revoked session
+    C->>S: Any request with old session
+    S->>R: Session not found
+    S-->>C: 401 Unauthorized
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 401 | "Not authenticated" | No valid session |
+| 403 | "Cannot revoke another user's session" | Session ownership check failed |
+| 404 | "Session not found" | Invalid session ID |
+
+### Notes
+
+- Users can only revoke their own sessions
+- Revoking current session is allowed (logs user out)
+- Revoked sessions are kept in database for audit purposes
+        `,
+			},
+			{
+				id: "sessions-revoke-all",
+				title: "Revoke All Sessions",
+				content: `
+## Revoke All Sessions
+
+**DELETE** \`/auth/sessions\`
+
+Revokes all sessions for the current user.
+
+### Request
+
+\`\`\`typescript
+DELETE /auth/sessions?includeCurrent=false
+// Auth cookies required
+\`\`\`
+
+### Query Parameters
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| \`includeCurrent\` | boolean | \`false\` | If \`true\`, also revokes the current session (full logout). |
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "message": "All sessions revoked",
+  "count": 4  // Number of sessions revoked
+}
+\`\`\`
+
+### Use Cases
+
+**Security Breach Response**
+\`\`\`typescript
+// User suspects account compromise
+DELETE /auth/sessions?includeCurrent=true
+// All sessions revoked, user must re-authenticate
+\`\`\`
+
+**Password Change Enforcement**
+\`\`\`typescript
+// After password change, revoke other sessions
+DELETE /auth/sessions?includeCurrent=false
+// Current session remains, others logged out
+\`\`\`
+
+**Account Recovery**
+\`\`\`typescript
+// Clean slate after compromise
+DELETE /auth/sessions?includeCurrent=true
+// User re-authenticates fresh
+\`\`\`
+
+### Error Responses
+
+| Status | Message | Cause |
+|--------|---------|-------|
+| 401 | "Not authenticated" | No valid session |
+        `,
+			},
+			{
+				id: "sessions-stats",
+				title: "Session Statistics",
+				content: `
+## Session Statistics
+
+**GET** \`/auth/sessions/stats\`
+
+Returns session statistics and analytics for the current user.
+
+### Request
+
+\`\`\`typescript
+GET /auth/sessions/stats
+// Auth cookies required
+\`\`\`
+
+### Success Response (200)
+
+\`\`\`typescript
+{
+  "success": true,
+  "data": {
+    "totalSessions": 12,
+    "activeSessions": 3,
+    "revokedSessions": 9,
+    "uniqueDevices": 4,
+    "uniqueIPs": 6,
+    "lastLoginAt": "2024-01-15T10:30:00Z",
+    "oldestActiveSession": "2024-01-01T08:00:00Z",
+    "averageTrustScore": 82
+  }
+}
+\`\`\`
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`totalSessions\` | number | All-time session count |
+| \`activeSessions\` | number | Currently active sessions |
+| \`revokedSessions\` | number | Revoked/expired sessions |
+| \`uniqueDevices\` | number | Distinct device fingerprints |
+| \`uniqueIPs\` | number | Distinct IP addresses |
+| \`lastLoginAt\` | string | Most recent login timestamp |
+| \`oldestActiveSession\` | string | Oldest active session timestamp |
+| \`averageTrustScore\` | number | Average trust score across active sessions |
+
+### Use Cases
+
+- **User security dashboard** - Show account activity summary
+- **Anomaly detection** - Unusual number of sessions/IPs
+- **Compliance reporting** - Access pattern analysis
+        `,
+			},
+		],
+	},
+];