@lenne.tech/nest-server 11.10.2 → 11.10.4

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -101,6 +101,7 @@ The `CoreBetterAuthUserMapper` enables bidirectional password synchronization:
     BetterAuthModule.forRoot({
       config: envConfig.betterAuth,
       fallbackSecrets: [envConfig.jwt?.secret],
+      // registerRolesGuardGlobally defaults to true - @Roles() decorators work automatically!
     }),
     // ... other modules
   ],
@@ -108,6 +109,8 @@ The `CoreBetterAuthUserMapper` enables bidirectional password synchronization:
 export class ServerModule {}
 ```
 
+**Note:** Since 11.10.3, `registerRolesGuardGlobally` defaults to `true`. You don't need to set it explicitly.
+
 #### For Existing Projects (Migration):
 ```typescript
 @Module({
@@ -129,38 +132,47 @@ export class ServerModule {}
 **Modify:** `src/config.env.ts`
 **Reference:** `node_modules/@lenne.tech/nest-server/src/config.env.ts`
 
-#### For New Projects (IAM-Only):
+#### Zero-Config (Default):
+BetterAuth is **enabled by default** with JWT + 2FA. No configuration required!
+
 ```typescript
 const config = {
-  // Disable Legacy Auth endpoints
+  // BetterAuth is automatically enabled with:
+  // - JWT tokens (for API clients)
+  // - 2FA/TOTP (users can enable it in settings)
+  // No betterAuth config needed!
+
+  // For new projects, disable Legacy Auth:
   auth: {
     legacyEndpoints: {
       enabled: false,
     },
   },
-  // BetterAuth configuration (minimal - JWT enabled by default)
-  betterAuth: true,  // or betterAuth: {} for same effect
+};
+```
 
-  // OR with optional features:
-  betterAuth: {
-    twoFactor: {}, // Enable 2FA (opt-in)
-    passkey: {},   // Enable Passkeys (opt-in)
-    // JWT is already enabled by default
-  },
+#### With Passkey (auto-detected from baseUrl):
+```typescript
+const config = {
+  // Passkey is auto-activated when URLs can be resolved
+  // Option 1: Set root-level baseUrl (production)
+  baseUrl: 'https://api.example.com',  // rpId, origin, trustedOrigins auto-detected
+  env: 'production',
+
+  // Option 2: Use env: 'local'/'ci'/'e2e' (development)
+  // env: 'local',  // Uses localhost defaults: API=:3000, App=:3001
 };
 ```
 
-#### For Existing Projects (Migration):
+#### Disabling Features:
 ```typescript
 const config = {
-  // Keep Legacy Auth endpoints enabled during migration
-  auth: {
-    legacyEndpoints: {
-      enabled: true, // Default - can disable after migration
-    },
+  betterAuth: {
+    jwt: false,       // Disable JWT (use cookies only)
+    twoFactor: false, // Disable 2FA
   },
-  // BetterAuth configuration (JWT enabled by default)
-  betterAuth: true,  // Minimal config, or use object for more options
+  // OR disable BetterAuth completely:
+  betterAuth: false,
 };
 ```
 
@@ -345,26 +357,31 @@ async function useBackupCode(code: string) {
 
 ### Passkey Login Flow (Client-Side)
 
-Handle passkey authentication with session validation fallback:
+Handle passkey authentication with session validation fallback.
+
+**IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `authenticateWithPasskey()` function from the composable instead of `authClient.signIn.passkey()` directly. This is because JWT mode requires sending a `challengeId` to the server for challenge verification.
 
 ```typescript
-// login.vue - Passkey login
+// login.vue - Passkey login (JWT-compatible)
+// Use authenticateWithPasskey from useBetterAuth composable
+const { authenticateWithPasskey, setUser, validateSession } = useBetterAuth();
+
 async function onPasskeyLogin() {
   try {
-    // Use official Better Auth passkey sign-in
-    const result = await authClient.signIn.passkey();
+    // Use composable method which handles challengeId for JWT mode
+    const result = await authenticateWithPasskey();
 
-    if (result.error) {
-      showError(result.error.message || 'Passkey authentication failed');
+    // Check for error (returns { success, error?, user?, session? })
+    if (!result.success) {
+      showError(result.error || 'Passkey authentication failed');
       return;
     }
 
     // Update auth state with user data if available
-    if (result.data?.user) {
-      setUser(result.data.user);
-    } else if (result.data?.session) {
-      // IMPORTANT: Passkey auth returns session without user
-      // Fetch user data via session validation
+    if (result.user) {
+      setUser(result.user);
+    } else {
+      // Passkey auth may return success without user - fetch via session validation
       await validateSession();
     }
 
@@ -378,33 +395,36 @@ async function onPasskeyLogin() {
     showError(err instanceof Error ? err.message : 'Passkey login failed');
   }
 }
-
-// Helper: Validate session and fetch user data
-async function validateSession() {
-  const sessionResult = await authClient.$fetch('/session');
-  if (sessionResult.user) {
-    setUser(sessionResult.user);
-    return true;
-  }
-  return false;
-}
 ```
 
+**Why not use `authClient.signIn.passkey()` directly?**
+
+In JWT mode (`cookies: false`), the server stores WebAuthn challenges in the database instead of cookies. The server returns a `challengeId` in the generate-options response, which must be sent back in the verify request. The `authenticateWithPasskey()` composable function handles this automatically.
+
+| Mode | Challenge Storage | Client Approach |
+|------|------------------|-----------------|
+| Cookie (`cookies: true` or not set) | Cookie (`better-auth.better-auth-passkey`) | Either approach works |
+| JWT (`cookies: false`) | Database with `challengeId` mapping (auto-enabled) | **Must use composable** |
+
+**Note:** Database challenge storage is automatically enabled when `options.cookies: false` is set. No additional configuration is required.
+
 ### Passkey Registration (Client-Side)
 
-Register a new passkey for an authenticated user:
+Register a new passkey for an authenticated user.
+
+**IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `registerPasskey()` function from the composable. This ensures the `challengeId` is correctly sent to the server.
 
 ```typescript
-// settings.vue - Register new passkey
-async function registerPasskey() {
+// settings.vue - Register new passkey (JWT-compatible)
+const { registerPasskey, listPasskeys, deletePasskey } = useBetterAuth();
+
+async function onRegisterPasskey() {
   try {
-    // This calls generate-register-options → verify-registration
-    const result = await authClient.passkey.addPasskey({
-      name: 'My Device',  // Optional: passkey name
-    });
+    // Use composable method which handles challengeId for JWT mode
+    const result = await registerPasskey('My Device'); // Optional name
 
-    if (result.error) {
-      showError(result.error.message);
+    if (!result.success) {
+      showError(result.error || 'Passkey registration failed');
       return;
     }
 
@@ -420,23 +440,32 @@ async function registerPasskey() {
   }
 }
 
-// List user's passkeys
+// List user's passkeys (works in both modes)
 async function loadPasskeys() {
-  const result = await authClient.passkey.listUserPasskeys();
-  if (!result.error) {
-    passkeys.value = result.data || [];
+  const result = await listPasskeys();
+  if (result.success) {
+    passkeys.value = result.passkeys || [];
   }
 }
 
-// Delete a passkey
-async function deletePasskey(passkeyId: string) {
-  const result = await authClient.passkey.deletePasskey({ id: passkeyId });
-  if (!result.error) {
+// Delete a passkey (works in both modes)
+async function onDeletePasskey(passkeyId: string) {
+  const result = await deletePasskey(passkeyId);
+  if (result.success) {
     await loadPasskeys();
   }
 }
 ```
 
+**Alternative for Cookie mode only:**
+
+If you're only using Cookie mode (`cookies: true`), you can use `authClient.passkey` directly:
+
+```typescript
+// Cookie mode ONLY - does NOT work with JWT mode
+const result = await authClient.passkey.addPasskey({ name: 'My Device' });
+```
+
 ---
 
 ## Better-Auth Hooks: Limitations & Warnings

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)