@lenne.tech/nest-server 11.13.1 → 11.13.2

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/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.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';

package/src/core.module.ts

@@ -137,9 +137,15 @@ export class CoreModule implements NestModule {
       };
     }
 
+    // Check if autoRegister: false for IAM-only mode (project imports its own BetterAuth module)
+    const rawBetterAuth = options?.betterAuth;
+    const isAutoRegisterDisabledEarly = typeof rawBetterAuth === 'object' && rawBetterAuth?.autoRegister === false;
+
     // Build GraphQL driver configuration based on auth mode
     const graphQlDriverConfig = isIamOnlyMode
-      ? this.buildIamOnlyGraphQlDriver(cors, options)
+      ? (isAutoRegisterDisabledEarly
+        ? this.buildLazyIamGraphQlDriver(cors, options)
+        : this.buildIamOnlyGraphQlDriver(cors, options))
       : this.buildLegacyGraphQlDriver(AuthService, AuthModule, cors, options);
 
     const config: IServerOptions = merge(
@@ -267,17 +273,27 @@ export class CoreModule implements NestModule {
       : isExplicitlyEnabled;
 
     const isAutoRegister = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === true;
+    // autoRegister: false means the project imports its own BetterAuthModule separately
+    const isAutoRegisterDisabled = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === false;
+
+    // Extract custom controller/resolver from config (Pattern 2: Config-based)
+    const configController = typeof betterAuthConfig === 'object' ? betterAuthConfig?.controller : undefined;
+    const configResolver = typeof betterAuthConfig === 'object' ? betterAuthConfig?.resolver : undefined;
 
     if (isBetterAuthEnabled) {
-      if (isIamOnlyMode || isAutoRegister) {
+      if ((isIamOnlyMode && !isAutoRegisterDisabled) || isAutoRegister) {
         imports.push(
           CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
+            // Pass custom controller/resolver from config (Pattern 2)
+            controller: configController,
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
             // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
             // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
             registerRolesGuardGlobally: isIamOnlyMode,
+            // Pass custom resolver from config (Pattern 2)
+            resolver: configResolver,
             // Pass server-level URLs for Passkey auto-detection
             // When env: 'local', defaults are: baseUrl=localhost:3000, appUrl=localhost:3001
             serverAppUrl: config.appUrl,
@@ -399,6 +415,108 @@ export class CoreModule implements NestModule {
     };
   }
 
+  /**
+   * Build a lazy GraphQL driver for IAM-only mode with autoRegister: false.
+   *
+   * When autoRegister: false, CoreBetterAuthModule is NOT imported by CoreModule,
+   * so we cannot use `imports` or `inject` to get BetterAuth services.
+   * Instead, we resolve them lazily via static getters on CoreBetterAuthModule.
+   * This is safe because `onConnect` is only called when a WebSocket connection is made,
+   * which happens after all modules are initialized.
+   */
+  private static buildLazyIamGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
+    return {
+      useFactory: async () =>
+        Object.assign(
+          {
+            autoSchemaFile: 'schema.gql',
+            context: ({ req, res }) => ({ req, res }),
+            cors,
+            installSubscriptionHandlers: true,
+            subscriptions: {
+              'graphql-ws': {
+                context: ({ extra }) => extra,
+                onConnect: async (context: Context<any>) => {
+                  const { connectionParams, extra } = context;
+                  const enableAuth = options?.graphQl?.enableSubscriptionAuth ?? true;
+
+                  if (enableAuth) {
+                    const betterAuthService = CoreBetterAuthModule.getServiceInstance();
+                    const userMapper = CoreBetterAuthModule.getUserMapperInstance();
+
+                    if (!betterAuthService || !userMapper) {
+                      throw new UnauthorizedException('BetterAuth not initialized');
+                    }
+
+                    const headers = CoreModule.getHeaderFromArray(extra.request?.rawHeaders);
+                    const authToken: string =
+                      connectionParams?.Authorization?.split(' ')[1] ?? headers.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      const { session, user: sessionUser } = await betterAuthService.getSession({
+                        headers: { authorization: `Bearer ${authToken}` },
+                      });
+
+                      if (!session || !sessionUser) {
+                        throw new UnauthorizedException('Invalid or expired session');
+                      }
+
+                      const user = await userMapper.mapSessionUser(sessionUser);
+                      if (!user) {
+                        throw new UnauthorizedException('User not found');
+                      }
+
+                      extra.user = user;
+                      extra.headers = connectionParams ?? headers;
+                      return extra;
+                    }
+
+                    throw new UnauthorizedException('Missing authentication token');
+                  }
+                },
+              },
+              'subscriptions-transport-ws': {
+                onConnect: async (connectionParams) => {
+                  const enableAuth = options?.graphQl?.enableSubscriptionAuth ?? true;
+
+                  if (enableAuth) {
+                    const betterAuthService = CoreBetterAuthModule.getServiceInstance();
+                    const userMapper = CoreBetterAuthModule.getUserMapperInstance();
+
+                    if (!betterAuthService || !userMapper) {
+                      throw new UnauthorizedException('BetterAuth not initialized');
+                    }
+
+                    const authToken: string = connectionParams?.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      const { session, user: sessionUser } = await betterAuthService.getSession({
+                        headers: { authorization: `Bearer ${authToken}` },
+                      });
+
+                      if (!session || !sessionUser) {
+                        throw new UnauthorizedException('Invalid or expired session');
+                      }
+
+                      const user = await userMapper.mapSessionUser(sessionUser);
+                      if (!user) {
+                        throw new UnauthorizedException('User not found');
+                      }
+
+                      return { headers: connectionParams, user };
+                    }
+
+                    throw new UnauthorizedException('Missing authentication token');
+                  }
+                },
+              },
+            },
+          },
+          options?.graphQl?.driver,
+        ),
+    };
+  }
+
   /**
    * Build GraphQL driver configuration for Legacy Auth mode
    *