@bluealba/platform-cli 1.0.1 → 1.0.2

package/docs/architecture/authentication-system.mdx

@@ -0,0 +1,903 @@
+---
+title: Authentication System
+description: Deep dive into the Blue Alba Platform authentication architecture - JWT, multi-IDP, OAuth 2.0, API keys, service auth, and impersonation
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Blue Alba Platform implements a comprehensive authentication system that supports multiple identity providers, authentication methods, and advanced features like user impersonation.
+
+## Authentication Architecture Overview
+
+The platform supports multiple authentication mechanisms:
+
+<CardGrid stagger>
+  <Card title="JWT-Based Sessions" icon="approve-check">
+    Primary authentication using JWT tokens stored in HTTP-only cookies for browser-based access
+  </Card>
+
+  <Card title="Multi-IDP Support" icon="star">
+    Integration with multiple identity providers: Okta, EntraId, OneLogin, Github, AWS Cognito
+  </Card>
+
+  <Card title="API Key Authentication" icon="seti:lock">
+    Long-lived API keys for programmatic access and integrations
+  </Card>
+
+  <Card title="Service-to-Service Auth" icon="seti:config">
+    Secure service authentication using shared secrets for internal communication
+  </Card>
+
+  <Card title="User Impersonation" icon="random">
+    Admin capability to impersonate users for support and debugging
+  </Card>
+
+  <Card title="OAuth 2.0 / OIDC" icon="seti:graphql">
+    Standard OAuth 2.0 Authorization Code flow with OpenID Connect
+  </Card>
+</CardGrid>
+
+---
+
+## JWT-Based Authentication
+
+### JWT Token Structure
+
+The platform uses JWT (JSON Web Tokens) as the primary session mechanism.
+
+**JWT Payload**:
+
+```typescript
+interface JWTPayload {
+  // User identity
+  id: string;                          // User ID
+  username: string;                    // Email or username
+  displayName: string;                 // Full name
+  authProviderName: string;            // IDP name (okta, entraid, etc.)
+
+  // Authorization
+  groups: string[];                    // User's groups
+  applications: string[];              // Allowed application IDs
+
+  // Optional fields
+  orig?: any;                          // Original user object from IDP
+  impersonatedBy?: {                   // If user is being impersonated
+    username: string;
+    displayName: string;
+    orig?: any;
+  };
+
+  // Standard JWT claims
+  iat: number;                         // Issued at
+  exp: number;                         // Expiration
+  iss: string;                         // Issuer
+  aud: string;                         // Audience
+}
+```
+
+**Example JWT**:
+
+```json
+{
+  "id": "user-abc-123",
+  "username": "john.doe@acme.com",
+  "displayName": "John Doe",
+  "authProviderName": "okta",
+  "groups": ["admins", "users"],
+  "applications": ["app-1", "app-2", "app-3"],
+  "iat": 1704067200,
+  "exp": 1704153600,
+  "iss": "https://platform.acme.com",
+  "aud": "platform-users"
+}
+```
+
+### Cookie-Based Storage
+
+JWT tokens are stored in HTTP-only cookies for security.
+
+**Cookie Configuration**:
+
+```typescript
+// Set authentication cookie
+response.cookie(AUTH_COOKIE_NAME, jwtToken, {
+  httpOnly: true,        // Not accessible via JavaScript
+  secure: true,          // Only sent over HTTPS
+  sameSite: 'lax',       // CSRF protection
+  maxAge: 24 * 60 * 60 * 1000,  // 24 hours
+  path: '/',             // Available for all paths
+  domain: '.platform.com' // Available for all subdomains
+});
+```
+
+<Aside type="tip" title="Security Benefits">
+  HTTP-only cookies prevent XSS attacks since JavaScript cannot access the token. The `secure` flag ensures tokens are only sent over HTTPS. The `sameSite` attribute provides CSRF protection.
+</Aside>
+
+### Token Validation Flow
+
+```
+┌──────────┐
+│ Browser  │
+└────┬─────┘
+     │ GET /api/data
+     │ Cookie: auth_token=eyJhbGc...
+     ▼
+┌─────────────────────────────────┐
+│  Gateway Authentication Guard   │
+│                                 │
+│  1. Extract token from cookie   │
+│     ↓                           │
+│  2. Verify JWT signature        │
+│     ↓                           │
+│  3. Check expiration            │
+│     ↓                           │
+│  4. Decode payload              │
+│     ↓                           │
+│  5. Create AuthUser object      │
+└────┬────────────────────────────┘
+     │ AuthUser { username, groups, ... }
+     ▼
+┌─────────────────────────────────┐
+│  Store in Platform Context      │
+└─────────────────────────────────┘
+```
+
+**Implementation**:
+
+```typescript
+@Injectable()
+export class AuthenticationService {
+  async validateToken(token: string): Promise<AuthUserWithApplications> {
+    // Get JWT secret (can be stored in parameters table)
+    const secret = await this.parametersService.getParameterOrDefault(
+      'AUTHENTICATION_SESSION_JWT_SECRET',
+      this.configService.get<string>('jwtSecret')
+    );
+
+    // Verify and decode JWT
+    const payload = this.jwtService.verify(token, { secret });
+
+    // Map to AuthUser
+    return {
+      id: payload.id,
+      username: payload.username,
+      displayName: payload.displayName,
+      authProviderName: payload.authProviderName,
+      groups: payload.groups || [],
+      applications: payload.applications || [],
+      impersonatedBy: payload.impersonatedBy,
+      orig: payload.orig
+    };
+  }
+}
+```
+
+---
+
+## Multi-IDP Architecture
+
+The platform supports multiple identity providers through a pluggable architecture.
+
+### Supported Identity Providers
+
+<Tabs>
+  <TabItem label="Okta">
+    **Configuration**:
+    ```bash
+    OKTA_DOMAIN=dev-12345.okta.com
+    OKTA_CLIENT_ID=0oa1b2c3d4e5f6g7h8i9
+    OKTA_CLIENT_SECRET=secret
+    OKTA_REDIRECT_URI=https://platform.com/auth/okta/callback
+    ```
+
+    **Features**:
+    - User authentication via Okta
+    - Group synchronization from Okta groups
+    - Automatic user provisioning
+    - Support for Okta Universal Directory
+  </TabItem>
+
+  <TabItem label="Microsoft EntraId">
+    **Configuration**:
+    ```bash
+    ENTRAID_TENANT_ID=12345678-1234-1234-1234-123456789012
+    ENTRAID_CLIENT_ID=87654321-4321-4321-4321-210987654321
+    ENTRAID_CLIENT_SECRET=secret
+    ENTRAID_REDIRECT_URI=https://platform.com/auth/entraid/callback
+    ```
+
+    **Features**:
+    - Azure AD authentication
+    - Integration with Microsoft 365
+    - Security group synchronization
+    - Conditional access policy support
+  </TabItem>
+
+  <TabItem label="OneLogin">
+    **Configuration**:
+    ```bash
+    ONELOGIN_SUBDOMAIN=acme
+    ONELOGIN_CLIENT_ID=abc123def456
+    ONELOGIN_CLIENT_SECRET=secret
+    ONELOGIN_REDIRECT_URI=https://platform.com/auth/onelogin/callback
+    ONELOGIN_REGION=us
+    ```
+
+    **Features**:
+    - OneLogin SSO
+    - Role and group mapping
+    - API access for user management
+  </TabItem>
+
+  <TabItem label="Github">
+    **Configuration**:
+    ```bash
+    GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8
+    GITHUB_CLIENT_SECRET=secret
+    GITHUB_REDIRECT_URI=https://platform.com/auth/github/callback
+    ```
+
+    **Features**:
+    - GitHub OAuth authentication
+    - Organization membership sync
+    - Team-based authorization
+  </TabItem>
+
+  <TabItem label="AWS Cognito">
+    **Configuration**:
+    ```bash
+    COGNITO_USER_POOL_ID=us-east-1_ABC123DEF
+    COGNITO_CLIENT_ID=1a2b3c4d5e6f7g8h9i0j1k2l3m
+    COGNITO_CLIENT_SECRET=secret
+    COGNITO_DOMAIN=acme-auth.auth.us-east-1.amazoncognito.com
+    COGNITO_REDIRECT_URI=https://platform.com/auth/cognito/callback
+    COGNITO_REGION=us-east-1
+    ```
+
+    **Features**:
+    - AWS Cognito user pools
+    - Custom attributes support
+    - MFA integration
+    - Lambda trigger support
+  </TabItem>
+</Tabs>
+
+### OAuth Provider Architecture
+
+**Location**: `apps/pae-nestjs-gateway-service/src/authentication/oauth-providers/`
+
+Each provider implements a standard interface:
+
+```typescript
+interface OAuthProvider {
+  // Provider metadata
+  name: string;
+  displayName: string;
+
+  // OAuth configuration
+  getConfig(): OAuthConfig;
+
+  // User info mapping
+  mapUserInfo(rawUserInfo: any): UserInfo;
+
+  // Group synchronization
+  getUserGroups(userId: string, accessToken: string): Promise<string[]>;
+}
+```
+
+**Provider Structure**:
+
+```
+oauth-providers/
+├── okta/
+│   ├── index.ts              # Provider implementation
+│   ├── provider.config.ts    # OAuth configuration
+│   ├── mapper.ts             # User info mapping
+│   ├── types.ts              # TypeScript types
+│   └── groups.service.ts     # Group sync logic
+├── entra-id/
+│   ├── index.ts
+│   ├── provider.config.ts
+│   ├── mapper.ts
+│   └── api/                  # MS Graph API integration
+│       ├── get-groups.ts
+│       └── get-groups-for-user.ts
+├── onelogin/
+│   ├── index.ts
+│   ├── provider.config.ts
+│   ├── mapper.ts
+│   └── api/                  # OneLogin API integration
+├── github/
+│   ├── index.ts
+│   ├── provider.config.ts
+│   └── mapper.ts
+├── cognito/
+│   ├── index.ts
+│   ├── provider.config.ts
+│   ├── mapper.ts
+│   └── api/                  # Cognito API integration
+└── providers.registry.ts     # Provider registration
+```
+
+---
+
+## OAuth 2.0 Authorization Code Flow
+
+The platform implements the standard OAuth 2.0 Authorization Code flow with PKCE.
+
+### Authentication Flow Diagram
+
+```
+┌─────────┐                                           ┌──────────┐
+│ Browser │                                           │   IDP    │
+│         │                                           │  (Okta)  │
+└────┬────┘                                           └─────┬────┘
+     │                                                      │
+     │  1. User clicks "Login"                             │
+     │────────────────────────────────▶                    │
+     │                                                      │
+     │  2. Redirect to /auth/login                         │
+     │────────────────────────────────▶                    │
+     │                                                      │
+     │  3. Redirect to IDP login page                      │
+     │─────────────────────────────────────────────────────▶
+     │     GET /authorize?                                 │
+     │         client_id=...                               │
+     │         &redirect_uri=...                           │
+     │         &response_type=code                         │
+     │         &scope=openid profile email                 │
+     │         &state=random-state                         │
+     │         &code_challenge=...                         │
+     │                                                      │
+     │  4. User authenticates with IDP                     │
+     │◀─────────────────────────────────────────────────────
+     │     (Username + Password + MFA)                     │
+     │                                                      │
+     │  5. IDP redirects back with code                    │
+     │◀─────────────────────────────────────────────────────
+     │     GET /auth/callback?                             │
+     │         code=auth-code-123                          │
+     │         &state=random-state                         │
+     │                                                      │
+     │  6. Gateway receives callback                       │
+     │────────────────────────────────▶                    │
+     │                                                      │
+     │  7. Exchange code for tokens                        │
+     │─────────────────────────────────────────────────────▶
+     │     POST /token                                     │
+     │         code=auth-code-123                          │
+     │         &client_id=...                              │
+     │         &client_secret=...                          │
+     │         &redirect_uri=...                           │
+     │         &code_verifier=...                          │
+     │                                                      │
+     │  8. Receive tokens                                  │
+     │◀─────────────────────────────────────────────────────
+     │     {                                               │
+     │       "access_token": "eyJhbGc...",                 │
+     │       "id_token": "eyJhbGc...",                     │
+     │       "refresh_token": "...",                       │
+     │       "expires_in": 3600                            │
+     │     }                                               │
+     │                                                      │
+     │  9. Get user info from IDP                          │
+     │─────────────────────────────────────────────────────▶
+     │     GET /userinfo                                   │
+     │     Authorization: Bearer eyJhbGc...                │
+     │                                                      │
+     │  10. Receive user info                              │
+     │◀─────────────────────────────────────────────────────
+     │     {                                               │
+     │       "sub": "user-123",                            │
+     │       "email": "john@acme.com",                     │
+     │       "name": "John Doe"                            │
+     │     }                                               │
+     │                                                      │
+     │  11. Create platform user (if new)                  │
+     │  12. Get user's groups                              │
+     │  13. Generate platform JWT                          │
+     │  14. Set HTTP-only cookie                           │
+     │◀────────────────────────────────                    │
+     │     Set-Cookie: auth_token=eyJhbGc...               │
+     │                                                      │
+     │  15. Redirect to application                        │
+     │◀────────────────────────────────                    │
+     │     Location: /                                     │
+     │                                                      │
+     │  16. Access application with cookie                 │
+     │────────────────────────────────▶                    │
+     │                                                      │
+```
+
+### Implementation Details
+
+<Tabs>
+  <TabItem label="1. Login Initiation">
+    ```typescript
+    // apps/pae-nestjs-gateway-service/src/authentication/authentication.controller.ts
+
+    @Get('auth/login')
+    async login(
+      @Query('provider') provider: string,
+      @Res() response: FastifyReply
+    ) {
+      // Get OAuth provider configuration
+      const oauthProvider = this.providersRegistry.getProvider(provider);
+      const config = oauthProvider.getConfig();
+
+      // Generate PKCE code verifier and challenge
+      const codeVerifier = generateCodeVerifier();
+      const codeChallenge = generateCodeChallenge(codeVerifier);
+
+      // Generate state for CSRF protection
+      const state = generateRandomState();
+
+      // Store in session
+      await this.sessionStore.set(state, {
+        codeVerifier,
+        provider,
+        returnTo: request.query.returnTo
+      });
+
+      // Build authorization URL
+      const authUrl = new URL(config.authorizationEndpoint);
+      authUrl.searchParams.set('client_id', config.clientId);
+      authUrl.searchParams.set('redirect_uri', config.redirectUri);
+      authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('scope', config.scope);
+      authUrl.searchParams.set('state', state);
+      authUrl.searchParams.set('code_challenge', codeChallenge);
+      authUrl.searchParams.set('code_challenge_method', 'S256');
+
+      // Redirect to IDP
+      response.redirect(authUrl.toString());
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="2. Callback Handling">
+    ```typescript
+    @Get('auth/callback')
+    async callback(
+      @Query('code') code: string,
+      @Query('state') state: string,
+      @Res() response: FastifyReply
+    ) {
+      // Retrieve session data
+      const session = await this.sessionStore.get(state);
+      if (!session) {
+        throw new UnauthorizedException('Invalid state');
+      }
+
+      // Get provider
+      const oauthProvider = this.providersRegistry.getProvider(session.provider);
+      const config = oauthProvider.getConfig();
+
+      // Exchange code for tokens
+      const tokenResponse = await axios.post(config.tokenEndpoint, {
+        grant_type: 'authorization_code',
+        code,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        redirect_uri: config.redirectUri,
+        code_verifier: session.codeVerifier
+      });
+
+      const { access_token, id_token, refresh_token } = tokenResponse.data;
+
+      // Get user info
+      const userInfoResponse = await axios.get(config.userInfoEndpoint, {
+        headers: {
+          Authorization: `Bearer ${access_token}`
+        }
+      });
+
+      // Map to platform user
+      const userInfo = oauthProvider.mapUserInfo(userInfoResponse.data);
+
+      // Continue with user creation/update...
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="3. User Provisioning">
+    ```typescript
+    // Create or update user in platform database
+    let user = await this.usersService.findByEmail(userInfo.email);
+
+    if (!user) {
+      // Create new user
+      user = await this.usersService.create({
+        email: userInfo.email,
+        displayName: userInfo.name,
+        authProviderName: session.provider,
+        authProviderUserId: userInfo.id,
+        tenantId: userInfo.tenantId // Determined from email domain or IDP config
+      });
+    } else {
+      // Update existing user
+      await this.usersService.update(user.id, {
+        displayName: userInfo.name,
+        lastLoginAt: new Date()
+      });
+    }
+
+    // Sync groups from IDP
+    const groups = await oauthProvider.getUserGroups(userInfo.id, access_token);
+    await this.groupsService.syncUserGroups(user.id, groups);
+
+    // Get user's allowed applications
+    const applications = await this.authzService.getAllowedApplications(user.username);
+
+    // Generate platform JWT
+    const jwtPayload = {
+      id: user.id,
+      username: user.email,
+      displayName: user.displayName,
+      authProviderName: session.provider,
+      groups,
+      applications: applications.map(app => app.id)
+    };
+
+    const jwtToken = this.jwtService.sign(jwtPayload);
+
+    // Set HTTP-only cookie
+    response.cookie('auth_token', jwtToken, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      maxAge: 24 * 60 * 60 * 1000
+    });
+
+    // Redirect to application
+    response.redirect(session.returnTo || '/');
+    ```
+  </TabItem>
+</Tabs>
+
+<Aside type="note" title="PKCE Security">
+  The platform uses PKCE (Proof Key for Code Exchange) to protect against authorization code interception attacks. The `code_challenge` is sent during authorization, and the `code_verifier` is sent during token exchange, preventing attackers from using stolen authorization codes.
+</Aside>
+
+---
+
+## API Key Authentication
+
+API keys provide long-lived authentication for programmatic access.
+
+### API Key Structure
+
+```typescript
+interface ApiKey {
+  id: string;
+  name: string;                // Human-readable name
+  key: string;                 // The actual key (hashed in DB)
+  userId: string;              // Associated user
+  tenantId: string;            // Tenant scope
+  permissions: string[];       // Allowed operations
+  expiresAt?: Date;            // Optional expiration
+  lastUsedAt?: Date;           // Track usage
+  createdAt: Date;
+  createdBy: string;
+}
+```
+
+### API Key Generation
+
+```typescript
+@Post('api-keys')
+async createApiKey(
+  @Body() dto: CreateApiKeyDto,
+  @User() user: AuthUserWithApplications
+) {
+  // Generate secure random key
+  const apiKey = crypto.randomBytes(32).toString('base64url');
+
+  // Hash for storage (using bcrypt)
+  const hashedKey = await bcrypt.hash(apiKey, 10);
+
+  // Store in database
+  await this.apiKeysService.create({
+    name: dto.name,
+    key: hashedKey,
+    userId: user.id,
+    tenantId: user.tenantId,
+    permissions: dto.permissions,
+    expiresAt: dto.expiresAt
+  });
+
+  // Return key ONCE (cannot be retrieved again)
+  return {
+    apiKey,
+    message: 'Save this key securely - it cannot be retrieved again'
+  };
+}
+```
+
+### API Key Usage
+
+```bash
+# Use API key in Authorization header
+curl -H "Authorization: Bearer pae_abc123def456ghi789jkl012mno345pqr678stu901vwx234" \
+  https://platform.com/api/data
+```
+
+**Validation Flow**:
+
+```typescript
+async validateApiKey(apiKey: string): Promise<AuthUserWithApplications | null> {
+  // Find API key in database
+  const storedKey = await this.apiKeysRepository.findByKey(apiKey);
+  if (!storedKey) {
+    return null;
+  }
+
+  // Verify key matches (compare hashes)
+  const isValid = await bcrypt.compare(apiKey, storedKey.key);
+  if (!isValid) {
+    return null;
+  }
+
+  // Check expiration
+  if (storedKey.expiresAt && storedKey.expiresAt < new Date()) {
+    return null;
+  }
+
+  // Update last used
+  await this.apiKeysRepository.updateLastUsed(storedKey.id);
+
+  // Load user
+  const user = await this.usersService.findById(storedKey.userId);
+
+  // Return user context with API key permissions
+  return {
+    id: user.id,
+    username: user.email,
+    displayName: user.displayName,
+    authProviderName: 'api-key',
+    groups: user.groups,
+    applications: storedKey.permissions
+  };
+}
+```
+
+---
+
+## Service-to-Service Authentication
+
+Services authenticate with each other using a shared secret.
+
+### Configuration
+
+```bash
+# Set the same secret on all services
+SERVICE_ACCESS_SECRET=shared-secret-for-internal-services
+```
+
+### Usage
+
+```typescript
+// Service A calling Service B
+const response = await axios.get('http://service-b/api/data', {
+  headers: {
+    'Authorization': `Bearer ${process.env.SERVICE_ACCESS_SECRET}`,
+    'x-forwarded-user': 'service-a' // Optional: identify the calling service
+  }
+});
+```
+
+### Validation
+
+```typescript
+async validateApiKey(apiKey: string, req: FastifyRequest["raw"]): Promise<AuthUserWithApplications | null> {
+  // Check if it's the service access secret
+  if (apiKey === process.env.SERVICE_ACCESS_SECRET) {
+    // Extract calling service name
+    const author = req.headers['x-forwarded-user'] as string | undefined;
+
+    // Return service account
+    return {
+      id: 'service',
+      username: author ?? 'service',
+      displayName: 'Service Account',
+      authProviderName: 'service-access',
+      groups: [],
+      applications: [] // Services typically have full access
+    };
+  }
+
+  // Otherwise, check if it's a regular API key
+  return this.apiKeysService.getUserForApiKey(apiKey);
+}
+```
+
+<Aside type="caution" title="Security Warning">
+  The `SERVICE_ACCESS_SECRET` grants full platform access. Rotate it regularly and never expose it in logs or client-side code. Use it only for internal service-to-service communication.
+</Aside>
+
+---
+
+## User Impersonation
+
+Admins can impersonate users for support and debugging purposes.
+
+### Impersonation Configuration
+
+```typescript
+// Database: impersonation_configs table
+interface ImpersonationConfig {
+  id: string;
+  username: string;              // Admin who can impersonate
+  restrictedTo: string[];        // Optional: limit to specific users
+  createdAt: Date;
+  createdBy: string;
+}
+```
+
+### Impersonation Flow
+
+```
+1. Admin requests to impersonate user
+   ↓
+2. Check if admin has impersonation permission
+   ↓
+3. Check if target user is in restricted list (if applicable)
+   ↓
+4. Create new JWT with impersonation data
+   ↓
+5. Set impersonation mode cookie
+   ↓
+6. All requests now use impersonated user's context
+   ↓
+7. Admin can stop impersonation to return to their account
+```
+
+**Implementation**:
+
+```typescript
+@Post('impersonate')
+async startImpersonation(
+  @Body() dto: { targetUsername: string },
+  @User() admin: AuthUserWithApplications
+) {
+  // Check if admin can impersonate
+  const config = await this.impersonationService.getConfig(admin.username);
+  if (!config) {
+    throw new ForbiddenException('You do not have impersonation permission');
+  }
+
+  // Check if target user is allowed
+  if (config.restrictedTo.length > 0 && !config.restrictedTo.includes(dto.targetUsername)) {
+    throw new ForbiddenException('You cannot impersonate this user');
+  }
+
+  // Load target user
+  const targetUser = await this.usersService.findByUsername(dto.targetUsername);
+  if (!targetUser) {
+    throw new NotFoundException('User not found');
+  }
+
+  // Create JWT with impersonation
+  const jwtPayload = {
+    ...targetUser,
+    impersonatedBy: {
+      username: admin.username,
+      displayName: admin.displayName,
+      orig: admin.orig
+    }
+  };
+
+  const jwtToken = this.jwtService.sign(jwtPayload);
+
+  // Set cookies
+  response.cookie('auth_token', jwtToken, { httpOnly: true, secure: true });
+  response.cookie('impersonation_mode', 'true', { httpOnly: false }); // Client needs to read this
+
+  return {
+    message: 'Impersonation started',
+    targetUser: dto.targetUsername
+  };
+}
+```
+
+<Aside type="tip" title="Audit Trail">
+  All actions performed during impersonation are logged with both the impersonated user and the admin who initiated impersonation. This ensures accountability and compliance.
+</Aside>
+
+---
+
+## Session Management
+
+### Session States
+
+The platform tracks three session states:
+
+```typescript
+type SessionStatus = 'valid' | 'expired' | 'invalid';
+
+async getSessionStatus(token: string): Promise<SessionStatus> {
+  if (!token) return 'invalid';
+
+  try {
+    await this.validateToken(token);
+    return 'valid';
+  } catch (error) {
+    if (error?.name === 'TokenExpiredError') {
+      return 'expired';
+    }
+    return 'invalid';
+  }
+}
+```
+
+### Handling Invalid Sessions
+
+```typescript
+handleInvalidSession(context: ExecutionContext, session: Session) {
+  const request = context.switchToHttp().getRequest<FastifyRequest>();
+  const response = context.switchToHttp().getResponse<FastifyReply>();
+
+  // Check if this is a browser request
+  if (this.isNoRedirectRequest(request)) {
+    // API/non-browser request: return 401
+    response.status(401).send({
+      message: session.status === 'expired' ? 'Session expired' : 'Unauthorized',
+      authRedirectURL: '/'
+    });
+  } else {
+    // Browser request: redirect to login
+    const returnTo = request.url;
+    response.redirect(`/auth/login?returnTo=${encodeURIComponent(returnTo)}`);
+  }
+}
+```
+
+---
+
+## Security Considerations
+
+<Aside type="caution" title="Authentication Security Best Practices">
+
+**JWT Security**:
+- Use strong secrets (minimum 256 bits)
+- Rotate secrets regularly
+- Keep tokens short-lived (< 24 hours)
+- Never store JWTs in localStorage (XSS risk)
+
+**Cookie Security**:
+- Always use `httpOnly` flag
+- Always use `secure` flag in production
+- Use `sameSite: 'lax'` or `strict` for CSRF protection
+- Set appropriate `domain` for subdomain sharing
+
+**API Key Security**:
+- Hash API keys before storage (never store plaintext)
+- Use cryptographically secure random generation
+- Implement rate limiting
+- Support key rotation
+- Monitor and alert on unusual usage
+
+**IDP Integration**:
+- Validate redirect URIs strictly
+- Implement PKCE for OAuth flows
+- Verify state parameter for CSRF protection
+- Use short-lived authorization codes
+- Store IDP tokens securely (encrypted)
+
+**General**:
+- Log all authentication events (success and failure)
+- Implement account lockout after failed attempts
+- Use HTTPS everywhere
+- Implement session timeout
+- Support MFA where possible
+
+</Aside>
+
+---
+
+## Next Steps
+
+- **[Authorization System](/_/docs/architecture/authorization-system/)** - Understanding RBAC and permissions
+- **[Gateway Architecture](/_/docs/architecture/gateway-architecture/)** - How gateway processes authentication
+- **[Multi-Tenancy](/_/docs/architecture/multi-tenancy/)** - Tenant isolation and user management