@lenne.tech/nest-server 11.10.3 → 11.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.10.3",
+  "version": "11.10.5",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

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

@@ -6,6 +6,7 @@ import { PubSub } from 'graphql-subscriptions';
 
 import { AuthGuardStrategy } from './auth-guard-strategy.enum';
 import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
+import { RolesGuardRegistry } from './guards/roles-guard-registry';
 import { RolesGuard } from './guards/roles.guard';
 import { CoreAuthUserService } from './services/core-auth-user.service';
 import { CoreAuthService } from './services/core-auth.service';
@@ -44,12 +45,17 @@ export class CoreAuthModule {
     }
 
     // Process providers
+    // Only register RolesGuard if not already registered (prevents duplicate with CoreBetterAuthModule)
+    const rolesGuardProvider = RolesGuardRegistry.isRegistered()
+      ? []
+      : (() => {
+          RolesGuardRegistry.markRegistered('CoreAuthModule');
+          return [{ provide: APP_GUARD, useClass: RolesGuard }];
+        })();
+
     let providers = [
-      // [Global] The GraphQLAuthGard integrates the user into context
-      {
-        provide: APP_GUARD,
-        useClass: RolesGuard,
-      },
+      // [Global] The GraphQLAuthGuard integrates the user into context
+      ...rolesGuardProvider,
       {
         provide: CoreAuthUserService,
         useClass: UserService,

package/src/core/modules/auth/guards/roles-guard-registry.ts

@@ -0,0 +1,57 @@
+import { Logger } from '@nestjs/common';
+
+/**
+ * Global registry to track RolesGuard registration across modules.
+ *
+ * This prevents duplicate registration when both CoreAuthModule (Legacy)
+ * and CoreBetterAuthModule (IAM) are used in the same application.
+ *
+ * Multiple APP_GUARD registrations of the same guard would work but cause
+ * unnecessary double validation on every request.
+ */
+export class RolesGuardRegistry {
+  private static readonly logger = new Logger('RolesGuardRegistry');
+  private static registered = false;
+  private static registeredBy: null | string = null;
+
+  /**
+   * Check if RolesGuard has already been registered as a global guard.
+   */
+  static isRegistered(): boolean {
+    return this.registered;
+  }
+
+  /**
+   * Get which module registered the RolesGuard.
+   */
+  static getRegisteredBy(): null | string {
+    return this.registeredBy;
+  }
+
+  /**
+   * Mark RolesGuard as registered by a specific module.
+   * Call this when adding RolesGuard as APP_GUARD.
+   *
+   * @param moduleName - Name of the module registering RolesGuard (for debugging)
+   */
+  static markRegistered(moduleName: string = 'Unknown'): void {
+    if (this.registered) {
+      this.logger.debug(
+        `RolesGuard already registered by ${this.registeredBy}, skipping registration from ${moduleName}`,
+      );
+      return;
+    }
+    this.registered = true;
+    this.registeredBy = moduleName;
+    this.logger.debug(`RolesGuard registered globally by ${moduleName}`);
+  }
+
+  /**
+   * Reset the registry state.
+   * Used in tests to ensure clean state between test runs.
+   */
+  static reset(): void {
+    this.registered = false;
+    this.registeredBy = null;
+  }
+}

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({

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

@@ -20,6 +20,7 @@ import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
 import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { ConfigService } from '../../common/services/config.service';
+import { ErrorCode } from '../error-code/error-codes';
 import { BetterAuthSignInResponse, hasSession, hasUser, requires2FA } from './better-auth.types';
 import { BetterAuthSessionUser, CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { sendWebResponse, toWebRequest } from './core-better-auth-web.helper';
@@ -227,7 +228,7 @@ export class CoreBetterAuthController {
 
     const api = this.betterAuthService.getApi();
     if (!api) {
-      throw new BadRequestException('Better-Auth API not available');
+      throw new BadRequestException(ErrorCode.BETTERAUTH_API_NOT_AVAILABLE);
     }
 
     // Step 1: Try legacy user migration BEFORE Better Auth handles the request
@@ -255,7 +256,7 @@ export class CoreBetterAuthController {
       })) as BetterAuthSignInResponse | null;
 
       if (!response) {
-        throw new UnauthorizedException('Invalid credentials');
+        throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
       }
 
       // Check for 2FA requirement
@@ -268,7 +269,7 @@ export class CoreBetterAuthController {
         // We need to modify the request body to use the normalized password
         const authInstance = this.betterAuthService.getInstance();
         if (!authInstance) {
-          throw new InternalServerErrorException('Better-Auth not initialized');
+          throw new InternalServerErrorException(ErrorCode.BETTERAUTH_NOT_INITIALIZED);
         }
 
         // Create a modified request body with normalized password
@@ -311,7 +312,7 @@ export class CoreBetterAuthController {
       // Check if response indicates an error
       const responseAny = response as any;
       if (responseAny?.error || responseAny?.code === 'CREDENTIAL_ACCOUNT_NOT_FOUND') {
-        throw new UnauthorizedException('Invalid credentials');
+        throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
       }
 
       if (hasUser(response)) {
@@ -334,7 +335,7 @@ export class CoreBetterAuthController {
         return this.processCookies(res, result);
       }
 
-      throw new UnauthorizedException('Invalid credentials');
+      throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
       this.logger.debug(`Sign-in error: ${errorMessage}`);
@@ -343,7 +344,7 @@ export class CoreBetterAuthController {
         throw error;
       }
 
-      throw new UnauthorizedException('Invalid credentials');
+      throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
     }
   }
 
@@ -380,7 +381,7 @@ export class CoreBetterAuthController {
 
     const api = this.betterAuthService.getApi();
     if (!api) {
-      throw new BadRequestException('Better-Auth API not available');
+      throw new BadRequestException(ErrorCode.BETTERAUTH_API_NOT_AVAILABLE);
     }
 
     // Normalize password to SHA256 format for consistency with Legacy Auth
@@ -396,7 +397,7 @@ export class CoreBetterAuthController {
       });
 
       if (!response) {
-        throw new BadRequestException('Sign-up failed');
+        throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
       }
 
       if (hasUser(response)) {
@@ -419,14 +420,14 @@ export class CoreBetterAuthController {
         return this.processCookies(res, result);
       }
 
-      throw new BadRequestException('Sign-up failed');
+      throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
       this.logger.debug(`Sign-up error: ${errorMessage}`);
       if (errorMessage.includes('already exists')) {
-        throw new BadRequestException('User with this email already exists');
+        throw new BadRequestException(ErrorCode.EMAIL_ALREADY_EXISTS);
       }
-      throw new BadRequestException('Sign-up failed');
+      throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
     }
   }
 
@@ -557,7 +558,7 @@ export class CoreBetterAuthController {
    */
   protected ensureEnabled(): void {
     if (!this.betterAuthService.isEnabled()) {
-      throw new BadRequestException('Better-Auth is not enabled');
+      throw new BadRequestException(ErrorCode.BETTERAUTH_DISABLED);
     }
   }
 
@@ -735,7 +736,7 @@ export class CoreBetterAuthController {
 
     const authInstance = this.betterAuthService.getInstance();
     if (!authInstance) {
-      throw new InternalServerErrorException('Better-Auth not initialized');
+      throw new InternalServerErrorException(ErrorCode.BETTERAUTH_NOT_INITIALIZED);
     }
 
     this.logger.debug(`Forwarding to Better Auth: ${req.method} ${req.path}`);

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

@@ -15,6 +15,7 @@ import mongoose, { Connection } from 'mongoose';
 
 import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
+import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry';
 import { RolesGuard } from '../auth/guards/roles.guard';
 import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthInstance, createBetterAuthInstance } from './better-auth.config';
@@ -87,13 +88,14 @@ export interface CoreBetterAuthModuleOptions {
   /**
    * 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
+   * **Important:** This should be `false` in Legacy mode (3-parameter CoreModule.forRoot)
+   * because CoreAuthModule already registers RolesGuard globally. Setting it to `true`
+   * in Legacy mode would cause duplicate guard registration.
+   *
+   * @default true (secure by default - ensures @Roles() decorators are enforced)
    */
   registerRolesGuardGlobally?: boolean;
 
@@ -218,6 +220,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static customController: null | Type<CoreBetterAuthController> = null;
   private static customResolver: null | Type<CoreBetterAuthResolver> = null;
   private static shouldRegisterRolesGuardGlobally = false;
+  // Track if registerRolesGuardGlobally was explicitly set to false (for warning)
+  private static rolesGuardExplicitlyDisabled = false;
 
   /**
    * Gets the controller class to use (custom or default)
@@ -248,6 +252,16 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     if (this.rateLimiter && CoreBetterAuthModule.currentConfig?.rateLimit) {
       this.rateLimiter.configure(CoreBetterAuthModule.currentConfig.rateLimit);
     }
+
+    // Security warning: Check if RolesGuard is registered when explicitly disabled
+    // This warning helps developers identify potential security misconfigurations
+    if (CoreBetterAuthModule.rolesGuardExplicitlyDisabled && !RolesGuardRegistry.isRegistered()) {
+      CoreBetterAuthModule.logger.warn(
+        '⚠️ SECURITY WARNING: registerRolesGuardGlobally is explicitly set to false, ' +
+        'but no RolesGuard is registered globally. @Roles() decorators will NOT enforce access control! ' +
+        'Either set registerRolesGuardGlobally: true, or ensure CoreAuthModule (Legacy) is imported.',
+      );
+    }
   }
 
   /**
@@ -357,8 +371,12 @@ 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;
+    // Store whether to register RolesGuard globally
+    // Default is true (secure by default) - ensures @Roles() decorators are enforced
+    // CoreModule.forRoot sets this to false in Legacy mode (where CoreAuthModule handles it)
+    this.shouldRegisterRolesGuardGlobally = registerRolesGuardGlobally ?? true;
+    // Track if explicitly disabled (for security warning in onModuleInit)
+    this.rolesGuardExplicitlyDisabled = 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
@@ -526,6 +544,9 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.customController = null;
     this.customResolver = null;
     this.shouldRegisterRolesGuardGlobally = false;
+    this.rolesGuardExplicitlyDisabled = false;
+    // Reset shared RolesGuard registry (shared with CoreAuthModule)
+    RolesGuardRegistry.reset();
   }
 
   /**
@@ -627,13 +648,17 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         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,
-              },
-            ]
+        // Uses shared RolesGuardRegistry to prevent duplicate registration across modules
+        ...(this.shouldRegisterRolesGuardGlobally && !RolesGuardRegistry.isRegistered()
+          ? (() => {
+              RolesGuardRegistry.markRegistered('CoreBetterAuthModule');
+              return [
+                {
+                  provide: APP_GUARD,
+                  useClass: RolesGuard,
+                },
+              ];
+            })()
           : []),
       ],
     };

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

@@ -5,6 +5,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 { ErrorCode } from '../error-code/error-codes';
 import {
   BetterAuth2FAResponse,
   BetterAuthSignInResponse,
@@ -203,7 +204,7 @@ export class CoreBetterAuthResolver {
 
     const api = this.betterAuthService.getApi();
     if (!api) {
-      throw new BadRequestException('Better-Auth API not available');
+      throw new BadRequestException(ErrorCode.BETTERAUTH_API_NOT_AVAILABLE);
     }
 
     // Try to sign in, with automatic legacy user migration
@@ -239,7 +240,7 @@ export class CoreBetterAuthResolver {
       }
 
       if (!response) {
-        throw new UnauthorizedException('Invalid credentials');
+        throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
       }
 
       // Check for 2FA requirement
@@ -271,7 +272,7 @@ export class CoreBetterAuthResolver {
         };
       }
 
-      throw new UnauthorizedException('Invalid credentials');
+      throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
     } catch (error) {
       this.logger.debug(
         `[SignIn] Sign-in failed for ${maskEmail(email)}: ${error instanceof Error ? error.message : 'Unknown error'}`,
@@ -291,7 +292,7 @@ export class CoreBetterAuthResolver {
         }
       }
 
-      throw new UnauthorizedException('Invalid credentials');
+      throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
     }
   }
 
@@ -308,7 +309,7 @@ export class CoreBetterAuthResolver {
     })) as BetterAuthSignInResponse | null;
 
     if (!response || !hasUser(response)) {
-      throw new UnauthorizedException('Invalid credentials');
+      throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
     }
 
     if (requires2FA(response)) {
@@ -348,7 +349,7 @@ export class CoreBetterAuthResolver {
 
     const api = this.betterAuthService.getApi();
     if (!api) {
-      throw new BadRequestException('Better-Auth API not available');
+      throw new BadRequestException(ErrorCode.BETTERAUTH_API_NOT_AVAILABLE);
     }
 
     try {
@@ -361,7 +362,7 @@ export class CoreBetterAuthResolver {
       })) as BetterAuthSignUpResponse | null;
 
       if (!response) {
-        throw new BadRequestException('Sign-up failed');
+        throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
       }
 
       if (hasUser(response)) {
@@ -379,14 +380,14 @@ export class CoreBetterAuthResolver {
         };
       }
 
-      throw new BadRequestException('Sign-up failed');
+      throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
       this.logger.debug(`Sign-up error: ${errorMessage}`);
       if (errorMessage.includes('already exists')) {
-        throw new BadRequestException('User with this email already exists');
+        throw new BadRequestException(ErrorCode.EMAIL_ALREADY_EXISTS);
       }
-      throw new BadRequestException('Sign-up failed');
+      throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
     }
   }
 
@@ -429,12 +430,12 @@ export class CoreBetterAuthResolver {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isTwoFactorEnabled()) {
-      throw new BadRequestException('Two-factor authentication is not enabled');
+      throw new BadRequestException(ErrorCode.TWO_FACTOR_NOT_ENABLED_SERVER);
     }
 
     const api = this.betterAuthService.getApi();
     if (!api) {
-      throw new BadRequestException('Better-Auth API not available');
+      throw new BadRequestException(ErrorCode.BETTERAUTH_API_NOT_AVAILABLE);
     }
 
     try {
@@ -450,7 +451,7 @@ export class CoreBetterAuthResolver {
           };
 
       if (!twoFactorApi?.verifyTotp) {
-        throw new BadRequestException('2FA verification method not available');
+        throw new BadRequestException(ErrorCode.TWO_FACTOR_METHOD_NOT_AVAILABLE);
       }
 
       const response = await twoFactorApi.verifyTotp({
@@ -469,10 +470,10 @@ export class CoreBetterAuthResolver {
         };
       }
 
-      throw new UnauthorizedException('Invalid 2FA code');
+      throw new UnauthorizedException(ErrorCode.INVALID_2FA_CODE);
     } catch (error) {
       this.logger.debug(`2FA verification error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      throw new UnauthorizedException('Invalid 2FA code');
+      throw new UnauthorizedException(ErrorCode.INVALID_2FA_CODE);
     }
   }
 
@@ -546,7 +547,7 @@ export class CoreBetterAuthResolver {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isTwoFactorEnabled()) {
-      throw new BadRequestException('Two-factor authentication is not enabled on this server');
+      throw new BadRequestException(ErrorCode.TWO_FACTOR_NOT_ENABLED_SERVER);
     }
 
     const api = this.betterAuthService.getApi();
@@ -564,7 +565,7 @@ export class CoreBetterAuthResolver {
           };
 
       if (!twoFactorApi?.disable) {
-        throw new BadRequestException('2FA disable method not available');
+        throw new BadRequestException(ErrorCode.TWO_FACTOR_METHOD_NOT_AVAILABLE);
       }
 
       const response = await twoFactorApi.disable({
@@ -591,7 +592,7 @@ export class CoreBetterAuthResolver {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isTwoFactorEnabled()) {
-      throw new BadRequestException('Two-factor authentication is not enabled on this server');
+      throw new BadRequestException(ErrorCode.TWO_FACTOR_NOT_ENABLED_SERVER);
     }
 
     const api = this.betterAuthService.getApi();
@@ -609,7 +610,7 @@ export class CoreBetterAuthResolver {
           };
 
       if (!twoFactorApi?.generateBackupCodes) {
-        throw new BadRequestException('Generate backup codes method not available');
+        throw new BadRequestException(ErrorCode.TWO_FACTOR_METHOD_NOT_AVAILABLE);
       }
 
       const response = await twoFactorApi.generateBackupCodes({ headers });
@@ -731,7 +732,7 @@ export class CoreBetterAuthResolver {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isPasskeyEnabled()) {
-      throw new BadRequestException('Passkey authentication is not enabled on this server');
+      throw new BadRequestException(ErrorCode.PASSKEY_NOT_ENABLED_SERVER);
     }
 
     const api = this.betterAuthService.getApi();
@@ -749,7 +750,7 @@ export class CoreBetterAuthResolver {
           };
 
       if (!passkeyApi?.deletePasskey) {
-        throw new BadRequestException('Delete passkey method not available');
+        throw new BadRequestException(ErrorCode.TWO_FACTOR_METHOD_NOT_AVAILABLE);
       }
 
       const response = await passkeyApi.deletePasskey({
@@ -773,9 +774,7 @@ export class CoreBetterAuthResolver {
    */
   protected ensureEnabled(): void {
     if (!this.betterAuthService.isEnabled()) {
-      throw new BadRequestException(
-        'Better-Auth is not enabled. Check that betterAuth.enabled is not set to false in your environment.',
-      );
+      throw new BadRequestException(ErrorCode.BETTERAUTH_DISABLED);
     }
   }
 

package/src/core/modules/error-code/error-codes.ts

@@ -133,6 +133,106 @@ export const LtnsErrors = {
     },
   },
 
+  // BetterAuth specific errors (LTNS_0010-LTNS_0049)
+  INVALID_CREDENTIALS: {
+    code: 'LTNS_0010',
+    message: 'Invalid credentials',
+    translations: {
+      de: 'Ungültige Anmeldedaten.',
+      en: 'Invalid credentials.',
+    },
+  },
+
+  INVALID_2FA_CODE: {
+    code: 'LTNS_0011',
+    message: 'Invalid 2FA code',
+    translations: {
+      de: 'Der 2FA-Code ist ungültig.',
+      en: 'The 2FA code is invalid.',
+    },
+  },
+
+  TWO_FACTOR_NOT_ENABLED: {
+    code: 'LTNS_0012',
+    message: 'Two-factor authentication is not enabled',
+    translations: {
+      de: 'Zwei-Faktor-Authentifizierung ist nicht aktiviert.',
+      en: 'Two-factor authentication is not enabled.',
+    },
+  },
+
+  TWO_FACTOR_NOT_ENABLED_SERVER: {
+    code: 'LTNS_0013',
+    message: 'Two-factor authentication is not enabled on this server',
+    translations: {
+      de: 'Zwei-Faktor-Authentifizierung ist auf diesem Server nicht aktiviert.',
+      en: 'Two-factor authentication is not enabled on this server.',
+    },
+  },
+
+  PASSKEY_NOT_ENABLED_SERVER: {
+    code: 'LTNS_0014',
+    message: 'Passkey authentication is not enabled on this server',
+    translations: {
+      de: 'Passkey-Authentifizierung ist auf diesem Server nicht aktiviert.',
+      en: 'Passkey authentication is not enabled on this server.',
+    },
+  },
+
+  SIGNUP_FAILED: {
+    code: 'LTNS_0015',
+    message: 'Sign-up failed',
+    translations: {
+      de: 'Die Registrierung ist fehlgeschlagen.',
+      en: 'Sign-up failed.',
+    },
+  },
+
+  BETTERAUTH_NOT_INITIALIZED: {
+    code: 'LTNS_0016',
+    message: 'Better-Auth not initialized',
+    translations: {
+      de: 'Better-Auth ist nicht initialisiert.',
+      en: 'Better-Auth is not initialized.',
+    },
+  },
+
+  BETTERAUTH_DISABLED: {
+    code: 'LTNS_0017',
+    message: 'Better-Auth is disabled',
+    translations: {
+      de: 'Better-Auth ist deaktiviert.',
+      en: 'Better-Auth is disabled.',
+    },
+  },
+
+  BETTERAUTH_API_NOT_AVAILABLE: {
+    code: 'LTNS_0018',
+    message: 'Better-Auth API not available',
+    translations: {
+      de: 'Better-Auth API ist nicht verfügbar.',
+      en: 'Better-Auth API is not available.',
+    },
+  },
+
+  TWO_FACTOR_METHOD_NOT_AVAILABLE: {
+    code: 'LTNS_0019',
+    message: '2FA verification method not available',
+    translations: {
+      de: '2FA-Verifizierungsmethode ist nicht verfügbar.',
+      en: '2FA verification method is not available.',
+    },
+  },
+
+  RATE_LIMIT_EXCEEDED: {
+    code: 'LTNS_0020',
+    message: 'Too many requests',
+    translations: {
+      de: 'Zu viele Anfragen. Bitte versuchen Sie es später erneut.',
+      en: 'Too many requests. Please try again later.',
+    },
+  },
+
   // =====================================================
   // Authorization Errors (LTNS_0100-LTNS_0199)
   // =====================================================

package/src/core.module.ts

@@ -247,12 +247,25 @@ export class CoreModule implements NestModule {
     }
 
     // Add CoreBetterAuthModule based on mode
-    // IAM-only mode: Always register CoreBetterAuthModule (required for subscription auth)
+    // IAM-only mode: BetterAuth is enabled by default (it's the only auth option)
     // Legacy mode: Only register if autoRegister is explicitly true
     // betterAuth can be: boolean | IBetterAuth | undefined
     const betterAuthConfig = config.betterAuth;
-    const isBetterAuthEnabled =
-      betterAuthConfig === true || (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled !== false);
+
+    // Determine if BetterAuth is explicitly disabled
+    // In IAM-only mode: enabled by default (undefined = true), only false or { enabled: false } disables
+    // In Legacy mode: disabled by default (undefined = false), must be explicitly enabled
+    const isExplicitlyDisabled = betterAuthConfig === false ||
+      (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled === false);
+    const isExplicitlyEnabled = betterAuthConfig === true ||
+      (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled !== false);
+
+    // IAM-only mode: enabled unless explicitly disabled
+    // Legacy mode: enabled only if explicitly enabled
+    const isBetterAuthEnabled = isIamOnlyMode
+      ? !isExplicitlyDisabled
+      : isExplicitlyEnabled;
+
     const isAutoRegister = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === true;
 
     if (isBetterAuthEnabled) {

package/src/index.ts

@@ -112,6 +112,7 @@ export * from './core/modules/auth/exceptions/invalid-token.exception';
 export * from './core/modules/auth/exceptions/legacy-auth-disabled.exception';
 export * from './core/modules/auth/guards/auth.guard';
 export * from './core/modules/auth/guards/legacy-auth-rate-limit.guard';
+export * from './core/modules/auth/guards/roles-guard-registry';
 export * from './core/modules/auth/guards/roles.guard';
 export * from './core/modules/auth/inputs/core-auth-sign-in.input';
 export * from './core/modules/auth/inputs/core-auth-sign-up.input';