@lenne.tech/nest-server 11.13.1 → 11.13.3

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -0,0 +1,205 @@
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable, Logger, UnauthorizedException } from '@nestjs/common';
+import { GqlExecutionContext } from '@nestjs/graphql';
+
+import { RoleEnum } from '../../common/enums/role.enum';
+import { ErrorCode } from '../error-code';
+import { BetterAuthTokenService } from './better-auth-token.service';
+import { BetterAuthenticatedUser } from './better-auth.types';
+import { CoreBetterAuthModule } from './core-better-auth.module';
+
+/**
+ * BetterAuth Roles Guard
+ *
+ * A simplified roles guard for BetterAuth (IAM-only) mode that does NOT extend AuthGuard.
+ * This avoids the mixin inheritance DI issues that occur with the standard RolesGuard.
+ *
+ * In IAM-only mode, authentication is handled by CoreBetterAuthMiddleware which:
+ * 1. Validates JWT tokens or session tokens
+ * 2. Sets req.user with the authenticated user (with _authenticatedViaBetterAuth flag)
+ *
+ * If the middleware hasn't set req.user (e.g., in test environments), this guard will
+ * try to verify the token directly using BetterAuthTokenService.
+ *
+ * No Passport integration is needed because BetterAuth handles all token validation.
+ *
+ * IMPORTANT: This guard has NO constructor dependencies. This is intentional because
+ * NestJS DI has issues resolving Reflector/ModuleRef for APP_GUARD providers in dynamic modules.
+ * Instead, we use Reflect.getMetadata directly to read decorator metadata, and access
+ * BetterAuthTokenService via CoreBetterAuthModule static reference.
+ */
+@Injectable()
+export class BetterAuthRolesGuard implements CanActivate {
+  private readonly logger = new Logger(BetterAuthRolesGuard.name);
+  private tokenService: BetterAuthTokenService | null = null;
+
+  /**
+   * Get BetterAuthTokenService lazily from CoreBetterAuthModule
+   * This avoids DI issues while still allowing token verification
+   */
+  private getTokenService(): BetterAuthTokenService | null {
+    if (!this.tokenService) {
+      this.tokenService = CoreBetterAuthModule.getTokenServiceInstance();
+    }
+    return this.tokenService;
+  }
+
+  /**
+   * Try to verify a BetterAuth token if user isn't already on the request.
+   * This handles cases where middleware didn't run (e.g., test environments).
+   */
+  private async verifyToken(request: any): Promise<BetterAuthenticatedUser | null> {
+    const tokenService = this.getTokenService();
+    if (!tokenService) {
+      return null;
+    }
+
+    try {
+      const { token } = tokenService.extractTokenFromRequest(request);
+      if (!token) {
+        return null;
+      }
+      return await tokenService.verifyAndLoadUser(token);
+    } catch (error) {
+      this.logger.debug(`Token verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Get roles from decorator metadata using Reflect.getMetadata directly
+    // This avoids the need for NestJS Reflector which causes DI issues in dynamic modules
+    const handlerRoles = Reflect.getMetadata('roles', context.getHandler()) as string[] | undefined;
+    const classRoles = Reflect.getMetadata('roles', context.getClass()) as string[] | undefined;
+
+    // Combine handler and class roles (handler takes precedence, like Reflector.getAll)
+    const reflectorRoles: (string[] | undefined)[] = [handlerRoles, classRoles];
+    const roles: string[] = reflectorRoles[0]
+      ? reflectorRoles[1]
+        ? [...reflectorRoles[0], ...reflectorRoles[1]]
+        : reflectorRoles[0]
+      : reflectorRoles[1];
+
+    // Check if locked - always deny
+    if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+    }
+
+    // If no roles required, or S_EVERYONE is set, allow access without authentication
+    if (!roles || !roles.some((value) => !!value) || roles.includes(RoleEnum.S_EVERYONE)) {
+      return true;
+    }
+
+    // Get request and check for user (set by BetterAuth middleware)
+    const request = this.getRequest(context);
+    let user = request?.user;
+
+    // If user isn't set (e.g., middleware didn't run in test environment),
+    // try to verify the token directly
+    if (!user) {
+      user = await this.verifyToken(request);
+      if (user && request) {
+        // Store the verified user on the request for downstream handlers
+        request.user = user;
+      }
+    }
+
+    // Check if user is authenticated
+    if (!user) {
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+    }
+
+    // Check S_USER role - any authenticated user is allowed
+    if (roles.includes(RoleEnum.S_USER)) {
+      return true;
+    }
+
+    // Check S_SELF role - user is accessing their own data
+    if (roles.includes(RoleEnum.S_SELF)) {
+      // Get the target object's ID from params or args
+      const targetId = this.getTargetId(context);
+      if (targetId && user.id === targetId) {
+        return true;
+      }
+    }
+
+    // Check S_CREATOR role - user created the object
+    if (roles.includes(RoleEnum.S_CREATOR)) {
+      // This requires the object to have a createdBy field
+      // Usually checked in services, but we can't access the object here
+      // Let it pass and check in the service/resolver
+      this.logger.debug('S_CREATOR check deferred to service layer');
+    }
+
+    // Check S_VERIFIED role - user's email is verified
+    if (roles.includes(RoleEnum.S_VERIFIED)) {
+      if (!user.verified && !user.verifiedAt && !user.emailVerified) {
+        throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
+      }
+      return true;
+    }
+
+    // Check if user has required role
+    if (user.hasRole?.(roles)) {
+      return true;
+    }
+
+    // Check if user's roles array includes any of the required roles
+    if (user.roles && Array.isArray(user.roles)) {
+      const hasRequiredRole = roles.some((role) => user.roles.includes(role));
+      if (hasRequiredRole) {
+        return true;
+      }
+    }
+
+    // User doesn't have required role
+    throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
+  }
+
+  /**
+   * Get request from execution context
+   * Handles both GraphQL and HTTP contexts
+   */
+  private getRequest(context: ExecutionContext): any {
+    // Try GraphQL context first
+    try {
+      const gqlContext = GqlExecutionContext.create(context);
+      const ctx = gqlContext.getContext();
+      if (ctx?.req) {
+        return ctx.req;
+      }
+    } catch {
+      // GraphQL context not available
+    }
+
+    // Fallback to HTTP context
+    return context.switchToHttp().getRequest();
+  }
+
+  /**
+   * Get target ID from context for S_SELF checks
+   */
+  private getTargetId(context: ExecutionContext): null | string {
+    // Try GraphQL args
+    try {
+      const gqlContext = GqlExecutionContext.create(context);
+      const args = gqlContext.getArgs();
+      if (args?.id) {
+        return args.id;
+      }
+    } catch {
+      // GraphQL context not available
+    }
+
+    // Try HTTP params
+    try {
+      const request = context.switchToHttp().getRequest();
+      if (request?.params?.id) {
+        return request.params.id;
+      }
+    } catch {
+      // HTTP context not available
+    }
+
+    return null;
+  }
+}

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

@@ -14,6 +14,21 @@ import { IBetterAuth } from '../../common/interfaces/server-options.interface';
  */
 export type BetterAuthInstance = ReturnType<typeof betterAuth>;
 
+// ---------------------------------------------------------------------------
+// Performance-optimized password hashing using Node.js native crypto.scrypt
+//
+// Better-Auth's default uses @noble/hashes scrypt which runs on the main
+// event loop. Under concurrent load this blocks all requests while hashing.
+// Node.js crypto.scrypt() offloads the work to the libuv thread pool,
+// allowing the event loop to remain responsive.
+//
+// Parameters match Better-Auth's defaults exactly:
+//   N=16384, r=16, p=1, dkLen=64, 16-byte salt
+// ---------------------------------------------------------------------------
+
+const SCRYPT_PARAMS = { maxmem: 128 * 16384 * 16 * 2, N: 16384, p: 1, r: 16 };
+const SCRYPT_KEY_LENGTH = 64;
+
 /**
  * Generates a cryptographically secure random secret.
  * Used as fallback when no BETTER_AUTH_SECRET is configured.
@@ -27,6 +42,38 @@ function generateSecureSecret(): string {
   return crypto.randomBytes(32).toString('base64');
 }
 
+/**
+ * Hash a password using Node.js native crypto.scrypt (libuv thread pool).
+ * Output format matches Better-Auth: "salt:hash" (both hex encoded).
+ */
+async function nativeScryptHash(password: string): Promise<string> {
+  const salt = crypto.randomBytes(16).toString('hex');
+  const normalized = password.normalize('NFKC');
+  const key = await new Promise<Buffer>((resolve, reject) => {
+    crypto.scrypt(normalized, salt, SCRYPT_KEY_LENGTH, SCRYPT_PARAMS, (err, derivedKey) => {
+      if (err) reject(err);
+      else resolve(derivedKey);
+    });
+  });
+  return `${salt}:${key.toString('hex')}`;
+}
+
+/**
+ * Verify a password against a Better-Auth scrypt hash using Node.js native crypto.scrypt.
+ */
+async function nativeScryptVerify(data: { hash: string; password: string }): Promise<boolean> {
+  const [salt, storedKey] = data.hash.split(':');
+  if (!salt || !storedKey) return false;
+  const normalized = data.password.normalize('NFKC');
+  const key = await new Promise<Buffer>((resolve, reject) => {
+    crypto.scrypt(normalized, salt, SCRYPT_KEY_LENGTH, SCRYPT_PARAMS, (err, derivedKey) => {
+      if (err) reject(err);
+      else resolve(derivedKey);
+    });
+  });
+  return crypto.timingSafeEqual(key, Buffer.from(storedKey, 'hex'));
+}
+
 /**
  * Cached auto-generated secret for the current server instance.
  * Generated once at a module load to ensure consistency within a single run.
@@ -268,6 +315,10 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
     // Can be disabled by setting config.emailAndPassword.enabled = false
     emailAndPassword: {
       enabled: config.emailAndPassword?.enabled !== false,
+      password: {
+        hash: nativeScryptHash,
+        verify: nativeScryptVerify,
+      },
     },
     plugins,
     secret: validation.resolvedSecret || config.secret,

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

@@ -332,6 +332,12 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         }
       }
 
+      // If Better Auth returned 404, the path is not handled by Better Auth.
+      // Call next() to let NestJS controllers handle it (e.g., custom controller endpoints).
+      if (response.status === 404) {
+        return next();
+      }
+
       // Convert Web Standard Response to Express response using shared helper
       await sendWebResponse(res, response);
     } catch (error) {

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

@@ -409,11 +409,27 @@ export class CoreBetterAuthEmailVerificationService {
     return elapsed < cooldown;
   }
 
+  /**
+   * Maximum entries in the lastSendTimes map to prevent unbounded growth.
+   * At 10,000 entries with email strings as keys, this uses ~1-2 MB max.
+   */
+  private static readonly MAX_SEND_TIMES_ENTRIES = 10000;
+
   /**
    * Track that a verification email was sent to this address
    */
   protected trackSend(email: string): void {
     const key = email.toLowerCase();
+
+    // Evict oldest entry if map is at capacity (before adding new one)
+    if (!this.lastSendTimes.has(key) && this.lastSendTimes.size >= CoreBetterAuthEmailVerificationService.MAX_SEND_TIMES_ENTRIES) {
+      // Map preserves insertion order - first key is the oldest
+      const oldestKey = this.lastSendTimes.keys().next().value;
+      if (oldestKey) {
+        this.lastSendTimes.delete(oldestKey);
+      }
+    }
+
     this.lastSendTimes.set(key, Date.now());
 
     // Schedule cleanup to prevent memory leak

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

@@ -46,6 +46,7 @@ interface RateLimitEntry {
 const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
   enabled: false,
   max: 10,
+  maxEntries: 10000,
   message: 'Too many requests, please try again later.',
   skipEndpoints: ['/session', '/callback'],
   strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
@@ -143,6 +144,11 @@ export class CoreBetterAuthRateLimiter {
     let entry = this.store.get(key);
 
     if (!entry || now >= entry.resetTime) {
+      // Evict oldest entries if store exceeds maxEntries
+      if (!entry && this.store.size >= this.config.maxEntries) {
+        this.evictOldest();
+      }
+
       // Create new entry or reset expired one
       entry = {
         count: 1,
@@ -234,6 +240,40 @@ export class CoreBetterAuthRateLimiter {
     }
   }
 
+  /**
+   * Evict the oldest entries when the store exceeds maxEntries.
+   * First removes all expired entries, then removes entries closest to expiry
+   * until the store is at 90% capacity.
+   */
+  private evictOldest(): void {
+    const now = Date.now();
+    let evicted = 0;
+
+    // First pass: remove all expired entries
+    for (const [key, entry] of this.store.entries()) {
+      if (now >= entry.resetTime) {
+        this.store.delete(key);
+        evicted++;
+      }
+    }
+
+    // If still over limit, remove entries with earliest resetTime (oldest)
+    if (this.store.size >= this.config.maxEntries) {
+      const targetSize = Math.floor(this.config.maxEntries * 0.9);
+      const entries = [...this.store.entries()].sort((a, b) => a[1].resetTime - b[1].resetTime);
+
+      for (const [key] of entries) {
+        if (this.store.size <= targetSize) break;
+        this.store.delete(key);
+        evicted++;
+      }
+    }
+
+    if (evicted > 0) {
+      this.logger.warn(`Evicted ${evicted} rate limit entries (store was at capacity: ${this.config.maxEntries})`);
+    }
+  }
+
   /**
    * Determine if an endpoint should skip rate limiting
    */

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -370,27 +370,38 @@ export class CoreBetterAuthUserMapper {
         return false;
       }
 
+      // Better-Auth stores account.userId as ObjectId that references users._id
+      const userMongoId = legacyUser._id as ObjectId;
+
+      // FAST PATH: Check if credential account already exists BEFORE expensive bcrypt
+      // For already-migrated users this avoids ~130ms of bcrypt.compare() per sign-in
+      const existingAccount = await accountsCollection.findOne({
+        providerId: 'credential',
+        userId: userMongoId,
+      });
+
+      if (existingAccount) {
+        return true;
+      }
+
+      // No password provided - cannot verify, cannot migrate
+      if (!plainPassword) {
+        return false;
+      }
+
       // IMPORTANT: Verify the provided password matches the legacy hash
       // This prevents migration with a wrong password
       // Legacy Auth uses two formats for backwards compatibility:
       // 1. bcrypt(password) - direct hash
       // 2. bcrypt(sha256(password)) - sha256 then bcrypt
-      if (plainPassword) {
-        const directMatch = await bcrypt.compare(plainPassword, legacyUser.password);
-        const sha256Match = await bcrypt.compare(sha256(plainPassword), legacyUser.password);
-        if (!directMatch && !sha256Match) {
-          // Security: Wrong password provided for migration - reject
-          this.logger.warn(`Migration password verification failed for ${maskEmail(userEmail)}`);
-          return false;
-        }
-      } else {
-        // No password provided - cannot verify, cannot migrate
+      const directMatch = await bcrypt.compare(plainPassword, legacyUser.password);
+      const sha256Match = !directMatch ? await bcrypt.compare(sha256(plainPassword), legacyUser.password) : false;
+      if (!directMatch && !sha256Match) {
+        // Security: Wrong password provided for migration - reject
+        this.logger.warn(`Migration password verification failed for ${maskEmail(userEmail)}`);
         return false;
       }
 
-      // Better-Auth stores account.userId as ObjectId that references users._id
-      // The id field is a secondary string identifier used in API responses
-      const userMongoId = legacyUser._id as ObjectId;
       const userIdHex = userMongoId.toHexString();
 
       // Update user with Better-Auth fields if not already present
@@ -413,17 +424,6 @@ export class CoreBetterAuthUserMapper {
         );
       }
 
-      // Check if credential account already exists
-      // Better-Auth stores userId as ObjectId referencing users._id
-      const existingAccount = await accountsCollection.findOne({
-        providerId: 'credential',
-        userId: userMongoId,
-      });
-
-      if (existingAccount) {
-        return true;
-      }
-
       // Create the credential account with Better-Auth compatible scrypt hash
       const passwordHash = await this.hashPasswordForBetterAuth(plainPassword);
 

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

@@ -17,7 +17,7 @@ import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { BrevoService } from '../../common/services/brevo.service';
 import { ConfigService } from '../../common/services/config.service';
 import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry';
-import { RolesGuard } from '../auth/guards/roles.guard';
+import { BetterAuthRolesGuard } from './better-auth-roles.guard';
 import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthInstance, createBetterAuthInstance } from './better-auth.config';
 import { DefaultBetterAuthResolver } from './better-auth.resolver';
@@ -228,6 +228,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   // Static reference to email verification service for Better-Auth hooks (outside DI context)
   private static emailVerificationService: CoreBetterAuthEmailVerificationService | null = null;
   private static mongoConnection: Connection | null = null;
+  // Safety Net: Track if forRoot() has already been called to detect duplicate registration
+  private static forRootCalled = false;
+  private static cachedDynamicModule: DynamicModule | null = null;
+  // Static references for lazy GraphQL driver (autoRegister: false) and BetterAuthRolesGuard
+  private static serviceInstance: CoreBetterAuthService | null = null;
+  private static userMapperInstance: CoreBetterAuthUserMapper | null = null;
+  private static tokenServiceInstance: BetterAuthTokenService | null = null;
 
   /**
    * Gets the controller class to use (custom or default)
@@ -243,9 +250,38 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     return this.customResolver || DefaultBetterAuthResolver;
   }
 
+  /**
+   * Gets the static CoreBetterAuthService instance.
+   * Used by the lazy GraphQL driver when autoRegister: false.
+   * Safe because onConnect is called only after module initialization.
+   */
+  static getServiceInstance(): CoreBetterAuthService | null {
+    return this.serviceInstance;
+  }
+
+  /**
+   * Gets the static CoreBetterAuthUserMapper instance.
+   * Used by the lazy GraphQL driver when autoRegister: false.
+   * Safe because onConnect is called only after module initialization.
+   */
+  static getUserMapperInstance(): CoreBetterAuthUserMapper | null {
+    return this.userMapperInstance;
+  }
+
+  /**
+   * Gets the static BetterAuthTokenService instance.
+   * Used by BetterAuthRolesGuard for token verification when user isn't already on request.
+   * Safe because guards are invoked only after module initialization.
+   */
+  static getTokenServiceInstance(): BetterAuthTokenService | null {
+    return this.tokenServiceInstance;
+  }
+
   constructor(
     @Optional() private readonly betterAuthService?: CoreBetterAuthService,
     @Optional() private readonly rateLimiter?: CoreBetterAuthRateLimiter,
+    @Optional() private readonly userMapper?: CoreBetterAuthUserMapper,
+    @Optional() private readonly tokenService?: BetterAuthTokenService,
   ) {}
 
   onModuleInit() {
@@ -254,6 +290,17 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       CoreBetterAuthModule.logger.log('CoreBetterAuthModule ready');
     }
 
+    // Store static references for lazy GraphQL driver (autoRegister: false) and BetterAuthRolesGuard
+    if (this.betterAuthService) {
+      CoreBetterAuthModule.serviceInstance = this.betterAuthService;
+    }
+    if (this.userMapper) {
+      CoreBetterAuthModule.userMapperInstance = this.userMapper;
+    }
+    if (this.tokenService) {
+      CoreBetterAuthModule.tokenServiceInstance = this.tokenService;
+    }
+
     // Configure rate limiter with stored config
     if (this.rateLimiter && CoreBetterAuthModule.currentConfig?.rateLimit) {
       this.rateLimiter.configure(CoreBetterAuthModule.currentConfig.rateLimit);
@@ -368,6 +415,24 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: CoreBetterAuthModuleOptions): DynamicModule {
+    // Safety Net: Detect duplicate forRoot() calls
+    // NestJS deduplicates DynamicModules by module class — the FIRST import wins,
+    // subsequent imports are silently ignored. This means custom controller/resolver
+    // from the second call would be lost. Return cached module with a warning.
+    if (this.forRootCalled && !process.env.VITEST) {
+      this.logger.warn(
+        'CoreBetterAuthModule.forRoot() was called more than once. ' +
+        'The second call is ignored by NestJS (DynamicModule deduplication). ' +
+        'Custom controller/resolver from the second call will NOT be registered. ' +
+        'Solutions: (1) Use betterAuth.controller/resolver in config, or ' +
+        '(2) Set betterAuth.autoRegister: false and import your module separately.',
+      );
+      if (this.cachedDynamicModule) {
+        return this.cachedDynamicModule;
+      }
+    }
+    this.forRootCalled = true;
+
     const {
       config: rawConfig,
       controller,
@@ -423,7 +488,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     if (config === null || config?.enabled === false) {
       this.logger.debug('BetterAuth is disabled - skipping initialization');
       this.betterAuthEnabled = false;
-      return {
+      this.cachedDynamicModule = {
         exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
         module: CoreBetterAuthModule,
         providers: [
@@ -442,6 +507,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           // because they require ConfigService and have no purpose when BetterAuth is disabled
         ],
       };
+      return this.cachedDynamicModule;
     }
 
     // Enable middleware registration
@@ -453,12 +519,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     // Always use deferred initialization to ensure MongoDB is ready
     // This prevents timing issues during application startup
     // Pass server-level URLs for Passkey auto-detection (using effective values from ConfigService fallback)
-    return this.createDeferredModule(config, {
+    this.cachedDynamicModule = this.createDeferredModule(config, {
       fallbackSecrets: effectiveFallbackSecrets,
       serverAppUrl: effectiveServerAppUrl,
       serverBaseUrl: effectiveServerBaseUrl,
       serverEnv: effectiveServerEnv,
     });
+    return this.cachedDynamicModule;
   }
 
   /**
@@ -622,6 +689,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.shouldRegisterRolesGuardGlobally = false;
     this.rolesGuardExplicitlyDisabled = false;
     this.emailVerificationService = null;
+    this.mongoConnection = null;
+    // Safety Net: Reset duplicate-call detection
+    this.forRootCalled = false;
+    this.cachedDynamicModule = null;
+    // Lazy GraphQL driver: Reset service references
+    this.serviceInstance = null;
+    this.userMapperInstance = null;
     // Reset shared RolesGuard registry (shared with CoreAuthModule)
     RolesGuardRegistry.reset();
   }
@@ -822,17 +896,20 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         },
         CoreBetterAuthChallengeService,
         this.getResolverClass(),
-        // Conditionally register RolesGuard globally for IAM-only setups
-        // In Legacy mode, RolesGuard is already registered globally via CoreAuthModule
+        // Conditionally register BetterAuthRolesGuard globally for IAM-only setups
+        // In Legacy mode, RolesGuard is registered globally via CoreAuthModule instead
         // Uses shared RolesGuardRegistry to prevent duplicate registration across modules
+        //
+        // Note: We use BetterAuthRolesGuard (not RolesGuard) in IAM-only mode because:
+        // - RolesGuard extends AuthGuard (a Passport mixin) which has DI metadata conflicts
+        // - BetterAuthRolesGuard is a simpler guard that only checks roles
+        // - Authentication is handled by CoreBetterAuthMiddleware (JWT/session validation)
         ...(this.shouldRegisterRolesGuardGlobally && !RolesGuardRegistry.isRegistered()
           ? (() => {
               RolesGuardRegistry.markRegistered('CoreBetterAuthModule');
               return [
-                {
-                  provide: APP_GUARD,
-                  useClass: RolesGuard,
-                },
+                BetterAuthRolesGuard,
+                { provide: APP_GUARD, useExisting: BetterAuthRolesGuard },
               ];
             })()
           : []),

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

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