@lenne.tech/nest-server 11.10.1 → 11.10.3

package/src/core/modules/better-auth/README.md

@@ -10,11 +10,15 @@ Integration of the [better-auth](https://better-auth.com) authentication framewo
 CoreModule.forRoot(envConfig),  // IAM-only (new projects)
 CoreBetterAuthModule.forRoot({ config: envConfig.betterAuth, fallbackSecrets: [envConfig.jwt?.secret] }),
 
-// 3. Configure in config.env.ts (minimal - JWT enabled by default):
-betterAuth: true  // or betterAuth: {} for same effect
-
-// With optional features:
-betterAuth: { twoFactor: {}, passkey: {} }
+// 3. Configure in config.env.ts (zero-config - enabled by default):
+// BetterAuth is enabled automatically with JWT + 2FA
+// Passkey is auto-activated when URLs can be resolved:
+//   - via root-level baseUrl (server-wide)
+//   - or env: 'local'/'ci'/'e2e' (uses localhost defaults)
+const config = {
+  baseUrl: 'https://api.example.com',  // Root-level - Passkey auto-detected from this
+  env: 'production',
+}
 ```
 
 **Quick Links:** [Integration Checklist](./INTEGRATION-CHECKLIST.md) | [REST API](#rest-api-endpoints) | [GraphQL API](#graphql-api) | [Configuration](#configuration)
@@ -42,8 +46,8 @@ betterAuth: { twoFactor: {}, passkey: {} }
 ### Built-in Plugins
 
 - **JWT Tokens** - For API clients and stateless authentication (**enabled by default**)
-- **Two-Factor Authentication (2FA)** - TOTP-based second factor (opt-in)
-- **Passkey/WebAuthn** - Passwordless authentication (opt-in)
+- **Two-Factor Authentication (2FA)** - TOTP-based second factor (**enabled by default**)
+- **Passkey/WebAuthn** - Passwordless authentication (**enabled by default**, requires resolvable URLs)
 
 ### Core Features
 
@@ -166,10 +170,11 @@ betterAuth: { enabled: false } // Disable (allows pre-configuration)
 **Default values (used when not configured):**
 
 - **JWT**: Enabled by default
+- **2FA/TOTP**: Enabled by default (users can optionally set up 2FA)
+- **Passkey**: Enabled by default (requires resolvable URLs via `baseUrl`, `appUrl`, or `env: 'local'`)
 - **Secret**: Falls back to `jwt.secret` → `jwt.refresh.secret` → auto-generated
 - **Base URL**: `http://localhost:3000`
 - **Base Path**: `/iam`
-- **2FA/Passkey**: Disabled (opt-in)
 
 To **explicitly disable** Better-Auth:
 
@@ -242,18 +247,55 @@ Read the security section below for production deployments.
 
 **For Development:** The defaults (`http://localhost:3000`, `/iam`) are correct.
 
-**For Production:** You must set `baseUrl` and `passkey.origin` to your actual domain:
+### Passkey Auto-Detection (Recommended)
+
+**New in v11.x:** Passkey configuration can be auto-detected from URLs:
 
 ```typescript
+// RECOMMENDED: Set root-level baseUrl - Passkey values are auto-detected
 const config = {
+  baseUrl: process.env.BASE_URL, // e.g., 'https://api.example.com'
+  env: 'production',
+  // Passkey is AUTO-ACTIVATED with:
+  // - rpId: 'example.com' (derived from appUrl)
+  // - origin: 'https://example.com' (= appUrl, derived from baseUrl)
+  // - trustedOrigins: ['https://example.com'] (= appUrl)
+};
+
+// OR for local development - env: 'local' uses localhost defaults:
+const localConfig = {
+  env: 'local',  // Uses API=localhost:3000, App=localhost:3001
+};
+```
+
+**Benefits:**
+- **One config per stage**: Only set `BASE_URL` in your environment
+- **No duplication**: Passkey values derived automatically
+- **Graceful Degradation**: If auto-detection fails (no baseUrl), Passkey is disabled with a warning - other auth methods (Email/Password, 2FA) continue to work
+
+**Auto-Detection Resolution:**
+| Value | Priority | Source |
+|-------|----------|--------|
+| `baseUrl` | 1. Explicit `betterAuth.baseUrl` → 2. Root-level `baseUrl` → 3. Localhost default (env: 'local') |
+| `appUrl` | 1. Root-level `appUrl` → 2. Derived from `baseUrl` (removes `api.` prefix) → 3. Localhost default |
+| `rpId` | 1. Explicit `passkey.rpId` → 2. Auto-detect from appUrl hostname |
+| `origin` | 1. Explicit `passkey.origin` → 2. Auto-detect from appUrl |
+| `trustedOrigins` | 1. Explicit `trustedOrigins` → 2. Auto-detect from appUrl |
+
+### Explicit Passkey Configuration (Advanced)
+
+For production scenarios where you need full control:
+
+```typescript
+const config = {
+  baseUrl: 'https://api.your-domain.com',  // Root-level
   betterAuth: {
-    baseUrl: 'https://api.your-domain.com',
     passkey: {
-      // enabled by default when config block is present
-      origin: 'https://your-domain.com', // Frontend domain
+      origin: 'https://your-domain.com', // Frontend domain (if different from API)
       rpId: 'your-domain.com', // Domain without protocol
       rpName: 'Your Application',
     },
+    trustedOrigins: ['https://your-domain.com', 'https://admin.your-domain.com'],
   },
 };
 ```
@@ -334,7 +376,53 @@ const config = {
 
 ## Configuration
 
-**Optional** - Better-Auth works without any configuration (true zero-config). Only add this block if you need to customize behavior:
+**Optional** - Better-Auth works without any configuration (true zero-config). Only add this block if you need to customize behavior.
+
+### Default Behavior Overview
+
+The following table shows which features are active based on your configuration:
+
+| Configuration | BetterAuth | JWT | 2FA | Passkey |
+|---------------|:----------:|:---:|:---:|:-------:|
+| *not set* (no URLs) | ✅ | ✅ | ✅ | ⚠️ disabled |
+| `env: 'local'/'ci'/'e2e'` (auto URLs) | ✅ | ✅ | ✅ | ✅ auto |
+| `baseUrl` set | ✅ | ✅ | ✅ | ✅ auto |
+| `betterAuth: false` | ❌ | ❌ | ❌ | ❌ |
+| `{ passkey: false }` | ✅ | ✅ | ✅ | ❌ |
+| `{ twoFactor: false }` | ✅ | ✅ | ❌ | ✅ auto |
+
+**Key points:**
+- **BetterAuth** is enabled by default (zero-config)
+- **JWT** is enabled by default (stateless authentication)
+- **2FA/TOTP** is enabled by default (users can optionally set up 2FA)
+- **Passkey/WebAuthn** is enabled by default, but requires resolvable URLs:
+  - Explicitly: `passkey.rpId`, `passkey.origin`, `trustedOrigins`
+  - Or via `baseUrl` → auto-detects `appUrl`, `rpId`, `origin`, `trustedOrigins`
+  - Or via `env: 'local'/'ci'/'e2e'` → uses localhost defaults
+
+### URL Configuration (Important for Passkey!)
+
+**Typical Architecture:**
+- **API**: `https://api.example.com` (NestJS server)
+- **App**: `https://example.com` (Frontend where browser runs)
+
+**URL Resolution:**
+
+| Config | `baseUrl` (API) | `appUrl` (Frontend) | Passkey |
+|--------|-----------------|---------------------|---------|
+| `env: 'local'/'ci'/'e2e'` | `http://localhost:3000` | `http://localhost:3001` | ✅ auto |
+| `baseUrl: 'https://api.example.com'` | as set | `https://example.com` (auto-derived) | ✅ auto |
+| `baseUrl: 'https://example.com'` | as set | `https://example.com` (same) | ✅ auto |
+| `appUrl: 'https://app.example.com'` | - | as set | ✅ auto |
+| Neither set | - | - | ⚠️ disabled |
+
+**Auto-Detection Logic:**
+1. `appUrl` is derived from `baseUrl` by removing `api.` prefix
+2. `rpId` is extracted from `appUrl` (e.g., `example.com`)
+3. `origin` = `appUrl` (e.g., `https://example.com`)
+4. `trustedOrigins` = `[appUrl]` (e.g., `['https://example.com']`)
+
+### Configuration Examples
 
 ```typescript
 // In config.env.ts
@@ -358,17 +446,23 @@ export default {
       // enabled: false,  // Uncomment to disable JWT
     },
 
-    // Two-Factor Authentication (opt-in - requires config block)
+    // Two-Factor Authentication - ENABLED BY DEFAULT
+    // Only add this block to customize or explicitly disable
     twoFactor: {
-      appName: 'My Application',
+      appName: 'My Application',  // Default: 'Nest Server'
+      // enabled: false,  // Uncomment to disable 2FA
     },
 
-    // Passkey/WebAuthn (opt-in - requires config block)
-    passkey: {
-      rpId: 'localhost',
-      rpName: 'My Application',
-      origin: 'http://localhost:3000',
-    },
+    // Passkey/WebAuthn - Auto-detection from baseUrl!
+    // If baseUrl is set, rpId/origin/trustedOrigins are auto-detected
+    passkey: true, // Just enable - values derived from baseUrl
+
+    // OR with explicit configuration (overrides auto-detection):
+    // passkey: {
+    //   rpId: 'localhost',       // Auto-detected from baseUrl hostname
+    //   rpName: 'My Application',
+    //   origin: 'http://localhost:3000', // Auto-detected from baseUrl
+    // },
 
     // Social Providers (enabled by default when credentials are configured)
     // Set enabled: false to explicitly disable a provider
@@ -384,6 +478,8 @@ export default {
     },
 
     // Trusted Origins for CORS
+    // Auto-detected from baseUrl when Passkey is enabled!
+    // Only set explicitly if you need additional origins
     trustedOrigins: ['http://localhost:3000', 'https://your-app.com'],
 
     // Rate Limiting (optional)
@@ -529,26 +625,27 @@ Better-Auth provides a rich plugin ecosystem. This module uses a **hybrid approa
 
 ### Built-in Plugins
 
-| Plugin             | Default State | Minimal Config to Enable | Default Values                                                                    |
+| Plugin             | Default State | Config to Disable        | Default Values                                                                    |
 | ------------------ | ------------- | ------------------------ | --------------------------------------------------------------------------------- |
-| **JWT**            | **ENABLED**   | *(none needed)*          | `expiresIn: '15m'`                                                                |
-| **Two-Factor**     | Disabled      | `twoFactor: {}`          | `appName: 'Nest Server'`                                                          |
-| **Passkey**        | Disabled      | `passkey: {}`            | `origin: 'http://localhost:3000'`, `rpId: 'localhost'`, `rpName: 'Nest Server'`   |
+| **JWT**            | **ENABLED**   | `jwt: false`             | `expiresIn: '15m'`                                                                |
+| **Two-Factor**     | **ENABLED**   | `twoFactor: false`       | `appName: 'Nest Server'`                                                          |
+| **Passkey**        | **ENABLED**   | `passkey: false`         | Auto-detected from `baseUrl`/`appUrl`, `rpName: 'Nest Server'`                    |
 
-**JWT is enabled by default** - no configuration needed. 2FA and Passkey require explicit configuration.
+**All three plugins are enabled by default** - no configuration needed. Passkey requires resolvable URLs to function (via `baseUrl`, `appUrl`, or `env: 'local'/'ci'/'e2e'`). If URLs cannot be resolved, Passkey is disabled with a warning (graceful degradation).
 
 #### Minimal Syntax (Recommended for Development)
 
 ```typescript
 const config = {
-  // JWT is enabled automatically with BetterAuth
+  // JWT and 2FA are enabled automatically with BetterAuth
   betterAuth: true,  // or betterAuth: {}
 
-  // To also enable 2FA and Passkey:
-  betterAuth: {
-    twoFactor: {},
-    passkey: {},
-  },
+  // Passkey is auto-activated when URLs can be resolved:
+  // Option 1: Set root-level baseUrl (production)
+  baseUrl: 'https://api.example.com',  // Passkey values auto-detected from this
+
+  // Option 2: Use env: 'local'/'ci'/'e2e' (development)
+  env: 'local',  // Uses localhost defaults: API=:3000, App=:3001
 };
 ```
 
@@ -574,13 +671,13 @@ const config = {
 const config = {
   betterAuth: {
     jwt: false,               // Disable JWT (or jwt: { enabled: false })
-    twoFactor: {},            // 2FA enabled with defaults
-    passkey: { enabled: false }, // Passkey explicitly disabled
+    twoFactor: false,         // Disable 2FA (or twoFactor: { enabled: false })
+    passkey: false,           // Disable Passkey (or passkey: { enabled: false })
   },
 };
 ```
 
-**Note:** JWT is the only plugin enabled by default. To disable it, use `jwt: false` or `jwt: { enabled: false }`.
+**Note:** All three plugins (JWT, 2FA, Passkey) are enabled by default. Passkey requires resolvable URLs to function. Use `false` or `{ enabled: false }` to disable any plugin.
 
 ### Dynamic Plugins (plugins Array)
 

package/src/core/modules/better-auth/better-auth-token.service.ts

@@ -0,0 +1,241 @@
+import { Injectable, Logger, Optional } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { Connection, Types } from 'mongoose';
+
+import { BetterAuthenticatedUser } from './better-auth.types';
+import { CoreBetterAuthService } from './core-better-auth.service';
+
+/**
+ * Result of token extraction from a request
+ */
+export interface TokenExtractionResult {
+  /** Source of the token (header or cookie) */
+  source: 'cookie' | 'header' | null;
+  /** The extracted token, if found */
+  token: null | string;
+}
+
+/**
+ * BetterAuthTokenService provides centralized token extraction and user loading
+ * for BetterAuth authentication.
+ *
+ * This service consolidates the token verification logic that was previously
+ * duplicated in AuthGuard and RolesGuard, providing:
+ * - Token extraction from Authorization header or cookies
+ * - JWT token verification via BetterAuth
+ * - Session token verification via database lookup
+ * - User loading from MongoDB with hasRole() capability
+ *
+ * @example
+ * ```typescript
+ * const token = this.tokenService.extractTokenFromRequest(request);
+ * if (token) {
+ *   const user = await this.tokenService.verifyAndLoadUser(token);
+ *   if (user) {
+ *     request.user = user;
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class BetterAuthTokenService {
+  private readonly logger = new Logger(BetterAuthTokenService.name);
+
+  constructor(
+    @Optional() private readonly betterAuthService?: CoreBetterAuthService,
+    @Optional() @InjectConnection() private readonly connection?: Connection,
+  ) {}
+
+  /**
+   * Extracts a token from the request's Authorization header or cookies.
+   *
+   * Checks in order:
+   * 1. Authorization header (Bearer token)
+   * 2. Session cookies (iam.session_token, better-auth.session_token, token)
+   *
+   * @param request - HTTP request object with headers and cookies
+   * @returns Token extraction result with token and source
+   */
+  extractTokenFromRequest(request: {
+    cookies?: Record<string, string>;
+    headers?: Record<string, string | string[] | undefined>;
+  }): TokenExtractionResult {
+    // Try Authorization header first
+    const authHeader = request.headers?.authorization || request.headers?.Authorization;
+    const headerValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+
+    if (headerValue) {
+      if (headerValue.startsWith('Bearer ') || headerValue.startsWith('bearer ')) {
+        return { source: 'header', token: headerValue.substring(7) };
+      }
+    }
+
+    // Try cookies
+    if (request.cookies && this.betterAuthService) {
+      const cookieName = this.betterAuthService.getSessionCookieName();
+      const token =
+        request.cookies[cookieName] ||
+        request.cookies['better-auth.session_token'] ||
+        request.cookies['token'] ||
+        undefined;
+
+      if (token) {
+        return { source: 'cookie', token };
+      }
+    }
+
+    return { source: null, token: null };
+  }
+
+  /**
+   * Verifies a token (JWT or session) and loads the corresponding user from MongoDB.
+   *
+   * This method tries multiple verification strategies:
+   * 1. BetterAuth JWT verification (if JWT plugin is enabled)
+   * 2. BetterAuth session token lookup (database lookup)
+   *
+   * @param token - The token to verify
+   * @returns User object with hasRole method, or null if verification fails
+   */
+  async verifyAndLoadUser(token: string): Promise<BetterAuthenticatedUser | null> {
+    if (!this.betterAuthService || !this.connection) {
+      return null;
+    }
+
+    // Strategy 1: Try JWT verification (if JWT plugin is enabled)
+    if (this.betterAuthService.isJwtEnabled()) {
+      try {
+        const payload = await this.betterAuthService.verifyJwtToken(token);
+        if (payload?.sub) {
+          const user = await this.loadUserFromPayload(payload);
+          if (user) {
+            return user;
+          }
+        }
+      } catch (error) {
+        // Check for token expiration
+        if (error instanceof Error && error.message.includes('expired')) {
+          this.logger.debug('JWT token expired');
+          throw error; // Re-throw for proper handling by guards
+        }
+        // Other JWT verification failures - try session token next
+        this.logger.debug(
+          `JWT verification failed, trying session: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
+    }
+
+    // Strategy 2: Try session token lookup (database lookup)
+    try {
+      const sessionResult = await this.betterAuthService.getSessionByToken(token);
+      if (sessionResult?.user) {
+        return this.loadUserFromSessionResult(sessionResult.user);
+      }
+    } catch (error) {
+      this.logger.debug(`Session lookup failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+
+    return null;
+  }
+
+  /**
+   * Creates a user object with hasRole method from a MongoDB document.
+   *
+   * @param user - Raw MongoDB user document
+   * @returns User object with hasRole method
+   */
+  createUserWithHasRole(user: Record<string, unknown>): BetterAuthenticatedUser {
+    return {
+      ...user,
+      _authenticatedViaBetterAuth: true,
+      hasRole: (roles: string[]): boolean => {
+        const userRoles = user.roles;
+        if (!userRoles || !Array.isArray(userRoles)) {
+          return false;
+        }
+        return roles.some((role) => userRoles.includes(role));
+      },
+      id: (user._id as Types.ObjectId)?.toString() || (user.id as string),
+    } as BetterAuthenticatedUser;
+  }
+
+  /**
+   * Loads a user from JWT payload using direct MongoDB query.
+   *
+   * @param payload - JWT payload with sub (user ID or iamId)
+   * @returns User object with hasRole method, or null if not found
+   */
+  private async loadUserFromPayload(payload: { [key: string]: unknown; sub: string }): Promise<BetterAuthenticatedUser | null> {
+    if (!this.connection) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.connection.collection('users');
+      let user: null | Record<string, unknown> = null;
+
+      // Try to find by MongoDB _id first
+      if (Types.ObjectId.isValid(payload.sub)) {
+        user = await usersCollection.findOne({ _id: new Types.ObjectId(payload.sub) });
+      }
+
+      // If not found, try by iamId
+      if (!user) {
+        user = await usersCollection.findOne({ iamId: payload.sub });
+      }
+
+      if (!user) {
+        return null;
+      }
+
+      return this.createUserWithHasRole(user);
+    } catch (error) {
+      this.logger.debug(`Failed to load user from payload: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+
+  /**
+   * Loads a user from session result (from getSessionByToken).
+   *
+   * @param sessionUser - User object from session lookup
+   * @returns User object with hasRole method, or null if not found
+   */
+  private async loadUserFromSessionResult(sessionUser: {
+    email?: string;
+    id?: string;
+  }): Promise<BetterAuthenticatedUser | null> {
+    if (!this.connection || !sessionUser) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.connection.collection('users');
+      let user: null | Record<string, unknown> = null;
+
+      // Try to find by email (most reliable)
+      if (sessionUser.email) {
+        user = await usersCollection.findOne({ email: sessionUser.email });
+      }
+
+      // If not found by email, try by iamId
+      if (!user && sessionUser.id) {
+        user = await usersCollection.findOne({ iamId: sessionUser.id });
+      }
+
+      // If still not found, try by _id (if the ID looks like a MongoDB ObjectId)
+      if (!user && sessionUser.id && Types.ObjectId.isValid(sessionUser.id)) {
+        user = await usersCollection.findOne({ _id: new Types.ObjectId(sessionUser.id) });
+      }
+
+      if (!user) {
+        return null;
+      }
+
+      return this.createUserWithHasRole(user);
+    } catch (error) {
+      this.logger.debug(`Failed to load user from session: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+}