@lenne.tech/nest-server 11.10.3 → 11.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.10.3",
+  "version": "11.10.4",
   "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.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.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';