@lenne.tech/nest-server 11.6.2 → 11.7.1

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
    */

package/src/core/modules/auth/services/core-auth.service.ts

@@ -1,4 +1,11 @@
-import { BadRequestException, Injectable, UnauthorizedException } from '@nestjs/common';
+import {
+  BadRequestException,
+  Injectable,
+  Logger,
+  NotFoundException,
+  Optional,
+  UnauthorizedException,
+} from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 import bcrypt = require('bcrypt');
 import { randomUUID } from 'crypto';
@@ -8,6 +15,8 @@ import { getStringIds } from '../../../common/helpers/db.helper';
 import { prepareServiceOptions } from '../../../common/helpers/service.helper';
 import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
 import { ConfigService } from '../../../common/services/config.service';
+import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper';
+import { BetterAuthService } from '../../better-auth/better-auth.service';
 import { CoreAuthModel } from '../core-auth.model';
 import { CoreAuthSignInInput } from '../inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from '../inputs/core-auth-sign-up.input';
@@ -29,9 +38,23 @@ export interface GetResultOptions {
 
 /**
  * CoreAuthService to handle user authentication
+ *
+ * When Better-Auth (IAM) is enabled, this service delegates authentication to IAM
+ * while maintaining backwards compatibility by returning Legacy JWT format tokens.
+ *
+ * Migration strategy:
+ * - New users: Created directly in IAM with scrypt password hash
+ * - Existing Legacy users: Lazily migrated on first sign-in
+ *   (Legacy bcrypt password verified, then IAM account created with scrypt hash)
+ *
+ * @deprecated The signIn and signUp methods are deprecated when IAM is enabled.
+ * Use the IAM REST endpoints (/iam/sign-in/email, /iam/sign-up/email) directly
+ * for new implementations. Legacy endpoints remain for backwards compatibility.
  */
 @Injectable()
 export class CoreAuthService {
+  private readonly logger = new Logger(CoreAuthService.name);
+
   /**
    * Integrate services
    */
@@ -39,6 +62,8 @@ export class CoreAuthService {
     protected readonly userService: CoreAuthUserService,
     protected readonly jwtService: JwtService,
     protected readonly configService: ConfigService,
+    @Optional() protected readonly betterAuthService?: BetterAuthService,
+    @Optional() protected readonly betterAuthUserMapper?: BetterAuthUserMapper,
   ) {}
 
   /**
@@ -99,6 +124,14 @@ export class CoreAuthService {
 
   /**
    * User sign in via email
+   *
+   * When IAM is enabled, this method:
+   * 1. For migrated users (have iamId): Verifies password via IAM
+   * 2. For non-migrated users: Verifies via Legacy, then migrates to IAM
+   *
+   * Always returns Legacy JWT format for backwards compatibility.
+   *
+   * @deprecated When IAM is enabled, prefer using /iam/sign-in/email REST endpoint directly.
    */
   async signIn(input: CoreAuthSignInInput, serviceOptions?: ServiceOptions): Promise<CoreAuthModel> {
     // Check input
@@ -106,6 +139,9 @@ export class CoreAuthService {
       throw new BadRequestException('Missing input');
     }
 
+    // Check if user enumeration prevention is enabled
+    const preventUserEnumeration = this.configService.getFastButReadOnly('auth.preventUserEnumeration', false);
+
     // Prepare service options
     const serviceOptionsForUserService = prepareServiceOptions(serviceOptions, {
       // We need password, so we can't use prepare output handling and have to deactivate it
@@ -119,12 +155,47 @@ export class CoreAuthService {
     const { deviceDescription, deviceId, email, password } = input;
 
     // Get user
-    const user = await this.userService.getViaEmail(email, serviceOptionsForUserService);
+    let user: ICoreAuthUser;
+    try {
+      user = await this.userService.getViaEmail(email, serviceOptionsForUserService);
+    } catch (error) {
+      if (error instanceof NotFoundException) {
+        throw new UnauthorizedException(preventUserEnumeration ? 'Invalid credentials' : 'Unknown email');
+      }
+      throw error;
+    }
     if (!user) {
-      throw new UnauthorizedException('Unknown email');
+      throw new UnauthorizedException(preventUserEnumeration ? 'Invalid credentials' : 'Unknown email');
     }
-    if (!((await bcrypt.compare(password, user.password)) || (await bcrypt.compare(sha256(password), user.password)))) {
-      throw new UnauthorizedException('Wrong password');
+
+    // Determine if IAM delegation is available
+    const iamEnabled = this.isIamEnabled();
+
+    if (iamEnabled && user.iamId) {
+      // User is already migrated to IAM - verify via IAM
+      const iamVerified = await this.verifyPasswordViaIam(email, password);
+      if (!iamVerified) {
+        throw new UnauthorizedException(preventUserEnumeration ? 'Invalid credentials' : 'Wrong password');
+      }
+      this.logger.debug(`User ${email} authenticated via IAM (already migrated)`);
+    } else {
+      // Verify via Legacy (bcrypt)
+      // Check if user has a password (social login only users don't have one)
+      if (!user.password) {
+        throw new UnauthorizedException(
+          preventUserEnumeration ? 'Invalid credentials' : 'No password set for this account',
+        );
+      }
+      if (
+        !((await bcrypt.compare(password, user.password)) || (await bcrypt.compare(sha256(password), user.password)))
+      ) {
+        throw new UnauthorizedException(preventUserEnumeration ? 'Invalid credentials' : 'Wrong password');
+      }
+
+      // If IAM is enabled but user not migrated, migrate them now
+      if (iamEnabled && !user.iamId) {
+        await this.migrateUserToIam(user, email, password);
+      }
     }
 
     // Return tokens and user with currentUser set so securityCheck knows user is requesting own data
@@ -136,6 +207,13 @@ export class CoreAuthService {
 
   /**
    * Register a new user account
+   *
+   * When IAM is enabled, this method:
+   * 1. Creates the user in IAM first (with scrypt password hash)
+   * 2. Creates/links the Legacy user with iamId
+   * 3. Returns Legacy JWT format for backwards compatibility
+   *
+   * @deprecated When IAM is enabled, prefer using /iam/sign-up/email REST endpoint directly.
    */
   async signUp(input: CoreAuthSignUpInput, serviceOptions?: ServiceOptions): Promise<CoreAuthModel> {
     // Prepare service options
@@ -146,7 +224,19 @@ export class CoreAuthService {
 
     // Get and check user
     try {
-      const user = await this.userService.create(input, serviceOptionsForUserService);
+      // Determine if IAM delegation is available
+      const iamEnabled = this.isIamEnabled();
+
+      let user: ICoreAuthUser;
+
+      if (iamEnabled) {
+        // Create via IAM first, then create/link Legacy user
+        user = await this.createUserViaIam(input, serviceOptionsForUserService);
+      } else {
+        // Create via Legacy
+        user = await this.userService.create(input, serviceOptionsForUserService);
+      }
+
       if (!user) {
         throw new BadRequestException('Email address already in use');
       }
@@ -332,4 +422,153 @@ export class CoreAuthService {
     // Return new token
     return newRefreshToken;
   }
+
+  // ===================================================================================================================
+  // IAM Delegation Helper Methods
+  // ===================================================================================================================
+
+  /**
+   * Checks if IAM (Better-Auth) delegation is available and enabled
+   */
+  protected isIamEnabled(): boolean {
+    return !!(this.betterAuthService?.isEnabled() && this.betterAuthUserMapper);
+  }
+
+  /**
+   * Verifies password via IAM for already-migrated users
+   *
+   * @param email - User email
+   * @param password - Plain password to verify
+   * @returns true if password is valid, false otherwise
+   */
+  protected async verifyPasswordViaIam(email: string, password: string): Promise<boolean> {
+    if (!this.betterAuthService) {
+      return false;
+    }
+
+    const api = this.betterAuthService.getApi();
+    if (!api) {
+      return false;
+    }
+
+    try {
+      const response = await api.signInEmail({
+        body: { email, password },
+      });
+
+      // Check if response indicates successful authentication
+      return !!(response && 'user' in response && response.user);
+    } catch (error) {
+      this.logger.debug(
+        `IAM password verification failed for ${email}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Migrates a Legacy user to IAM
+   *
+   * This creates the IAM user and account with a scrypt password hash,
+   * then links the Legacy user via iamId.
+   *
+   * @param user - The Legacy user to migrate
+   * @param email - User email
+   * @param plainPassword - Plain password (needed to create scrypt hash)
+   */
+  protected async migrateUserToIam(user: ICoreAuthUser, email: string, plainPassword: string): Promise<void> {
+    if (!this.betterAuthUserMapper) {
+      return;
+    }
+
+    try {
+      // Create IAM account with the plain password (creates scrypt hash)
+      const migrated = await this.betterAuthUserMapper.migrateAccountToIam(email, plainPassword);
+
+      if (migrated) {
+        this.logger.log(`Migrated Legacy user ${email} to IAM`);
+
+        // Refresh user to get updated iamId
+        const updatedUser = await this.userService.getViaEmail(email, { force: true });
+        if (updatedUser?.iamId) {
+          // Update the user object in place so subsequent operations see the iamId
+          (user as any).iamId = updatedUser.iamId;
+        }
+      }
+    } catch (error) {
+      // Log but don't throw - migration failure shouldn't block login
+      this.logger.warn(
+        `Failed to migrate user ${email} to IAM: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
+  /**
+   * Creates a user via IAM and links to Legacy user
+   *
+   * @param input - Sign-up input data
+   * @param serviceOptions - Service options for user service
+   * @returns The created Legacy user (linked to IAM)
+   */
+  protected async createUserViaIam(input: CoreAuthSignUpInput, serviceOptions: ServiceOptions): Promise<ICoreAuthUser> {
+    if (!this.betterAuthService || !this.betterAuthUserMapper) {
+      throw new BadRequestException('IAM service not available');
+    }
+
+    const api = this.betterAuthService.getApi();
+    if (!api) {
+      throw new BadRequestException('IAM API not available');
+    }
+
+    try {
+      // Create user in IAM first
+      // Note: firstName and lastName are project-specific fields, may not exist on CoreAuthSignUpInput
+      const inputAny = input as any;
+      const name = [inputAny.firstName, inputAny.lastName].filter(Boolean).join(' ') || input.email.split('@')[0];
+      const response = await api.signUpEmail({
+        body: {
+          email: input.email,
+          name,
+          password: input.password,
+        },
+      });
+
+      if (!response || !('user' in response) || !response.user) {
+        throw new BadRequestException('Email address already in use');
+      }
+
+      // Link or create Legacy user with iamId
+      const iamUser = response.user as { email: string; id: string; name?: string };
+      const syncedUser = await this.betterAuthUserMapper.linkOrCreateUser(iamUser as any, {
+        firstName: inputAny.firstName,
+        lastName: inputAny.lastName,
+      });
+
+      if (!syncedUser) {
+        throw new BadRequestException('Failed to create user');
+      }
+
+      // Sync password to Legacy (enables backwards compatibility)
+      // Pass plain password so bcrypt hash can be created for Legacy Auth
+      await this.betterAuthUserMapper.syncPasswordToLegacy(iamUser.id, input.email, input.password);
+
+      this.logger.log(`Created user ${input.email} via IAM`);
+
+      // Get the full user from our database
+      const user = await this.userService.getViaEmail(input.email, serviceOptions);
+      if (!user) {
+        throw new BadRequestException('Failed to retrieve created user');
+      }
+
+      return user;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.debug(`IAM sign-up error for ${input.email}: ${errorMessage}`);
+
+      if (errorMessage.includes('already exists') || errorMessage.includes('already in use')) {
+        throw new BadRequestException('Email address already in use');
+      }
+      throw error;
+    }
+  }
 }