@lenne.tech/nest-server 11.7.0 → 11.7.1

package/src/core.module.ts

@@ -19,7 +19,9 @@ import { EmailService } from './core/common/services/email.service';
 import { MailjetService } from './core/common/services/mailjet.service';
 import { ModelDocService } from './core/common/services/model-doc.service';
 import { TemplateService } from './core/common/services/template.service';
+import { BetterAuthUserMapper } from './core/modules/better-auth/better-auth-user.mapper';
 import { BetterAuthModule } from './core/modules/better-auth/better-auth.module';
+import { BetterAuthService } from './core/modules/better-auth/better-auth.service';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 
 /**
@@ -66,10 +68,65 @@ export class CoreModule implements NestModule {
   }
 
   /**
-   * Dynamic module
-   * see https://docs.nestjs.com/modules#dynamic-modules
+   * Dynamic module initialization
+   *
+   * @see https://docs.nestjs.com/modules#dynamic-modules
+   *
+   * ## Signatures
+   *
+   * ### IAM-Only Signature (Recommended for new projects)
+   *
+   * ```typescript
+   * CoreModule.forRoot(envConfig)
+   * ```
+   *
+   * Use this for new projects that only use BetterAuth (IAM) for authentication.
+   * GraphQL Subscription authentication uses BetterAuth JWT tokens.
+   *
+   * **Requirements:**
+   * - Configure `betterAuth` in your config (enabled by default)
+   * - Create BetterAuthModule, Resolver, and Controller in your project
+   * - Inject BetterAuthUserMapper in UserService
+   *
+   * ### Legacy + IAM Signature (For existing projects)
+   *
+   * ```typescript
+   * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig)
+   * ```
+   *
+   * @deprecated This 3-parameter signature is deprecated for new projects.
+   * Use the single-parameter signature `CoreModule.forRoot(envConfig)` instead.
+   * Existing projects can continue using this signature during migration.
+   *
+   * Use this for existing projects that need Legacy Auth for backwards compatibility.
+   * Both Legacy Auth and BetterAuth (IAM) can run in parallel.
+   *
+   * ## Migration Path
+   *
+   * 1. **Existing projects**: Use the 3-parameter signature, run Legacy + IAM in parallel
+   * 2. **Monitor**: Use `betterAuthMigrationStatus` query to track user migration
+   * 3. **Disable Legacy**: Set `auth.legacyEndpoints.enabled: false` after all users migrated
+   * 4. **New projects**: Use the single-parameter signature with IAM only
+   *
+   * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
    */
-  static forRoot(AuthService: any, AuthModule: any, options: Partial<IServerOptions>): DynamicModule {
+  static forRoot(options: Partial<IServerOptions>): DynamicModule;
+  /**
+   * @deprecated Use the single-parameter signature `CoreModule.forRoot(envConfig)` for new projects.
+   * This 3-parameter signature is for existing projects during migration to IAM.
+   */
+  static forRoot(AuthService: any, AuthModule: any, options: Partial<IServerOptions>): DynamicModule;
+  static forRoot(
+    authServiceOrOptions: any,
+    authModuleOrUndefined?: any,
+    optionsOrUndefined?: Partial<IServerOptions>,
+  ): DynamicModule {
+    // Detect which signature was used
+    const isIamOnlyMode = authModuleOrUndefined === undefined && optionsOrUndefined === undefined;
+    const AuthService = isIamOnlyMode ? null : authServiceOrOptions;
+    const AuthModule = isIamOnlyMode ? null : authModuleOrUndefined;
+    const options: Partial<IServerOptions> = isIamOnlyMode ? authServiceOrOptions : optionsOrUndefined;
+
     // Process config
     let cors = {};
     if (options?.cookies) {
@@ -78,73 +135,17 @@ export class CoreModule implements NestModule {
         origin: true,
       };
     }
+
+    // Build GraphQL driver configuration based on auth mode
+    const graphQlDriverConfig = isIamOnlyMode
+      ? this.buildIamOnlyGraphQlDriver(cors, options)
+      : this.buildLegacyGraphQlDriver(AuthService, AuthModule, cors, options);
+
     const config: IServerOptions = merge(
       {
         env: 'develop',
         graphQl: {
-          driver: {
-            imports: [AuthModule],
-            inject: [AuthService],
-            useFactory: async (authService: any) =>
-              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;
-                        if (config.graphQl.enableSubscriptionAuth) {
-                          // get authToken from authorization header
-                          const headers = this.getHeaderFromArray(extra.request?.rawHeaders);
-                          const authToken: string =
-                            connectionParams?.Authorization?.split(' ')[1] ?? headers.Authorization?.split(' ')[1];
-                          if (authToken) {
-                            // verify authToken/getJwtPayLoad
-                            const payload = authService.decodeJwt(authToken);
-                            const user = await authService.validateUser(payload);
-                            if (!user) {
-                              throw new UnauthorizedException('No user found for token');
-                            }
-                            // the user/jwtPayload object found will be available as context.currentUser/jwtPayload in your GraphQL resolvers
-                            extra.user = user;
-                            extra.headers = connectionParams ?? headers;
-                            return extra;
-                          }
-
-                          throw new UnauthorizedException('Missing authentication token');
-                        }
-                      },
-                    },
-                    'subscriptions-transport-ws': {
-                      onConnect: async (connectionParams) => {
-                        if (config.graphQl.enableSubscriptionAuth) {
-                          // get authToken from authorization header
-                          const authToken: string = connectionParams?.Authorization?.split(' ')[1];
-
-                          if (authToken) {
-                            // verify authToken/getJwtPayLoad
-                            const payload = authService.decodeJwt(authToken);
-                            const user = await authService.validateUser(payload);
-                            if (!user) {
-                              throw new UnauthorizedException('No user found for token');
-                            }
-                            // the user/jwtPayload object found will be available as context.currentUser/jwtPayload in your GraphQL resolvers
-                            return { headers: connectionParams, user };
-                          }
-
-                          throw new UnauthorizedException('Missing authentication token');
-                        }
-                      },
-                    },
-                  },
-                },
-                options?.graphQl?.driver,
-              ),
-          },
+          driver: graphQlDriverConfig,
           enableSubscriptionAuth: true,
         },
         mongoose: {
@@ -229,16 +230,19 @@ export class CoreModule implements NestModule {
       imports.push(CoreHealthCheckModule);
     }
 
-    // Add BetterAuthModule only if autoRegister is explicitly true
-    // By default (autoRegister: false), projects integrate via an extended module in their project
-    if (config.betterAuth?.enabled !== false && config.betterAuth?.autoRegister === true) {
-      imports.push(
-        BetterAuthModule.forRoot({
-          config: config.betterAuth || {},
-          // Pass JWT secrets for backwards compatibility fallback
-          fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
-        }),
-      );
+    // Add BetterAuthModule based on mode
+    // IAM-only mode: Always register BetterAuthModule (required for subscription auth)
+    // Legacy mode: Only register if autoRegister is explicitly true
+    if (config.betterAuth?.enabled !== false) {
+      if (isIamOnlyMode || config.betterAuth?.autoRegister === true) {
+        imports.push(
+          BetterAuthModule.forRoot({
+            config: config.betterAuth || {},
+            // Pass JWT secrets for backwards compatibility fallback
+            fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
+          }),
+        );
+      }
     }
 
     // Set exports
@@ -255,4 +259,182 @@ export class CoreModule implements NestModule {
       providers,
     };
   }
+
+  // =============================================================================
+  // GraphQL Driver Configuration Helpers
+  // =============================================================================
+
+  /**
+   * Build GraphQL driver configuration for IAM-only mode
+   *
+   * Uses BetterAuthService for subscription authentication via JWT tokens.
+   * This is the recommended mode for new projects.
+   */
+  private static buildIamOnlyGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
+    return {
+      imports: [BetterAuthModule],
+      inject: [BetterAuthService, BetterAuthUserMapper],
+      useFactory: async (betterAuthService: BetterAuthService, userMapper: BetterAuthUserMapper) =>
+        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) {
+                    // Get headers from raw headers or connection params
+                    const headers = CoreModule.getHeaderFromArray(extra.request?.rawHeaders);
+                    const authToken: string =
+                      connectionParams?.Authorization?.split(' ')[1] ?? headers.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      // Validate via BetterAuth session
+                      const { session, user: sessionUser } = await betterAuthService.getSession({
+                        headers: { authorization: `Bearer ${authToken}` },
+                      });
+
+                      if (!session || !sessionUser) {
+                        throw new UnauthorizedException('Invalid or expired session');
+                      }
+
+                      // Map to full user with roles
+                      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 authToken: string = connectionParams?.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      // Validate via BetterAuth session
+                      const { session, user: sessionUser } = await betterAuthService.getSession({
+                        headers: { authorization: `Bearer ${authToken}` },
+                      });
+
+                      if (!session || !sessionUser) {
+                        throw new UnauthorizedException('Invalid or expired session');
+                      }
+
+                      // Map to full user with roles
+                      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
+   *
+   * Uses the provided AuthService for subscription authentication via JWT tokens.
+   * This is for existing projects that need backwards compatibility.
+   *
+   * @deprecated Use IAM-only mode (single-parameter forRoot) for new projects
+   */
+  private static buildLegacyGraphQlDriver(
+    AuthService: any,
+    AuthModule: any,
+    cors: object,
+    options: Partial<IServerOptions>,
+  ) {
+    // Store config reference for use in callbacks
+    const enableSubscriptionAuth = options?.graphQl?.enableSubscriptionAuth ?? true;
+
+    return {
+      imports: [AuthModule],
+      inject: [AuthService],
+      useFactory: async (authService: any) =>
+        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;
+                  if (enableSubscriptionAuth) {
+                    // get authToken from authorization header
+                    const headers = CoreModule.getHeaderFromArray(extra.request?.rawHeaders);
+                    const authToken: string =
+                      connectionParams?.Authorization?.split(' ')[1] ?? headers.Authorization?.split(' ')[1];
+                    if (authToken) {
+                      // verify authToken/getJwtPayLoad
+                      const payload = authService.decodeJwt(authToken);
+                      const user = await authService.validateUser(payload);
+                      if (!user) {
+                        throw new UnauthorizedException('No user found for token');
+                      }
+                      // the user/jwtPayload object found will be available as context.currentUser/jwtPayload in your GraphQL resolvers
+                      extra.user = user;
+                      extra.headers = connectionParams ?? headers;
+                      return extra;
+                    }
+
+                    throw new UnauthorizedException('Missing authentication token');
+                  }
+                },
+              },
+              'subscriptions-transport-ws': {
+                onConnect: async (connectionParams) => {
+                  if (enableSubscriptionAuth) {
+                    // get authToken from authorization header
+                    const authToken: string = connectionParams?.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      // verify authToken/getJwtPayLoad
+                      const payload = authService.decodeJwt(authToken);
+                      const user = await authService.validateUser(payload);
+                      if (!user) {
+                        throw new UnauthorizedException('No user found for token');
+                      }
+                      // the user/jwtPayload object found will be available as context.currentUser/jwtPayload in your GraphQL resolvers
+                      return { headers: connectionParams, user };
+                    }
+
+                    throw new UnauthorizedException('Missing authentication token');
+                  }
+                },
+              },
+            },
+          },
+          options?.graphQl?.driver,
+        ),
+    };
+  }
 }

package/src/index.ts

@@ -108,15 +108,19 @@ export * from './core/modules/auth/core-auth.resolver';
 export * from './core/modules/auth/exceptions/expired-refresh-token.exception';
 export * from './core/modules/auth/exceptions/expired-token.exception';
 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';
 export * from './core/modules/auth/inputs/core-auth-sign-in.input';
 export * from './core/modules/auth/inputs/core-auth-sign-up.input';
+export * from './core/modules/auth/interfaces/auth-provider.interface';
 export * from './core/modules/auth/interfaces/core-auth-user.interface';
 export * from './core/modules/auth/interfaces/core-token-data.interface';
 export * from './core/modules/auth/interfaces/jwt-payload.interface';
 export * from './core/modules/auth/services/core-auth-user.service';
 export * from './core/modules/auth/services/core-auth.service';
+export * from './core/modules/auth/services/legacy-auth-rate-limiter.service';
 export * from './core/modules/auth/strategies/jwt-refresh.strategy';
 export * from './core/modules/auth/strategies/jwt.strategy';
 export * from './core/modules/auth/tokens.decorator';
@@ -162,6 +166,7 @@ export * from './core/modules/user/core-user.model';
 export * from './core/modules/user/core-user.service';
 export * from './core/modules/user/inputs/core-user-create.input';
 export * from './core/modules/user/inputs/core-user.input';
+export * from './core/modules/user/interfaces/core-user-service-options.interface';
 
 // =====================================================================================================================
 // Tests

package/src/server/modules/auth/auth.resolver.ts

@@ -30,6 +30,8 @@ export class AuthResolver extends CoreAuthResolver {
 
   /**
    * SignIn for User
+   *
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => Auth, { description: 'Sign in and get JWT token' })
   @Roles(RoleEnum.S_EVERYONE)
@@ -38,6 +40,8 @@ export class AuthResolver extends CoreAuthResolver {
     @Context() ctx: { res: ResponseType },
     @Args('input') input: AuthSignInInput,
   ): Promise<Auth> {
+    // Check if legacy endpoints are enabled before proceeding
+    this.checkLegacyGraphQLEnabled('signIn');
     const result = await this.authService.signIn(input, {
       ...serviceOptions,
       inputType: AuthSignInInput,
@@ -47,6 +51,8 @@ export class AuthResolver extends CoreAuthResolver {
 
   /**
    * Sign up for user
+   *
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => Auth, {
     description: 'Sign up user and get JWT token',
@@ -57,6 +63,8 @@ export class AuthResolver extends CoreAuthResolver {
     @Context() ctx: { res: ResponseType },
     @Args('input') input: AuthSignUpInput,
   ): Promise<Auth> {
+    // Check if legacy endpoints are enabled before proceeding
+    this.checkLegacyGraphQLEnabled('signUp');
     const result = await this.authService.signUp(input, serviceOptions);
     return this.processCookies(ctx, result);
   }

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

@@ -7,6 +7,7 @@ import { RoleEnum } from '../../../core/common/enums/role.enum';
 import { AuthGuardStrategy } from '../../../core/modules/auth/auth-guard-strategy.enum';
 import { AuthGuard } from '../../../core/modules/auth/guards/auth.guard';
 import { BetterAuthAuthModel } from '../../../core/modules/better-auth/better-auth-auth.model';
+import { BetterAuthMigrationStatusModel } from '../../../core/modules/better-auth/better-auth-migration-status.model';
 import {
   BetterAuth2FASetupModel,
   BetterAuthFeaturesModel,
@@ -78,6 +79,14 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
     return super.betterAuthFeatures();
   }
 
+  @Query(() => BetterAuthMigrationStatusModel, {
+    description: 'Get migration status from Legacy Auth to Better-Auth (IAM) - Admin only',
+  })
+  @Roles(RoleEnum.ADMIN)
+  override async betterAuthMigrationStatus(): Promise<BetterAuthMigrationStatusModel> {
+    return super.betterAuthMigrationStatus();
+  }
+
   @Query(() => [BetterAuthPasskeyModel], {
     description: 'List passkeys for the current user',
     nullable: true,

package/src/server/modules/user/user.service.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable, UnauthorizedException, UnprocessableEntityException } from '@nestjs/common';
+import { Inject, Injectable, Optional, UnauthorizedException, UnprocessableEntityException } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 import fs = require('fs');
 import { PubSub } from 'graphql-subscriptions';
@@ -9,6 +9,7 @@ import { ServiceOptions } from '../../../core/common/interfaces/service-options.
 import { ConfigService } from '../../../core/common/services/config.service';
 import { EmailService } from '../../../core/common/services/email.service';
 import { CoreModelConstructor } from '../../../core/common/types/core-model-constructor.type';
+import { BetterAuthUserMapper } from '../../../core/modules/better-auth/better-auth-user.mapper';
 import { CoreUserService } from '../../../core/modules/user/core-user.service';
 import { UserCreateInput } from './inputs/user-create.input';
 import { UserInput } from './inputs/user.input';
@@ -32,8 +33,9 @@ export class UserService extends CoreUserService<User, UserInput, UserCreateInpu
     @Inject('USER_CLASS') protected override readonly mainModelConstructor: CoreModelConstructor<User>,
     @InjectModel('User') protected override readonly mainDbModel: Model<UserDocument>,
     @Inject('PUB_SUB') protected readonly pubSub: PubSub,
+    @Optional() private readonly betterAuthUserMapper?: BetterAuthUserMapper,
   ) {
-    super(configService, emailService, mainDbModel, mainModelConstructor);
+    super(configService, emailService, mainDbModel, mainModelConstructor, { betterAuthUserMapper });
   }
 
   // ===================================================================================================================