@lenne.tech/nest-server 11.10.2 → 11.10.3

package/src/core/modules/better-auth/core-better-auth.middleware.ts

@@ -1,7 +1,7 @@
 import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { isProduction, maskEmail, maskToken } from '../../common/helpers/logging.helper';
+import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper';
 import { extractSessionToken } from './core-better-auth-web.helper';
 import { CoreBetterAuthService } from './core-better-auth.service';
@@ -33,7 +33,6 @@ export interface CoreBetterAuthRequest extends Request {
 @Injectable()
 export class CoreBetterAuthMiddleware implements NestMiddleware {
   private readonly logger = new Logger(CoreBetterAuthMiddleware.name);
-  private readonly isProd = isProduction();
 
   constructor(
     private readonly betterAuthService: CoreBetterAuthService,
@@ -134,9 +133,7 @@ export class CoreBetterAuthMiddleware implements NestMiddleware {
     } catch (error) {
       // Don't block the request on auth errors
       // The guards will handle unauthorized access
-      if (!this.isProd) {
-        this.logger.debug(`Session validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      }
+      this.logger.debug(`Session validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 
     next();
@@ -176,26 +173,18 @@ export class CoreBetterAuthMiddleware implements NestMiddleware {
       const basePath = this.betterAuthService.getBasePath();
       const sessionToken = extractSessionToken(req, basePath);
 
-      if (!this.isProd) {
-        this.logger.debug(`[MIDDLEWARE] getSession called, token found: ${sessionToken ? 'yes' : 'no'}`);
-      }
+      this.logger.debug(`[MIDDLEWARE] getSession called, token found: ${sessionToken ? 'yes' : 'no'}`);
 
       if (sessionToken) {
-        if (!this.isProd) {
-          this.logger.debug(`[MIDDLEWARE] Found session token in cookies: ${maskToken(sessionToken)}`);
-        }
+        this.logger.debug(`[MIDDLEWARE] Found session token in cookies: ${maskToken(sessionToken)}`);
 
         // Use getSessionByToken to validate session directly from database
         const sessionResult = await this.betterAuthService.getSessionByToken(sessionToken);
 
-        if (!this.isProd) {
-          this.logger.debug(`[MIDDLEWARE] getSessionByToken result: user=${maskEmail(sessionResult?.user?.email)}, session=${!!sessionResult?.session}`);
-        }
+        this.logger.debug(`[MIDDLEWARE] getSessionByToken result: user=${maskEmail(sessionResult?.user?.email)}, session=${!!sessionResult?.session}`);
 
         if (sessionResult?.user && sessionResult?.session) {
-          if (!this.isProd) {
-            this.logger.debug(`[MIDDLEWARE] Session validated for user: ${maskEmail(sessionResult.user.email)}`);
-          }
+          this.logger.debug(`[MIDDLEWARE] Session validated for user: ${maskEmail(sessionResult.user.email)}`);
           return sessionResult as { session: any; user: BetterAuthSessionUser };
         }
       }
@@ -225,9 +214,7 @@ export class CoreBetterAuthMiddleware implements NestMiddleware {
 
       return null;
     } catch (error) {
-      if (!this.isProd) {
-        this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      }
+      this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
       return null;
     }
   }

package/src/core/modules/better-auth/core-better-auth.module.ts

@@ -20,6 +20,7 @@ import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthInstance, createBetterAuthInstance } from './better-auth.config';
 import { DefaultBetterAuthResolver } from './better-auth.resolver';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware';
+import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
 import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit.middleware';
 import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service';
 import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
@@ -38,13 +39,14 @@ export const BETTER_AUTH_INSTANCE = 'BETTER_AUTH_INSTANCE';
  */
 export interface CoreBetterAuthModuleOptions {
   /**
-   * Better-auth configuration.
+   * Better-auth configuration (optional - auto-read from ConfigService).
    * Accepts:
    * - `true`: Enable with all defaults (including JWT)
    * - `false`: Disable BetterAuth
    * - `{ ... }`: Enable with custom configuration
+   * - `undefined`: Auto-read from ConfigService (Zero-Config)
    */
-  config: boolean | IBetterAuth;
+  config?: boolean | IBetterAuth;
 
   /**
    * Custom controller class to use instead of the default CoreBetterAuthController.
@@ -119,19 +121,66 @@ export interface CoreBetterAuthModuleOptions {
    * ```
    */
   resolver?: Type<CoreBetterAuthResolver>;
+
+  /**
+   * Server-level app/frontend URL (from IServerOptions.appUrl).
+   * This is the frontend application URL where the browser runs.
+   *
+   * Used for:
+   * - CORS trustedOrigins
+   * - Passkey/WebAuthn origin
+   *
+   * Auto-Detection:
+   * - If not set, derived from `serverBaseUrl`:
+   *   - 'https://api.example.com' → 'https://example.com'
+   *   - 'https://example.com' → 'https://example.com'
+   * - When `serverEnv: 'local'` and not set: defaults to 'http://localhost:3001'
+   *
+   * @example 'https://example.com'
+   */
+  serverAppUrl?: string;
+
+  /**
+   * Server-level base URL (from IServerOptions.baseUrl).
+   * This is the API server URL.
+   *
+   * Used for:
+   * - Email links (password reset, verification)
+   * - OAuth callback URLs
+   * - As fallback for betterAuth.baseUrl
+   *
+   * Auto-Detection:
+   * - When `serverEnv: 'local'` and not set: defaults to 'http://localhost:3000'
+   *
+   * @example 'https://api.example.com'
+   */
+  serverBaseUrl?: string;
+
+  /**
+   * Server environment (from IServerOptions.env).
+   * Used for local environment defaults:
+   * - When `env: 'local'` and no URLs are set:
+   *   - `serverBaseUrl` defaults to 'http://localhost:3000'
+   *   - `serverAppUrl` defaults to 'http://localhost:3001'
+   */
+  serverEnv?: string;
 }
 
 /**
  * Normalizes betterAuth config from boolean | IBetterAuth to IBetterAuth | null
  * - `true` → `{}` (enabled with defaults)
  * - `false` → `null` (disabled)
- * - `undefined` → `null` (disabled for backward compatibility)
+ * - `undefined` → `{}` (enabled by default - zero-config)
+ * - `{ enabled: false }` → `null` (disabled)
  * - `{ ... }` → `{ ... }` (pass through)
  */
 function normalizeBetterAuthConfig(config: boolean | IBetterAuth | undefined): IBetterAuth | null {
-  if (config === undefined || config === null) return null;
+  // BetterAuth is enabled by default (zero-config)
+  if (config === undefined || config === null) return {};
   if (config === true) return {};
   if (config === false) return null;
+  // Check for explicit { enabled: false }
+  if (typeof config === 'object' && config.enabled === false) return null;
   return config;
 }
 
@@ -268,10 +317,39 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: CoreBetterAuthModuleOptions): DynamicModule {
-    const { config: rawConfig, controller, fallbackSecrets, registerRolesGuardGlobally, resolver } = options;
+    const {
+      config: rawConfig,
+      controller,
+      fallbackSecrets,
+      registerRolesGuardGlobally,
+      resolver,
+      serverAppUrl,
+      serverBaseUrl,
+      serverEnv,
+    } = options;
+
+    // Auto-read from global ConfigService if not explicitly provided
+    // This allows projects to use BetterAuthModule.forRoot({}) for true Zero-Config
+    // as all values are already available from CoreModule.forRoot(envConfig)
+    const globalConfig = ConfigService.configFastButReadOnly;
+
+    // Auto-detect config from ConfigService if not explicitly provided
+    const effectiveRawConfig = rawConfig ?? globalConfig?.betterAuth;
+
+    // Auto-detect fallbackSecrets from ConfigService if not explicitly provided
+    const effectiveFallbackSecrets = fallbackSecrets ?? (
+      globalConfig?.jwt
+        ? [globalConfig.jwt.secret, globalConfig.jwt.refresh?.secret].filter(Boolean)
+        : undefined
+    );
+
+    // Auto-detect server URLs from ConfigService if not explicitly provided
+    const effectiveServerAppUrl = serverAppUrl ?? globalConfig?.appUrl;
+    const effectiveServerBaseUrl = serverBaseUrl ?? globalConfig?.baseUrl;
+    const effectiveServerEnv = serverEnv ?? globalConfig?.env;
 
     // Normalize config: true → {}, false/undefined → null
-    const config = normalizeBetterAuthConfig(rawConfig);
+    const config = normalizeBetterAuthConfig(effectiveRawConfig);
 
     // Store config for middleware configuration
     this.currentConfig = config;
@@ -289,7 +367,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       this.logger.debug('BetterAuth is disabled - skipping initialization');
       this.betterAuthEnabled = false;
       return {
-        exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService],
+        exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
         module: CoreBetterAuthModule,
         providers: [
           {
@@ -302,6 +380,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           CoreBetterAuthUserMapper,
           CoreBetterAuthRateLimiter,
           BetterAuthTokenService,
+          CoreBetterAuthChallengeService,
         ],
       };
     }
@@ -314,7 +393,12 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
 
     // Always use deferred initialization to ensure MongoDB is ready
     // This prevents timing issues during application startup
-    return this.createDeferredModule(config, fallbackSecrets);
+    // Pass server-level URLs for Passkey auto-detection (using effective values from ConfigService fallback)
+    return this.createDeferredModule(config, effectiveFallbackSecrets, {
+      serverAppUrl: effectiveServerAppUrl,
+      serverBaseUrl: effectiveServerBaseUrl,
+      serverEnv: effectiveServerEnv,
+    });
   }
 
   /**
@@ -326,7 +410,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   static forRootAsync(): DynamicModule {
     return {
       controllers: [this.getControllerClass()],
-      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService],
+      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
       imports: [],
       module: CoreBetterAuthModule,
       providers: [
@@ -408,6 +492,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             return new BetterAuthTokenService(betterAuthService, connection);
           },
         },
+        CoreBetterAuthChallengeService,
         this.getResolverClass(),
       ],
     };
@@ -446,11 +531,19 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   /**
    * Creates a deferred initialization module that waits for mongoose connection
    * By injecting the Connection token, NestJS ensures Mongoose is ready first
+   *
+   * @param config - BetterAuth configuration
+   * @param fallbackSecrets - Fallback secrets for backwards compatibility
+   * @param serverUrls - Server-level URLs for Passkey auto-detection
    */
-  private static createDeferredModule(config: IBetterAuth, fallbackSecrets?: (string | undefined)[]): DynamicModule {
+  private static createDeferredModule(
+    config: IBetterAuth,
+    fallbackSecrets?: (string | undefined)[],
+    serverUrls?: { serverAppUrl?: string; serverBaseUrl?: string; serverEnv?: string },
+  ): DynamicModule {
     return {
       controllers: [this.getControllerClass()],
-      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService],
+      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
       module: CoreBetterAuthModule,
       providers: [
         {
@@ -467,9 +560,23 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               if (!globalDb) {
                 throw new Error('MongoDB database not available');
               }
-              this.authInstance = createBetterAuthInstance({ config, db: globalDb, fallbackSecrets });
+              this.authInstance = createBetterAuthInstance({
+                config,
+                db: globalDb,
+                fallbackSecrets,
+                serverAppUrl: serverUrls?.serverAppUrl,
+                serverBaseUrl: serverUrls?.serverBaseUrl,
+                serverEnv: serverUrls?.serverEnv,
+              });
             } else {
-              this.authInstance = createBetterAuthInstance({ config, db, fallbackSecrets });
+              this.authInstance = createBetterAuthInstance({
+                config,
+                db,
+                fallbackSecrets,
+                serverAppUrl: serverUrls?.serverAppUrl,
+                serverBaseUrl: serverUrls?.serverBaseUrl,
+                serverEnv: serverUrls?.serverEnv,
+              });
             }
 
             // IMPORTANT: Store the config AFTER createBetterAuthInstance mutates it
@@ -516,6 +623,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             return new BetterAuthTokenService(betterAuthService, connection);
           },
         },
+        CoreBetterAuthChallengeService,
         this.getResolverClass(),
         // Conditionally register RolesGuard globally for IAM-only setups
         // In Legacy mode, RolesGuard is already registered globally via CoreAuthModule
@@ -539,24 +647,26 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static logEnabledFeatures(config: IBetterAuth): void {
     const features: string[] = [];
 
-    // Helper to check if a plugin is enabled
-    // Supports: true, { enabled: true }, { ... } (enabled by default when config block present)
-    // Disabled only when: false or { enabled: false }
-    const isPluginEnabled = <T extends { enabled?: boolean }>(value: boolean | T | undefined): boolean => {
-      if (value === undefined || value === false) return false;
-      if (value === true) return true;
-      return value.enabled !== false;
+    // Helper to check if a plugin is explicitly disabled
+    const isExplicitlyDisabled = <T extends { enabled?: boolean }>(value: boolean | T | undefined): boolean => {
+      if (value === false) return true;
+      if (typeof value === 'object' && value?.enabled === false) return true;
+      return false;
     };
 
-    // Plugins are enabled by default when config block is present
-    if (isPluginEnabled(config.jwt)) {
+    // JWT and 2FA are enabled by default unless explicitly disabled
+    if (!isExplicitlyDisabled(config.jwt)) {
       features.push('JWT');
     }
-    if (isPluginEnabled(config.twoFactor)) {
+    if (!isExplicitlyDisabled(config.twoFactor)) {
       features.push('2FA/TOTP');
     }
-    if (isPluginEnabled(config.passkey)) {
-      features.push('Passkey/WebAuthn');
+    // Passkey is enabled by default, unless explicitly set to false
+    if (config.passkey !== false && !(typeof config.passkey === 'object' && config.passkey?.enabled === false)) {
+      const passkeyConfig = typeof config.passkey === 'object' ? config.passkey : null;
+      // Challenge storage is 'database' by default, can be overridden via config
+      const challengeStorage = passkeyConfig?.challengeStorage || 'database';
+      features.push(`Passkey/WebAuthn (challenges: ${challengeStorage})`);
     }
 
     // Dynamically collect enabled social providers

package/src/core/modules/better-auth/core-better-auth.resolver.ts

@@ -4,6 +4,7 @@ import { Request, Response } from 'express';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { maskEmail } from '../../common/helpers/logging.helper';
 import {
   BetterAuth2FAResponse,
   BetterAuthSignInResponse,
@@ -228,12 +229,12 @@ export class CoreBetterAuthResolver {
         body: { email, password },
       })) as BetterAuthSignInResponse | null;
 
-      this.logger.debug(`[SignIn] API response for ${email}: ${JSON.stringify(response)?.substring(0, 200)}`);
+      this.logger.debug(`[SignIn] API response for ${maskEmail(email)}: ${JSON.stringify(response)?.substring(0, 200)}`);
 
       // Check if response indicates an error (Better-Auth returns error objects, not throws)
       const responseAny = response as any;
       if (responseAny?.error || responseAny?.code === 'CREDENTIAL_ACCOUNT_NOT_FOUND') {
-        this.logger.debug(`[SignIn] API returned error for ${email}: ${responseAny?.error || responseAny?.code}`);
+        this.logger.debug(`[SignIn] API returned error for ${maskEmail(email)}: ${responseAny?.error || responseAny?.code}`);
         throw new Error(responseAny?.error || responseAny?.code || 'Credential account not found');
       }
 
@@ -273,17 +274,17 @@ export class CoreBetterAuthResolver {
       throw new UnauthorizedException('Invalid credentials');
     } catch (error) {
       this.logger.debug(
-        `[SignIn] Sign-in failed for ${email}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        `[SignIn] Sign-in failed for ${maskEmail(email)}: ${error instanceof Error ? error.message : 'Unknown error'}`,
       );
 
       // If migration is allowed, try to migrate legacy user and retry
       if (allowMigration) {
-        this.logger.debug(`[SignIn] Attempting migration for ${email}...`);
+        this.logger.debug(`[SignIn] Attempting migration for ${maskEmail(email)}...`);
         // Pass the original password for legacy verification
         const migrated = await this.userMapper.migrateAccountToIam(email, password);
-        this.logger.debug(`[SignIn] Migration result for ${email}: ${migrated}`);
+        this.logger.debug(`[SignIn] Migration result for ${maskEmail(email)}: ${migrated}`);
         if (migrated) {
-          this.logger.debug(`[SignIn] Migrated legacy user ${email} to IAM, retrying sign-in`);
+          this.logger.debug(`[SignIn] Migrated legacy user ${maskEmail(email)} to IAM, retrying sign-in`);
           // Retry sign-in after migration with normalized password (as migrateAccountToIam stores it)
           const normalizedPassword = this.userMapper.normalizePasswordForIam(password);
           return this.attemptSignInDirect(email, normalizedPassword, api);

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

@@ -4,7 +4,7 @@ import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
 import { Connection } from 'mongoose';
 
-import { isProduction, maskCookieHeader, maskEmail, maskToken } from '../../common/helpers/logging.helper';
+import { maskCookieHeader, maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
 import { BetterAuthInstance } from './better-auth.config';
@@ -55,7 +55,6 @@ export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
 @Injectable()
 export class CoreBetterAuthService {
   private readonly logger = new Logger(CoreBetterAuthService.name);
-  private readonly isProd = isProduction();
   private readonly config: IBetterAuth;
 
   constructor(
@@ -129,32 +128,30 @@ export class CoreBetterAuthService {
 
   /**
    * Checks if 2FA is enabled.
-   * Supports both boolean and object configuration:
-   * - `true` or `{}` → enabled
-   * - `false` or `{ enabled: false }` → disabled
+   * 2FA is enabled by default when BetterAuth is enabled.
+   * Only disabled when explicitly set to:
+   * - `false`
+   * - `{ enabled: false }`
    */
   isTwoFactorEnabled(): boolean {
-    return this.isEnabled() && this.isPluginEnabled(this.config.twoFactor);
+    if (!this.isEnabled()) return false;
+    if (this.config.twoFactor === false) return false;
+    if (typeof this.config.twoFactor === 'object' && this.config.twoFactor?.enabled === false) return false;
+    return true;
   }
 
   /**
    * Checks if Passkey/WebAuthn is enabled.
-   * Supports both boolean and object configuration:
-   * - `true` or `{}` → enabled
-   * - `false` or `{ enabled: false }` → disabled
+   * Passkey is enabled by default when BetterAuth is enabled.
+   * Only disabled when explicitly set to:
+   * - `false`
+   * - `{ enabled: false }`
    */
   isPasskeyEnabled(): boolean {
-    return this.isEnabled() && this.isPluginEnabled(this.config.passkey);
-  }
-
-  /**
-   * Helper to check if a plugin configuration is enabled.
-   * Supports both boolean and object configuration.
-   */
-  private isPluginEnabled<T extends { enabled?: boolean }>(config: boolean | T | undefined): boolean {
-    if (config === undefined) return false;
-    if (typeof config === 'boolean') return config;
-    return config.enabled !== false;
+    if (!this.isEnabled()) return false;
+    if (this.config.passkey === false) return false;
+    if (typeof this.config.passkey === 'object' && this.config.passkey?.enabled === false) return false;
+    return true;
   }
 
   /**
@@ -320,17 +317,13 @@ export class CoreBetterAuthService {
       }
 
       // Debug: Log the cookie header being sent to api.getSession (masked for security)
-      if (!this.isProd) {
-        const cookieHeader = headers.get('cookie');
-        this.logger.debug(`getSession called with cookies: ${maskCookieHeader(cookieHeader)}`);
-      }
+      const cookieHeader = headers.get('cookie');
+      this.logger.debug(`getSession called with cookies: ${maskCookieHeader(cookieHeader)}`);
 
       const response = await api.getSession({ headers });
 
       // Debug: Log the response from api.getSession
-      if (!this.isProd) {
-        this.logger.debug(`getSession response: ${JSON.stringify(response)?.substring(0, 200)}`);
-      }
+      this.logger.debug(`getSession response: ${JSON.stringify(response)?.substring(0, 200)}`);
 
       if (response && typeof response === 'object' && 'user' in response) {
         return response as SessionResult;
@@ -338,9 +331,7 @@ export class CoreBetterAuthService {
 
       return { session: null, user: null };
     } catch (error) {
-      if (!this.isProd) {
-        this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      }
+      this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
       return { session: null, user: null };
     }
   }
@@ -383,9 +374,7 @@ export class CoreBetterAuthService {
       await api.signOut({ headers });
       return true;
     } catch (error) {
-      if (!this.isProd) {
-        this.logger.debug(`revokeSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      }
+      this.logger.debug(`revokeSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
       return false;
     }
   }
@@ -494,31 +483,23 @@ export class CoreBetterAuthService {
       const result = results[0];
 
       if (!result) {
-        if (!this.isProd) {
-          this.logger.debug(`getSessionByToken: session not found for token ${maskToken(token)}`);
-        }
+        this.logger.debug(`getSessionByToken: session not found for token ${maskToken(token)}`);
         return { session: null, user: null };
       }
 
       // Check if session is expired
       if (result.expiresAt && new Date(result.expiresAt) < new Date()) {
-        if (!this.isProd) {
-          this.logger.debug(`getSessionByToken: session expired`);
-        }
+        this.logger.debug(`getSessionByToken: session expired`);
         return { session: null, user: null };
       }
 
       const user = result.userDoc;
       if (!user) {
-        if (!this.isProd) {
-          this.logger.debug(`getSessionByToken: user not found for session`);
-        }
+        this.logger.debug(`getSessionByToken: user not found for session`);
         return { session: null, user: null };
       }
 
-      if (!this.isProd) {
-        this.logger.debug(`getSessionByToken: found session for user ${maskEmail(user.email)}`);
-      }
+      this.logger.debug(`getSessionByToken: found session for user ${maskEmail(user.email)}`);
 
       return {
         session: {
@@ -535,9 +516,7 @@ export class CoreBetterAuthService {
         },
       };
     } catch (error) {
-      if (!this.isProd) {
-        this.logger.debug(`getSessionByToken error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      }
+      this.logger.debug(`getSessionByToken error: ${error instanceof Error ? error.message : 'Unknown error'}`);
       return { session: null, user: null };
     }
   }

package/src/core.module.ts

@@ -265,6 +265,11 @@ export class CoreModule implements NestModule {
             // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
             // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
             registerRolesGuardGlobally: isIamOnlyMode,
+            // Pass server-level URLs for Passkey auto-detection
+            // When env: 'local', defaults are: baseUrl=localhost:3000, appUrl=localhost:3001
+            serverAppUrl: config.appUrl,
+            serverBaseUrl: config.baseUrl,
+            serverEnv: config.env,
           }),
         );
       }

package/src/server/modules/better-auth/better-auth.module.ts

@@ -7,6 +7,19 @@ import { BetterAuthResolver } from './better-auth.resolver';
 
 /**
  * Options for BetterAuthModule.forRoot()
+ *
+ * All options are optional when using Zero-Config:
+ * All values are auto-read from ConfigService (set by CoreModule.forRoot)
+ *
+ * @example
+ * // Zero-Config - all values auto-detected from ConfigService
+ * BetterAuthModule.forRoot({})
+ *
+ * // Or with explicit overrides
+ * BetterAuthModule.forRoot({
+ *   config: { secret: 'custom-secret' },
+ *   serverAppUrl: 'https://custom-app.com',
+ * })
  */
 export interface ServerBetterAuthModuleOptions {
   /**
@@ -15,14 +28,33 @@ export interface ServerBetterAuthModuleOptions {
    * - `true`: Enable with all defaults (including JWT)
    * - `false`: Disable BetterAuth
    * - `{ ... }`: Enable with custom configuration
+   * - `undefined`: Auto-read from ConfigService (Zero-Config)
    */
-  config: boolean | IBetterAuth;
+  config?: boolean | IBetterAuth;
 
   /**
    * Fallback secrets for backwards compatibility with JWT config.
    * If no betterAuth.secret is configured, these secrets are tried in order.
    */
   fallbackSecrets?: (string | undefined)[];
+
+  /**
+   * Server-level app URL for Passkey auto-detection.
+   * @see IServerOptions.appUrl
+   */
+  serverAppUrl?: string;
+
+  /**
+   * Server-level base URL for Passkey auto-detection.
+   * @see IServerOptions.baseUrl
+   */
+  serverBaseUrl?: string;
+
+  /**
+   * Server environment for localhost defaults (local, ci, e2e).
+   * @see IServerOptions.env
+   */
+  serverEnv?: string;
 }
 
 /**
@@ -42,14 +74,9 @@ export interface ServerBetterAuthModuleOptions {
  *
  * @Module({
  *   imports: [
- *     CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), {
- *       ...envConfig,
- *       betterAuth: { ...envConfig.betterAuth, autoRegister: false },
- *     }),
- *     BetterAuthModule.forRoot({
- *       config: envConfig.betterAuth,
- *       fallbackSecrets: [envConfig.jwt?.secret, envConfig.jwt?.refresh?.secret],
- *     }),
+ *     CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig),
+ *     // Zero-Config: All values auto-read from ConfigService
+ *     BetterAuthModule.forRoot({}),
  *   ],
  * })
  * export class ServerModule {}
@@ -64,7 +91,7 @@ export class BetterAuthModule {
    * @returns Dynamic module configuration
    */
   static forRoot(options: ServerBetterAuthModuleOptions): DynamicModule {
-    const { config, fallbackSecrets } = options;
+    const { config, fallbackSecrets, serverAppUrl, serverBaseUrl, serverEnv } = options;
 
     // If better-auth is explicitly disabled, return minimal module
     // Supports: false, { enabled: false }, or undefined/null
@@ -85,6 +112,9 @@ export class BetterAuthModule {
           controller: BetterAuthController,
           fallbackSecrets,
           resolver: BetterAuthResolver,
+          serverAppUrl,
+          serverBaseUrl,
+          serverEnv,
         }),
       ],
       module: BetterAuthModule,

package/src/server/server.module.ts

@@ -45,11 +45,9 @@ import { ServerController } from './server.controller';
     AuthModule.forRoot(envConfig.jwt),
 
     // Include BetterAuthModule for better-auth integration
+    // Zero-Config: All values are auto-read from ConfigService (set by CoreModule.forRoot)
     // This allows project-specific customization via BetterAuthResolver
-    BetterAuthModule.forRoot({
-      config: envConfig.betterAuth,
-      fallbackSecrets: [envConfig.jwt?.secret, envConfig.jwt?.refresh?.secret],
-    }),
+    BetterAuthModule.forRoot({}),
 
     // Include ErrorCodeModule with project-specific error codes
     // Uses Core ErrorCodeModule.forRoot() with custom service and controller