@lenne.tech/nest-server 11.10.1 → 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

@@ -9,14 +9,18 @@ import {
   Optional,
   Type,
 } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
 import { getConnectionToken } from '@nestjs/mongoose';
 import mongoose, { Connection } from 'mongoose';
 
 import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
+import { RolesGuard } from '../auth/guards/roles.guard';
+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';
@@ -35,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.
@@ -79,6 +84,19 @@ export interface CoreBetterAuthModuleOptions {
    */
   fallbackSecrets?: (string | undefined)[];
 
+  /**
+   * Register RolesGuard as a global guard.
+   *
+   * This should be set to `true` for IAM-only setups (CoreModule.forRoot with 1 parameter)
+   * where CoreAuthModule is not imported (which normally registers RolesGuard globally).
+   *
+   * When `true`, all `@Roles()` decorators will be enforced automatically without
+   * needing explicit `@UseGuards(RolesGuard)` on each endpoint.
+   *
+   * @default false
+   */
+  registerRolesGuardGlobally?: boolean;
+
   /**
    * Custom resolver class to use instead of the default DefaultBetterAuthResolver.
    * The class must extend CoreBetterAuthResolver.
@@ -103,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;
 }
 
@@ -152,6 +217,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static currentConfig: IBetterAuth | null = null;
   private static customController: null | Type<CoreBetterAuthController> = null;
   private static customResolver: null | Type<CoreBetterAuthResolver> = null;
+  private static shouldRegisterRolesGuardGlobally = false;
 
   /**
    * Gets the controller class to use (custom or default)
@@ -251,10 +317,39 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: CoreBetterAuthModuleOptions): DynamicModule {
-    const { config: rawConfig, controller, fallbackSecrets, 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;
@@ -262,6 +357,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.customController = controller || null;
     // Store custom resolver if provided
     this.customResolver = resolver || null;
+    // Store whether to register RolesGuard globally (for IAM-only setups)
+    this.shouldRegisterRolesGuardGlobally = registerRolesGuardGlobally ?? false;
 
     // If better-auth is disabled (config is null or enabled: false), return minimal module
     // Note: We don't provide middleware classes when disabled because they depend on CoreBetterAuthService
@@ -270,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],
+        exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
         module: CoreBetterAuthModule,
         providers: [
           {
@@ -282,6 +379,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           CoreBetterAuthService,
           CoreBetterAuthUserMapper,
           CoreBetterAuthRateLimiter,
+          BetterAuthTokenService,
+          CoreBetterAuthChallengeService,
         ],
       };
     }
@@ -294,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,
+    });
   }
 
   /**
@@ -306,7 +410,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   static forRootAsync(): DynamicModule {
     return {
       controllers: [this.getControllerClass()],
-      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter],
+      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
       imports: [],
       module: CoreBetterAuthModule,
       providers: [
@@ -380,6 +484,15 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         CoreBetterAuthApiMiddleware,
         CoreBetterAuthRateLimiter,
         CoreBetterAuthRateLimitMiddleware,
+        // BetterAuthTokenService needs explicit factory to ensure proper dependency injection
+        {
+          inject: [CoreBetterAuthService, getConnectionToken()],
+          provide: BetterAuthTokenService,
+          useFactory: (betterAuthService: CoreBetterAuthService, connection: Connection) => {
+            return new BetterAuthTokenService(betterAuthService, connection);
+          },
+        },
+        CoreBetterAuthChallengeService,
         this.getResolverClass(),
       ],
     };
@@ -412,16 +525,25 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.currentConfig = null;
     this.customController = null;
     this.customResolver = null;
+    this.shouldRegisterRolesGuardGlobally = false;
   }
 
   /**
    * 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],
+      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
       module: CoreBetterAuthModule,
       providers: [
         {
@@ -438,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
@@ -479,7 +615,26 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         CoreBetterAuthApiMiddleware,
         CoreBetterAuthRateLimiter,
         CoreBetterAuthRateLimitMiddleware,
+        // BetterAuthTokenService needs explicit factory to ensure proper dependency injection
+        {
+          inject: [CoreBetterAuthService, getConnectionToken()],
+          provide: BetterAuthTokenService,
+          useFactory: (betterAuthService: CoreBetterAuthService, connection: Connection) => {
+            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
+        ...(this.shouldRegisterRolesGuardGlobally
+          ? [
+              {
+                provide: APP_GUARD,
+                useClass: RolesGuard,
+              },
+            ]
+          : []),
       ],
     };
   }
@@ -492,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,
@@ -195,7 +196,7 @@ export class CoreBetterAuthResolver {
   async betterAuthSignIn(
     @Args('email') email: string,
     @Args('password') password: string,
-    // eslint-disable-next-line unused-imports/no-unused-vars -- Reserved for future cookie/session handling
+     
     @Context() _ctx: { req: Request; res: Response },
   ): Promise<CoreBetterAuthAuthModel> {
     this.ensureEnabled();
@@ -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;
   }
 
   /**
@@ -201,6 +198,19 @@ export class CoreBetterAuthService {
     return this.config.baseUrl || 'http://localhost:3000';
   }
 
+  /**
+   * Gets the session cookie name based on the configured base path.
+   *
+   * The cookie name follows the pattern: `{basePath}.session_token`
+   * For example, with basePath '/iam', the cookie name is 'iam.session_token'
+   *
+   * @returns The session cookie name
+   */
+  getSessionCookieName(): string {
+    const basePath = this.getBasePath()?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
+    return `${basePath}.session_token`;
+  }
+
   // ===================================================================================================================
   // JWT Token Methods
   // ===================================================================================================================
@@ -307,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;
@@ -325,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 };
     }
   }
@@ -370,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;
     }
   }
@@ -481,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: {
@@ -522,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/modules/better-auth/index.ts

@@ -22,6 +22,7 @@
  * - DefaultBetterAuthResolver: Default resolver implementation (use as fallback)
  */
 
+export * from './better-auth-token.service';
 export * from './better-auth.config';
 export * from './better-auth.resolver';
 export * from './better-auth.types';