@lenne.tech/nest-server 11.7.0 → 11.7.2

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

@@ -5,9 +5,11 @@ import { PassportModule } from '@nestjs/passport';
 import { PubSub } from 'graphql-subscriptions';
 
 import { AuthGuardStrategy } from './auth-guard-strategy.enum';
+import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
 import { RolesGuard } from './guards/roles.guard';
 import { CoreAuthUserService } from './services/core-auth-user.service';
 import { CoreAuthService } from './services/core-auth.service';
+import { LegacyAuthRateLimiter } from './services/legacy-auth-rate-limiter.service';
 import { JwtRefreshStrategy } from './strategies/jwt-refresh.strategy';
 import { JwtStrategy } from './strategies/jwt.strategy';
 
@@ -68,6 +70,9 @@ export class CoreAuthModule {
         provide: JwtRefreshStrategy,
         useClass: options.jwtRefreshStrategy || JwtRefreshStrategy,
       },
+      // Rate limiting for Legacy Auth endpoints (disabled by default, configure via auth.rateLimit)
+      LegacyAuthRateLimiter,
+      LegacyAuthRateLimitGuard,
     ];
     if (Array.isArray(options?.providers)) {
       providers = imports.concat(options.providers);
@@ -75,7 +80,16 @@ export class CoreAuthModule {
 
     // Return CoreAuthModule
     return {
-      exports: [CoreAuthService, JwtModule, JwtStrategy, JwtRefreshStrategy, PassportModule, UserModule],
+      exports: [
+        CoreAuthService,
+        JwtModule,
+        JwtStrategy,
+        JwtRefreshStrategy,
+        LegacyAuthRateLimiter,
+        LegacyAuthRateLimitGuard,
+        PassportModule,
+        UserModule,
+      ],
       imports,
       module: CoreAuthModule,
       providers,

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

@@ -10,7 +10,9 @@ import { ServiceOptions } from '../../common/interfaces/service-options.interfac
 import { ConfigService } from '../../common/services/config.service';
 import { AuthGuardStrategy } from './auth-guard-strategy.enum';
 import { CoreAuthModel } from './core-auth.model';
+import { LegacyAuthDisabledException } from './exceptions/legacy-auth-disabled.exception';
 import { AuthGuard } from './guards/auth.guard';
+import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
 import { CoreAuthSignInInput } from './inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from './inputs/core-auth-sign-up.input';
 import { ICoreAuthUser } from './interfaces/core-auth-user.interface';
@@ -19,6 +21,26 @@ import { Tokens } from './tokens.decorator';
 
 /**
  * Authentication resolver for the sign in
+ *
+ * This resolver provides Legacy Auth endpoints via GraphQL.
+ * In a future version, BetterAuth (IAM) will become the default.
+ *
+ * ## Disabling Legacy Endpoints
+ *
+ * After all users have migrated to BetterAuth (IAM), these endpoints
+ * can be disabled via configuration:
+ *
+ * ```typescript
+ * auth: {
+ *   legacyEndpoints: {
+ *     enabled: false, // Disable all legacy endpoints
+ *     // or
+ *     graphql: false  // Disable only GraphQL endpoints
+ *   }
+ * }
+ * ```
+ *
+ * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
  */
 @Resolver(() => CoreAuthModel, { isAbstract: true })
 @Roles(RoleEnum.ADMIN)
@@ -31,67 +53,113 @@ export class CoreAuthResolver {
     protected readonly configService: ConfigService,
   ) {}
 
+  // ===========================================================================
+  // Helper - Legacy Endpoint Check
+  // ===========================================================================
+
+  /**
+   * Check if legacy GraphQL endpoints are enabled
+   *
+   * Throws LegacyAuthDisabledException if:
+   * - config.auth.legacyEndpoints.enabled is false
+   * - config.auth.legacyEndpoints.graphql is false
+   *
+   * @throws LegacyAuthDisabledException
+   */
+  protected checkLegacyGraphQLEnabled(endpointName: string): void {
+    const authConfig = this.configService.getFastButReadOnly('auth');
+    const legacyConfig = authConfig?.legacyEndpoints;
+
+    // Check if legacy endpoints are globally disabled
+    if (legacyConfig?.enabled === false) {
+      throw new LegacyAuthDisabledException(endpointName);
+    }
+
+    // Check if GraphQL endpoints specifically are disabled
+    if (legacyConfig?.graphql === false) {
+      throw new LegacyAuthDisabledException(endpointName);
+    }
+  }
+
   // ===========================================================================
   // Mutations
   // ===========================================================================
 
   /**
    * Logout user (from specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth signOut in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => Boolean, { description: 'Logout user (from specific device)' })
-  @Roles(RoleEnum.S_EVERYONE)
-  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(LegacyAuthRateLimitGuard)
   async logout(
     @CurrentUser() currentUser: ICoreAuthUser,
     @Context() ctx: { res: ResponseType },
     @Tokens('token') token: string,
     @Args('allDevices', { nullable: true }) allDevices?: boolean,
   ): Promise<boolean> {
+    this.checkLegacyGraphQLEnabled('logout');
     const result = await this.authService.logout(token, { allDevices, currentUser });
     return this.processCookies(ctx, result);
   }
 
   /**
    * Refresh token (for specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth session refresh in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => CoreAuthModel, { description: 'Refresh tokens (for specific device)' })
   @Roles(RoleEnum.S_EVERYONE)
-  @UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))
+  @UseGuards(LegacyAuthRateLimitGuard, AuthGuard(AuthGuardStrategy.JWT_REFRESH))
   async refreshToken(
     @CurrentUser() user: ICoreAuthUser,
     @Tokens('refreshToken') refreshToken: string,
     @Context() ctx: { res: ResponseType },
   ): Promise<CoreAuthModel> {
+    this.checkLegacyGraphQLEnabled('refreshToken');
     const result = await this.authService.refreshTokens(user, refreshToken);
     return this.processCookies(ctx, result);
   }
 
   /**
    * Sign in user via email and password (on specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth signIn in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => CoreAuthModel, {
     description: 'Sign in user via email and password and get JWT tokens (for specific device)',
   })
   @Roles(RoleEnum.S_EVERYONE)
+  @UseGuards(LegacyAuthRateLimitGuard)
   async signIn(
     @GraphQLServiceOptions({ gqlPath: 'signIn.user' }) serviceOptions: ServiceOptions,
     @Context() ctx: { res: ResponseType },
     @Args('input') input: CoreAuthSignInInput,
   ): Promise<CoreAuthModel> {
+    this.checkLegacyGraphQLEnabled('signIn');
     const result = await this.authService.signIn(input, serviceOptions);
     return this.processCookies(ctx, result);
   }
 
   /**
    * Register a new user account (on specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth signUp in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => CoreAuthModel, { description: 'Register a new user account (on specific device)' })
   @Roles(RoleEnum.S_EVERYONE)
+  @UseGuards(LegacyAuthRateLimitGuard)
   async signUp(
     @GraphQLServiceOptions({ gqlPath: 'signUp.user' }) serviceOptions: ServiceOptions,
     @Context() ctx: { res: ResponseType },
     @Args('input') input: CoreAuthSignUpInput,
   ): Promise<CoreAuthModel> {
+    this.checkLegacyGraphQLEnabled('signUp');
     const result = await this.authService.signUp(input, serviceOptions);
     return this.processCookies(ctx, result);
   }

package/src/core/modules/auth/exceptions/legacy-auth-disabled.exception.ts

@@ -0,0 +1,35 @@
+import { GoneException } from '@nestjs/common';
+
+/**
+ * Exception thrown when Legacy Auth endpoints are accessed but disabled
+ *
+ * This exception is thrown when:
+ * - config.auth.legacyEndpoints.enabled is false
+ * - config.auth.legacyEndpoints.graphql is false (for GraphQL endpoints)
+ * - config.auth.legacyEndpoints.rest is false (for REST endpoints)
+ *
+ * HTTP Status: 410 Gone
+ *
+ * This status code indicates that the resource is no longer available
+ * and will not be available again - appropriate for deprecated endpoints.
+ *
+ * @since 11.7.1
+ *
+ * @example
+ * ```typescript
+ * if (!this.isLegacyEndpointEnabled()) {
+ *   throw new LegacyAuthDisabledException();
+ * }
+ * ```
+ */
+export class LegacyAuthDisabledException extends GoneException {
+  constructor(endpoint?: string) {
+    super({
+      error: 'Legacy Auth Disabled',
+      message: endpoint
+        ? `Legacy Auth endpoint '${endpoint}' is disabled. Use BetterAuth (IAM) endpoints instead.`
+        : 'Legacy Auth endpoints are disabled. Use BetterAuth (IAM) endpoints instead.',
+      statusCode: 410,
+    });
+  }
+}

package/src/core/modules/auth/guards/legacy-auth-rate-limit.guard.ts

@@ -0,0 +1,109 @@
+import { CanActivate, ExecutionContext, HttpException, HttpStatus, Injectable } from '@nestjs/common';
+import { GqlExecutionContext } from '@nestjs/graphql';
+
+import { LegacyAuthRateLimiter } from '../services/legacy-auth-rate-limiter.service';
+
+/**
+ * Guard for rate limiting Legacy Auth endpoints
+ *
+ * This guard applies rate limiting to protect against brute-force attacks.
+ * It works with both REST and GraphQL endpoints.
+ *
+ * Rate limiting must be enabled via configuration:
+ * ```typescript
+ * auth: {
+ *   rateLimit: {
+ *     enabled: true,
+ *     max: 10,
+ *     windowSeconds: 60,
+ *   }
+ * }
+ * ```
+ *
+ * @since 11.7.x
+ */
+@Injectable()
+export class LegacyAuthRateLimitGuard implements CanActivate {
+  constructor(private readonly rateLimiter: LegacyAuthRateLimiter) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    // If rate limiting is disabled, always allow
+    if (!this.rateLimiter.isEnabled()) {
+      return true;
+    }
+
+    const { endpoint, ip } = this.extractRequestInfo(context);
+    const result = this.rateLimiter.check(ip, endpoint);
+
+    if (!result.allowed) {
+      throw new HttpException(
+        {
+          error: 'Too Many Requests',
+          message: this.rateLimiter.getMessage(),
+          remaining: result.remaining,
+          retryAfter: result.resetIn,
+          statusCode: HttpStatus.TOO_MANY_REQUESTS,
+        },
+        HttpStatus.TOO_MANY_REQUESTS,
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Extract IP and endpoint from the execution context
+   */
+  private extractRequestInfo(context: ExecutionContext): { endpoint: string; ip: string } {
+    const contextType = context.getType<'graphql' | 'http'>();
+
+    if (contextType === 'graphql') {
+      const gqlContext = GqlExecutionContext.create(context);
+      const info = gqlContext.getInfo();
+      const ctx = gqlContext.getContext();
+
+      // Get IP from request
+      const req = ctx.req;
+      const ip = this.getClientIp(req);
+
+      // Get endpoint from GraphQL field name
+      const endpoint = info?.fieldName || 'unknown';
+
+      return { endpoint, ip };
+    }
+
+    // HTTP context
+    const request = context.switchToHttp().getRequest();
+    const ip = this.getClientIp(request);
+
+    // Get endpoint from URL path
+    const url = request.url || request.path || '';
+    const endpoint = url.split('/').pop() || 'unknown';
+
+    return { endpoint, ip };
+  }
+
+  /**
+   * Get client IP from request, handling proxies
+   */
+  private getClientIp(request: any): string {
+    if (!request) {
+      return 'unknown';
+    }
+
+    // Check common proxy headers
+    const forwardedFor = request.headers?.['x-forwarded-for'];
+    if (forwardedFor) {
+      // Take the first IP in the chain (original client)
+      return forwardedFor.split(',')[0].trim();
+    }
+
+    const realIp = request.headers?.['x-real-ip'];
+    if (realIp) {
+      return realIp;
+    }
+
+    // Fall back to direct connection IP
+    return request.ip || request.connection?.remoteAddress || 'unknown';
+  }
+}

package/src/core/modules/auth/interfaces/auth-provider.interface.ts

@@ -0,0 +1,86 @@
+import { JwtPayload } from './jwt-payload.interface';
+
+/**
+ * Auth Provider Interface
+ *
+ * This interface defines the contract for authentication providers.
+ * Both Legacy Auth (CoreAuthService) and BetterAuth can implement this interface,
+ * allowing CoreModule to work with either system transparently.
+ *
+ * @since 11.8.0
+ * @see https://github.com/lenneTech/nest-server/blob/develop/src/core/modules/auth/interfaces/auth-provider.interface.ts
+ *
+ * ## Roadmap
+ *
+ * ### v11.x (Current)
+ * - Interface introduced for future flexibility
+ * - Legacy Auth (CoreAuthService) is the default implementation
+ * - BetterAuth can be used alongside Legacy Auth
+ *
+ * ### Future Version (Planned)
+ * - CoreModule.forRoot will use IAuthProvider instead of concrete AuthService
+ * - Legacy Auth becomes optional (must be explicitly enabled)
+ * - BetterAuth becomes the recommended default
+ *
+ * ## Implementation Example
+ *
+ * ```typescript
+ * @Injectable()
+ * export class BetterAuthProvider implements IAuthProvider {
+ *   constructor(private readonly betterAuthService: BetterAuthService) {}
+ *
+ *   decodeJwt(token: string): JwtPayload {
+ *     return this.betterAuthService.decodeJwt(token);
+ *   }
+ *
+ *   async validateUser(payload: JwtPayload): Promise<any> {
+ *     return this.betterAuthService.validateUser(payload);
+ *   }
+ *
+ *   signToken(user: any, expiresIn?: string): string {
+ *     return this.betterAuthService.signToken(user, expiresIn);
+ *   }
+ * }
+ * ```
+ */
+export interface IAuthProvider {
+  /**
+   * Decode a JWT token without verification
+   * Used for extracting payload information
+   *
+   * @param token - The JWT token to decode
+   * @returns The decoded JWT payload
+   */
+  decodeJwt(token: string): JwtPayload;
+
+  /**
+   * Sign a new JWT token for a user
+   *
+   * @param user - The user to create a token for
+   * @param expiresIn - Optional expiration time (e.g., '15m', '7d')
+   * @returns The signed JWT token
+   */
+  signToken(user: any, expiresIn?: string): string;
+
+  /**
+   * Validate a user based on JWT payload
+   * Called during authentication to verify the user exists and is valid
+   *
+   * @param payload - The JWT payload containing user information
+   * @returns The validated user object, or null if invalid
+   */
+  validateUser(payload: JwtPayload): Promise<any>;
+}
+
+/**
+ * Auth Provider Token for dependency injection
+ *
+ * Use this token to inject the auth provider in your services:
+ *
+ * ```typescript
+ * constructor(
+ *   @Inject(AUTH_PROVIDER) private readonly authProvider: IAuthProvider,
+ * ) {}
+ * ```
+ */
+export const AUTH_PROVIDER = 'AUTH_PROVIDER';

package/src/core/modules/auth/interfaces/core-auth-user.interface.ts

@@ -9,6 +9,12 @@ export interface ICoreAuthUser {
    */
   email: string;
 
+  /**
+   * Better-Auth (IAM) user ID for linking
+   * Set when user is migrated or created via IAM
+   */
+  iamId?: string;
+
   /**
    * ID of the user
    */