@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/services/auth-challenge-helper.service.ts

@@ -1,825 +0,0 @@
-import { Repository } from 'typeorm';
-import { BaseMFADevice } from '../entities';
-import { AuthResponseDTO } from '../dto/auth-response.dto';
-import { AuthChallenge } from '../dto/auth-challenge.dto';
-import { SendVerificationEmailDTO } from '../dto/verify-email.dto';
-import { SendVerificationSMSDTO } from '../dto/verify-phone.dto';
-import { IUser, IMFADevice } from '../interfaces/entities.interface';
-import { ChallengeService } from './challenge.service';
-import { JwtService } from './jwt.service';
-import { SessionService } from './session.service';
-import { EmailVerificationService } from './email-verification.service';
-import { PhoneVerificationService } from './phone-verification.service';
-import { ClientInfoService } from './client-info.service';
-import { NAuthConfig } from '../interfaces/config.interface';
-import { NAuthLogger } from '../utils/nauth-logger';
-import { NAuthException } from '../exceptions/nauth.exception';
-import { AuthErrorCode } from '../enums/error-codes.enum';
-import { MFAMethod, MFADeviceMethod, MFAVerificationMethod, MFADeviceMethods } from '../enums/mfa-method.enum';
-import { AuthFlowStateMachineService } from './auth-flow-state-machine.service';
-import { AuthFlowContextBuilder } from './auth-flow-context-builder.service';
-import { AuthFlowState, AuthFlowContext } from './auth-flow-state-machine.types';
-
-/**
- * Helper service for challenge-response authentication flows
- *
- * This service determines if a user needs to complete challenges
- * before full authentication can be granted, and generates appropriate
- * responses including MFA challenges.
- *
- * @example
- * ```typescript
- * const response = await challengeHelper.determineAuthResponse(
- *   user,
- *   'login',
- *   { ipAddress: '1.2.3.4' }
- * );
- * ```
- */
-export class AuthChallengeHelperService {
-  constructor(
-    private readonly challengeService: ChallengeService,
-    private readonly jwtService: JwtService,
-    private readonly sessionService: SessionService,
-    private readonly mfaDeviceRepository: Repository<BaseMFADevice>,
-    private readonly logger: NAuthLogger,
-    private readonly stateMachine: AuthFlowStateMachineService,
-    private readonly contextBuilder: AuthFlowContextBuilder,
-    private readonly clientInfoService: ClientInfoService,
-    private readonly emailVerificationService?: EmailVerificationService,
-    private readonly phoneVerificationService?: PhoneVerificationService, // Optional - only available when SMS provider is configured
-  ) {}
-
-  // ============================================================================
-  // OLD METHODS DELETED - Replaced by state machine
-  // ============================================================================
-  // determinePendingChallenges() - DELETED (replaced by state machine)
-  // isMFASetupRequired() - DELETED (replaced by state machine)
-  // checkMFARequirement() - DELETED (replaced by state machine)
-  // All challenge determination is now handled by determineAuthResponse() using state machine
-
-  /**
-   * Create challenge response for authentication
-   *
-   * Generates a challenge session and returns challenge details to client.
-   * Sends verification codes when challenges are created to ensure sequential flow.
-   *
-   * @param user - User who needs to complete challenges
-   * @param challengeName - Type of challenge
-   * @param config - Auth configuration
-   * @param authMethod - Authentication method ('password' or 'social')
-   * @param authProvider - Provider name for social auth (e.g., 'google', 'facebook')
-   * @returns Challenge response DTO
-   *
-   * @example
-   * ```typescript
-   * const response = await challengeHelper.createChallengeResponse(
-   *   user,
-   *   AuthChallenge.VERIFY_EMAIL,
-   *   config,
-   *   'social',
-   *   'google'
-   * );
-   * ```
-   */
-  async createChallengeResponse(
-    user: IUser,
-    challengeName: AuthChallenge,
-    config: NAuthConfig,
-    authMethod: 'password' | 'social' = 'password',
-    authProvider?: string,
-    skipAutoSend?: boolean,
-  ): Promise<AuthResponseDTO> {
-    // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-    // Note: ClientInfoService is used transparently by ChallengeService and AuditService
-
-    // ============================================================================
-    // STEP 1: Create challenge session FIRST (before sending codes)
-    // ============================================================================
-    // This ensures the session exists before any verification codes are sent.
-    // Creating the session first is critical for proper audit trail and session tracking.
-    this.logger?.debug?.(
-      `Creating challenge with authMethod=${authMethod}, authProvider=${authProvider || 'none'} for user ${user.sub}`,
-    );
-
-    // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-    const challengeSession = await this.challengeService.createChallengeSession(user, challengeName, {
-      email: user.email,
-      phone: user.phone,
-      authMethod, // Store auth method for challenge completion flow
-      authProvider, // Store provider for social auth (e.g., 'google', 'facebook')
-    });
-
-    // ============================================================================
-    // STEP 2: Send verification codes AFTER session is created
-    // ============================================================================
-    // This ensures codes are sent at the right time:
-    // - Email code sent when VERIFY_EMAIL challenge is created
-    // - Phone code sent when VERIFY_PHONE challenge is created (after email is verified)
-    // This prevents sending both codes at once, avoiding user confusion.
-    // Challenges are sequential: first VERIFY_EMAIL, then VERIFY_PHONE
-    if (challengeName === AuthChallenge.VERIFY_EMAIL && this.emailVerificationService) {
-      this.logger?.log?.(`📧 Sending verification email to: ${user.email}`);
-      // Fire and forget - don't block challenge response
-      const emailDto = Object.assign(new SendVerificationEmailDTO(), {
-        sub: user.sub,
-        baseUrl: undefined,
-        challengeSessionId: challengeSession.id, // Link verification token to this challenge session
-      });
-      this.emailVerificationService
-        .sendVerificationEmail(emailDto)
-        .then(() => {
-          this.logger?.log?.(`Verification email sent successfully to: ${user.email}`);
-        })
-        .catch((error: unknown) => {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.error?.(`Failed to send verification email to ${user.email}: ${errorMessage}`);
-        });
-    }
-
-    // Skip auto-send if SMS was already sent (e.g., during phone collection)
-    if (!skipAutoSend && challengeName === AuthChallenge.VERIFY_PHONE && this.phoneVerificationService && user.phone) {
-      this.logger?.log?.(`Sending verification SMS to: ${user.phone}`);
-      // Fire and forget - don't block challenge response
-      const smsDto = Object.assign(new SendVerificationSMSDTO(), {
-        sub: user.sub,
-        challengeSessionId: challengeSession.id, // Link verification token to this challenge session
-      });
-      this.phoneVerificationService
-        .sendVerificationSMS(smsDto)
-        .then(() => {
-          this.logger?.log?.(`Verification SMS sent successfully to: ${user.phone}`);
-        })
-        .catch((error: unknown) => {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.error?.(`Failed to send verification SMS to ${user.phone}: ${errorMessage}`);
-        });
-    }
-
-    // ============================================================================
-    // STEP 3: Send MFA challenge code for MFA_REQUIRED (if SMS is preferred method)
-    // ============================================================================
-    // When user logs in and MFA verification is required, automatically send SMS code
-    // if SMS is their preferred MFA method. This provides better UX by not requiring
-    // a separate API call to trigger code sending.
-    //
-    // Note: MFA_REQUIRED challenges are handled by createMFAChallengeResponse()
-    // which includes auto-send SMS logic
-
-    // Build challenge parameters
-    // Note: Type is Record<string, unknown> to allow arrays (e.g., allowedMethods for MFA)
-    const challengeParameters: Record<string, unknown> = {};
-
-    switch (challengeName) {
-      case AuthChallenge.VERIFY_EMAIL:
-        challengeParameters.email = user.email;
-        challengeParameters.codeDeliveryDestination = this.challengeService.maskEmail(user.email);
-        break;
-
-      case AuthChallenge.VERIFY_PHONE:
-        challengeParameters.phone = user.phone || undefined;
-        challengeParameters.codeDeliveryDestination = user.phone
-          ? this.challengeService.maskPhone(user.phone)
-          : undefined;
-        // If no phone, indicate user must provide it first
-        if (!user.phone) {
-          challengeParameters.requiresPhoneCollection = 'true';
-          challengeParameters.instructions = 'You must add a phone number and verify it to continue';
-        }
-        break;
-
-      case AuthChallenge.MFA_REQUIRED:
-        challengeParameters.instructions = 'Multi-factor authentication is required';
-        // Include masked phone if SMS is preferred method
-        if (user.preferredMfaMethod === 'sms' && user.phone) {
-          challengeParameters.codeDeliveryDestination = this.challengeService.maskPhone(user.phone);
-        }
-        // Include masked email if Email is preferred method
-        if (user.preferredMfaMethod === 'email' && user.email) {
-          challengeParameters.codeDeliveryDestination = this.challengeService.maskEmail(user.email);
-        }
-        break;
-
-      case AuthChallenge.MFA_SETUP_REQUIRED: {
-        const allowedMethods = config.mfa?.allowedMethods || [...MFADeviceMethods];
-        challengeParameters.allowedMethods = allowedMethods;
-        challengeParameters.instructions = 'Multi-factor authentication setup is required before you can login';
-        break;
-      }
-
-      case AuthChallenge.FORCE_CHANGE_PASSWORD:
-        challengeParameters.instructions = 'You must change your password before continuing';
-        break;
-    }
-
-    const response: AuthResponseDTO = {
-      challengeName,
-      session: challengeSession.sessionToken,
-      challengeParameters,
-      userSub: user.sub,
-    };
-
-    return response;
-  }
-
-  // ============================================================================
-  // MFA Challenge Support
-  // ============================================================================
-  // checkMFARequirement() - DELETED (replaced by state machine)
-  // All MFA requirement checking is now handled by state machine in determineAuthResponse()
-
-  /**
-   * Create MFA setup challenge response
-   *
-   * Generates challenge session for MFA setup requirement.
-   * User must set up MFA before being allowed to login.
-   *
-   * @param user - User requiring MFA setup
-   * @param config - Auth configuration
-   * @param authMethod - Authentication method ('password' or 'social')
-   * @param authProvider - Provider name for social auth (e.g., 'google', 'facebook')
-   * @returns MFA setup challenge response
-   *
-   * @example
-   * ```typescript
-   * const response = await challengeHelper.createMFASetupChallengeResponse(
-   *   user,
-   *   config,
-   *   'social',
-   *   'google'
-   * );
-   * // Returns: { challengeName: 'MFA_SETUP_REQUIRED', session: '...', challengeParameters: {...} }
-   * ```
-   */
-  async createMFASetupChallengeResponse(
-    user: IUser,
-    config: NAuthConfig,
-    authMethod: 'password' | 'social' = 'password',
-    authProvider?: string,
-  ): Promise<AuthResponseDTO> {
-    // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-    // Note: ClientInfoService is used transparently by ChallengeService and AuditService
-    this.logger?.log?.(`Creating MFA setup challenge for user: ${user.sub}`);
-
-    const allowedMethods = config.mfa?.allowedMethods || [...MFADeviceMethods];
-
-    // Create challenge session with auth context
-    this.logger?.debug?.(
-      `Creating MFA setup challenge with authMethod=${authMethod}, authProvider=${authProvider || 'none'} for user ${user.sub}`,
-    );
-
-    // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-    const challengeSession = await this.challengeService.createChallengeSession(
-      user,
-      AuthChallenge.MFA_SETUP_REQUIRED,
-      {
-        allowedMethods,
-        requiresSetup: true,
-        authMethod, // Store auth method for challenge completion flow
-        authProvider, // Store provider for social auth
-      },
-    );
-
-    this.logger?.log?.(`MFA setup challenge created for user: ${user.sub}`);
-
-    // Return challenge response
-    return {
-      challengeName: AuthChallenge.MFA_SETUP_REQUIRED,
-      session: challengeSession.sessionToken,
-      challengeParameters: {
-        allowedMethods,
-        instructions: 'Multi-factor authentication setup is required before you can login',
-      },
-      userSub: user.sub,
-    } as AuthResponseDTO;
-  }
-
-  /**
-   * Create MFA challenge response
-   *
-   * Generates challenge session for MFA verification.
-   * Returns available MFA methods and challenge parameters.
-   *
-   * @param user - User requiring MFA
-   * @returns MFA challenge response
-   * @remarks Client info (ipAddress, userAgent) is automatically extracted from ClientInfoService context
-   *
-   * @example
-   * ```typescript
-   * const response = await challengeHelper.createMFAChallengeResponse(
-   *   user,
-   *   '1.2.3.4',
-   *   'Mozilla/5.0...'
-   * );
-   * // Returns: { challengeName: 'MFA_REQUIRED', session: '...', challengeParameters: {...} }
-   * ```
-   */
-  async createMFAChallengeResponse(user: IUser): Promise<AuthResponseDTO> {
-    // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-    // Note: ClientInfoService is used transparently by ChallengeService and AuditService
-    this.logger?.log?.(`Creating MFA challenge for user: ${user.sub}`);
-
-    // Get user's active MFA devices
-    const devices = (await this.mfaDeviceRepository.find({
-      where: { userId: user.id, isActive: true },
-      order: { isPrimary: 'DESC', lastUsedAt: 'DESC' },
-    })) as unknown as IMFADevice[];
-
-    if (devices.length === 0) {
-      this.logger?.warn?.(`User has MFA enabled but no active devices: ${user.sub}`);
-      // User has MFA enabled but no devices - should not happen
-      // Allow login and let them set up MFA
-      throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'MFA enabled but no devices configured');
-    }
-
-    // Get available methods (device types only - no backup)
-    const deviceMethods = [...new Set(devices.map((d) => d.type))] as MFADeviceMethod[];
-
-    // Build full available methods list (including backup if available)
-    const availableMethods: MFAVerificationMethod[] = [...deviceMethods];
-    if (user.backupCodes && user.backupCodes.length > 0) {
-      availableMethods.push(MFAMethod.BACKUP);
-    }
-
-    // Debug logging for troubleshooting
-    this.logger?.debug?.(
-      `MFA challenge for user ${user.sub}: preferredMfaMethod=${user.preferredMfaMethod}, deviceMethods=[${deviceMethods.join(', ')}], devices=[${devices.map((d) => `${d.type}${d.isPrimary ? '(primary)' : ''}`).join(', ')}]`,
-    );
-
-    // Determine preferred method - prioritize user.preferredMfaMethod over primaryDevice
-    // This ensures that when user explicitly sets a preferred method, it's respected
-    let preferredMethod: string;
-
-    // Normalize preferred method to lowercase for comparison (database might store in different case)
-    const normalizedPreferredMethod = user.preferredMfaMethod?.toLowerCase();
-
-    // Check if user has a preferred method and it's available
-    if (
-      normalizedPreferredMethod &&
-      (normalizedPreferredMethod === MFAMethod.TOTP ||
-        normalizedPreferredMethod === MFAMethod.SMS ||
-        normalizedPreferredMethod === MFAMethod.EMAIL ||
-        normalizedPreferredMethod === MFAMethod.PASSKEY) &&
-      deviceMethods.some((m) => m.toLowerCase() === normalizedPreferredMethod)
-    ) {
-      // User has explicitly set a preferred method and it's available
-      // Find the actual method from deviceMethods to ensure case consistency
-      preferredMethod =
-        deviceMethods.find((m) => m.toLowerCase() === normalizedPreferredMethod) || normalizedPreferredMethod;
-      this.logger?.debug?.(
-        `Using user preferred MFA method: ${preferredMethod} (from user.preferredMfaMethod: ${user.preferredMfaMethod})`,
-      );
-    } else {
-      // Fallback to primary device or first available method
-      const primaryDevice = devices.find((d) => d.isPrimary);
-      preferredMethod = primaryDevice?.type || deviceMethods[0];
-      this.logger?.debug?.(
-        `Using fallback MFA method: ${preferredMethod} (preferred: ${user.preferredMfaMethod}, available: ${deviceMethods.join(', ')})`,
-      );
-    }
-
-    // Get masked phone if SMS is available
-    let maskedPhone: string | undefined;
-    const smsDevice = devices.find((d) => d.type === MFAMethod.SMS && d.phoneNumber);
-    if (smsDevice?.phoneNumber) {
-      const digits = smsDevice.phoneNumber.replace(/\D/g, '');
-      maskedPhone = digits.length >= 4 ? `***-***-${digits.slice(-4)}` : smsDevice.phoneNumber;
-    }
-
-    // Get masked email if Email is available
-    let maskedEmail: string | undefined;
-    const emailDevice = devices.find((d) => d.type === MFAMethod.EMAIL && d.email);
-    const emailToMask = emailDevice?.email || user.email; // Fallback to user.email if device doesn't have it
-    if (emailToMask) {
-      // Mask email: show first char and domain (e.g., u***r@example.com)
-      const [localPart, domain] = emailToMask.split('@');
-      if (localPart && domain) {
-        const firstChar = localPart[0];
-        const lastChar = localPart[localPart.length - 1];
-        maskedEmail = localPart.length > 2 ? `${firstChar}***${lastChar}@${domain}` : `${firstChar}***@${domain}`;
-      } else {
-        maskedEmail = emailToMask;
-      }
-    }
-
-    // Create challenge session
-    // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-    // Store preferred method in metadata for resend endpoint to know which method to use
-    const challengeSession = await this.challengeService.createChallengeSession(user, AuthChallenge.MFA_REQUIRED, {
-      availableMethods,
-      preferredMethod,
-      maskedPhone,
-      maskedEmail,
-      method: preferredMethod, // Store method in metadata for resend endpoint
-    });
-
-    this.logger?.log?.(`MFA challenge created for user: ${user.sub}`);
-
-    // ============================================================================
-    // Auto-send SMS code if SMS is the preferred method
-    // ============================================================================
-    // Automatically send SMS code if:
-    // 1. SMS is user's preferred MFA method, OR
-    // 2. SMS is the ONLY MFA method they have setup
-    //
-    // This provides better UX by not requiring a separate API call to trigger code sending.
-    const smsIsPreferred = preferredMethod.toLowerCase() === 'sms';
-    const smsIsOnly = deviceMethods.length === 1 && deviceMethods[0].toLowerCase() === 'sms';
-
-    if ((smsIsPreferred || smsIsOnly) && this.phoneVerificationService && user.phone) {
-      this.logger?.log?.(
-        `Auto-sending MFA SMS code to user ${user.sub} (preferred=${smsIsPreferred}, only=${smsIsOnly})`,
-      );
-      // Fire and forget - don't block challenge response
-      // Use PhoneVerificationService which handles SMS sending, rate limits, and token storage
-      // skipAlreadyVerifiedCheck=true because phone is already verified but we need MFA code
-      const smsDto = Object.assign(new SendVerificationSMSDTO(), {
-        sub: user.sub,
-        skipAlreadyVerifiedCheck: true,
-        challengeSessionId: challengeSession.id, // Link MFA SMS code to this challenge session
-      });
-      this.phoneVerificationService
-        .sendVerificationSMS(smsDto)
-        .then(() => {
-          this.logger?.log?.(`MFA SMS code sent successfully to user ${user.sub}`);
-        })
-        .catch((error: unknown) => {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.error?.(`Failed to send MFA SMS code to user ${user.sub}: ${errorMessage}`);
-        });
-    } else {
-      this.logger?.debug?.(
-        `Skipped auto-send MFA SMS for user ${user.sub}: ` +
-          `phoneService=${!!this.phoneVerificationService}, ` +
-          `preferredMethod=${preferredMethod}, ` +
-          `smsIsPreferred=${smsIsPreferred}, ` +
-          `smsIsOnly=${smsIsOnly}, ` +
-          `deviceMethods=[${deviceMethods.join(', ')}], ` +
-          `phone=${!!user.phone}`,
-      );
-    }
-
-    // ============================================================================
-    // Auto-send Email code if Email is the preferred method
-    // ============================================================================
-    // Automatically send Email code if:
-    // 1. Email is user's preferred MFA method, OR
-    // 2. Email is the ONLY MFA method they have setup
-    //
-    // This provides better UX by not requiring a separate API call to trigger code sending.
-    const emailIsPreferred = preferredMethod.toLowerCase() === 'email';
-    const emailIsOnly = deviceMethods.length === 1 && deviceMethods[0].toLowerCase() === 'email';
-
-    if ((emailIsPreferred || emailIsOnly) && this.emailVerificationService && user.email) {
-      this.logger?.log?.(
-        `Auto-sending MFA Email code to user ${user.sub} (preferred=${emailIsPreferred}, only=${emailIsOnly})`,
-      );
-      // Fire and forget - don't block challenge response
-      // Use EmailVerificationService which handles email sending, rate limits, and token storage
-      // skipAlreadyVerifiedCheck=true because email is already verified but we need MFA code
-      const emailDto = Object.assign(new SendVerificationEmailDTO(), {
-        sub: user.sub,
-        baseUrl: undefined,
-        skipAlreadyVerifiedCheck: true,
-        challengeSessionId: challengeSession.id, // Link MFA email code to this challenge session
-      });
-      this.emailVerificationService
-        .sendVerificationEmail(emailDto)
-        .then(() => {
-          this.logger?.log?.(`MFA Email code sent successfully to user ${user.sub}`);
-        })
-        .catch((error: unknown) => {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.error?.(`Failed to send MFA Email code to user ${user.sub}: ${errorMessage}`);
-        });
-    } else {
-      this.logger?.debug?.(
-        `Skipped auto-send MFA Email for user ${user.sub}: ` +
-          `emailService=${!!this.emailVerificationService}, ` +
-          `preferredMethod=${preferredMethod}, ` +
-          `emailIsPreferred=${emailIsPreferred}, ` +
-          `emailIsOnly=${emailIsOnly}, ` +
-          `deviceMethods=[${deviceMethods.join(', ')}], ` +
-          `email=${!!user.email}`,
-      );
-    }
-
-    // Return challenge response
-    // Always include maskedEmail if email is preferred, even if undefined (frontend can use user.email)
-    const challengeParams: Record<string, unknown> = {
-      availableMethods,
-      preferredMethod: preferredMethod as MFADeviceMethod,
-    };
-    if (maskedPhone) {
-      challengeParams.maskedPhone = maskedPhone;
-    }
-    if (maskedEmail || preferredMethod.toLowerCase() === 'email') {
-      // Include maskedEmail if available, or if email is preferred (frontend will handle display)
-      challengeParams.maskedEmail = maskedEmail || user.email || '';
-    }
-
-    return {
-      challengeName: AuthChallenge.MFA_REQUIRED,
-      session: challengeSession.sessionToken,
-      challengeParameters: challengeParams,
-    } as AuthResponseDTO;
-  }
-
-  // ============================================================================
-  // Success Response
-  // ============================================================================
-
-  /**
-   * Create successful authentication response with tokens
-   *
-   * Generates tokens and session for fully authenticated user.
-   *
-   * @param user - Authenticated user
-   * @param deviceToken - Device token (optional)
-   * @param isTrusted - Whether device is trusted (optional)
-   * @param isSocialLogin - Whether this is a social login (optional)
-   * @param metadata - Response metadata (optional)
-   * @returns Auth response with tokens
-   *
-   * @example
-   * ```typescript
-   * const response = await challengeHelper.createSuccessResponse(
-   *   user,
-   *   'abc123',
-   *   true,
-   *   false
-   * );
-   * ```
-   */
-  async createSuccessResponse(
-    user: IUser,
-    deviceToken?: string,
-    isTrusted?: boolean,
-    _isSocialLogin = false, // Reserved for future use
-    _metadata?: {
-      // Reserved for future use
-      gracePeriodEndsAt?: Date;
-      riskScore?: number;
-      riskLevel?: 'low' | 'medium' | 'high';
-      blockedUntil?: Date;
-      reason?: string;
-    },
-  ): Promise<AuthResponseDTO> {
-    // Get client info from ClientInfoService (for deviceToken only - IP/userAgent come from context automatically)
-    const clientInfo = this.clientInfoService.get();
-    const finalDeviceToken = clientInfo.deviceToken || deviceToken;
-
-    // ============================================================================
-    // SECURITY: Defense-in-depth validation before token issuance
-    // ============================================================================
-    // Note: Challenge validation is now handled by state machine in determineAuthResponse
-    // This method is only called when state is AUTHENTICATED, so no additional check needed
-
-    // Generate token family for rotation tracking
-    const tokenFamily = this.jwtService.generateTokenFamily();
-
-    // Generate temporary tokens first (session creation requires token hashes)
-    // Note: deviceId not included in token - session.deviceId is source of truth
-    const tempTokens = await this.jwtService.generateTokenPair({
-      userId: user.sub, // Use sub in JWT payload (external identifier)
-      email: user.email,
-      sessionId: 'temp', // Temporary - will be regenerated with real sessionId
-      tokenFamily,
-    });
-
-    // Generate deviceId if not provided
-    let finalDeviceId = finalDeviceToken;
-    if (!finalDeviceId) {
-      const crypto = await import('crypto');
-      finalDeviceId = crypto.randomUUID();
-    }
-
-    // Create session
-    // Client info (ipAddress, ipCountry, ipCity, userAgent) automatically extracted from ClientInfoService
-    const session = await this.sessionService.createSession({
-      userId: user.id, // Use internal id for foreign key
-      accessTokenHash: this.jwtService.hashToken(tempTokens.accessToken),
-      refreshTokenHash: this.jwtService.hashToken(tempTokens.refreshToken),
-      tokenFamily,
-      deviceId: finalDeviceId,
-      expiresAt: this.sessionService.getSessionExpirationDate(),
-      authMethod: 'password', // Default to password for challenge flows (signup, verification completion)
-    });
-
-    // Now regenerate tokens with the actual sessionId
-    // Note: deviceId not included in token - session.deviceId is source of truth
-    const tokens = await this.jwtService.generateTokenPair({
-      userId: user.sub,
-      email: user.email,
-      sessionId: session.id.toString(),
-      tokenFamily,
-    });
-
-    // Update session with new token hashes
-    await this.sessionService.updateTokens(
-      session.id,
-      this.jwtService.hashToken(tokens.accessToken),
-      this.jwtService.hashToken(tokens.refreshToken),
-    );
-
-    // Decode tokens to get expiry times
-    const accessTokenValidation = await this.jwtService.validateAccessToken(tokens.accessToken);
-    const refreshTokenValidation = await this.jwtService.validateRefreshToken(tokens.refreshToken);
-
-    const response: AuthResponseDTO = {
-      accessToken: tokens.accessToken,
-      refreshToken: tokens.refreshToken,
-      accessTokenExpiresAt: accessTokenValidation.payload?.exp || 0,
-      refreshTokenExpiresAt: refreshTokenValidation.payload?.exp || 0,
-      trusted: isTrusted,
-      // Expose deviceToken so that:
-      // - In cookies mode, CookieTokenInterceptor can set the httpOnly nauth_device_token cookie
-      // - In JSON mode, mobile clients can store it securely and send via header
-      // NOTE: finalDeviceToken is a logical device identifier derived from:
-      // - clientInfo.deviceToken (existing trusted device), OR
-      // - deviceToken parameter passed from AuthService / state machine
-      deviceToken: finalDeviceToken,
-      user: {
-        sub: user.sub,
-        email: user.email,
-        firstName: user.firstName,
-        lastName: user.lastName,
-        phone: user.phone ?? undefined,
-        isEmailVerified: user.isEmailVerified,
-        isPhoneVerified: user.isPhoneVerified ?? undefined,
-        socialProviders: user.socialProviders ?? undefined,
-        hasPasswordHash: !!user.passwordHash,
-      },
-      userSub: user.sub,
-    };
-
-    return response;
-  }
-
-  /**
-   * Determine and create appropriate auth response
-   *
-   * Main entry point that decides whether to return challenges or tokens.
-   * Uses state machine to evaluate authentication flow state.
-   *
-   * @param params - Authentication parameters
-   * @param params.user - User attempting authentication
-   * @param params.config - Auth configuration
-   * @param params.deviceToken - Device token (optional)
-   * @param params.isSocialLogin - Whether this is a social login (OAuth) authentication (optional)
-   * @param params.skipMFAVerification - Skip MFA verification flag (optional)
-   * @param params.authProvider - Social auth provider name (optional)
-   * @returns Auth response (either challenge or success)
-   *
-   * @example
-   * ```typescript
-   * const response = await challengeHelper.determineAuthResponse({
-   *   user,
-   *   config,
-   *   deviceToken: 'abc123',
-   *   isSocialLogin: false
-   * });
-   * ```
-   */
-  async determineAuthResponse(params: {
-    user: IUser;
-    config: NAuthConfig;
-    deviceToken?: string;
-    isSocialLogin?: boolean;
-    skipMFAVerification?: boolean;
-    authProvider?: string;
-  }): Promise<AuthResponseDTO> {
-    const { user, config, deviceToken, isSocialLogin = false, skipMFAVerification = false, authProvider } = params;
-
-    this.logger?.debug?.(
-      `[ChallengeHelper] determineAuthResponse called for user ${user.sub} (isSocialLogin=${isSocialLogin}, skipMFA=${skipMFAVerification}, deviceToken=${deviceToken ? 'present' : 'none'})`,
-    );
-
-    // Build context with pre-computed values
-    const context = await this.contextBuilder.build({
-      user,
-      config,
-      authMethod: isSocialLogin ? 'social' : 'password',
-      authProvider,
-      deviceToken,
-      skipMFAVerification,
-    });
-
-    // Evaluate state using state machine
-    const state = await this.stateMachine.evaluateState(context);
-
-    // Get state definition
-    const stateDefinition = this.stateMachine.getStateDefinition(state);
-    if (!stateDefinition) {
-      this.logger?.error?.(`No state definition found for state: ${state}`, { state, userId: user.id });
-      throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'Invalid authentication state');
-    }
-
-    // Build metadata if available
-    const metadata = this.stateMachine.buildMetadata(state, context);
-
-    // Convert state to response
-    const response = await this.stateToResponse(state, stateDefinition, context, metadata);
-
-    this.logger?.debug?.(
-      `[ChallengeHelper] State ${state} → Challenge: ${response.challengeName || 'SUCCESS'} for user ${user.sub}`,
-    );
-
-    return response;
-  }
-
-  /**
-   * Convert state to authentication response
-   *
-   * Maps state to appropriate response (challenge or success).
-   * Merges state metadata into response.
-   *
-   * @param state - Authentication flow state
-   * @param stateDefinition - State definition
-   * @param context - Authentication flow context
-   * @param metadata - Response metadata (optional)
-   * @returns Authentication response
-   */
-  private async stateToResponse(
-    state: AuthFlowState,
-    stateDefinition: { challenge?: AuthChallenge },
-    context: AuthFlowContext,
-    metadata?: {
-      gracePeriodEndsAt?: Date;
-      riskScore?: number;
-      riskLevel?: 'low' | 'medium' | 'high';
-      blockedUntil?: Date;
-      reason?: string;
-    },
-  ): Promise<AuthResponseDTO> {
-    // Get client info from ClientInfoService
-    const clientInfo = this.clientInfoService.get();
-    const deviceToken = clientInfo.deviceToken || context.deviceToken;
-
-    const authMethod = context.authMethod || 'password';
-
-    // Handle challenge states
-    if (stateDefinition.challenge) {
-      // Handle MFA_SETUP_REQUIRED challenge specially
-      if (stateDefinition.challenge === AuthChallenge.MFA_SETUP_REQUIRED) {
-        return this.createMFASetupChallengeResponse(context.user, context.config, authMethod, context.authProvider);
-      }
-
-      // Handle MFA_REQUIRED challenge specially - needs preferred method logic
-      if (stateDefinition.challenge === AuthChallenge.MFA_REQUIRED) {
-        return this.createMFAChallengeResponse(context.user);
-      }
-
-      // Handle other challenges
-      return this.createChallengeResponse(
-        context.user,
-        stateDefinition.challenge,
-        context.config,
-        authMethod,
-        context.authProvider,
-      );
-    }
-
-    // Handle special states
-    if (state === AuthFlowState.GRACE_PERIOD_ACTIVE) {
-      // Grace period active - return success with metadata
-      const isTrusted = context.computed.isDeviceTrusted;
-      const response = await this.createSuccessResponse(
-        context.user,
-        deviceToken,
-        isTrusted,
-        context.authMethod === 'social',
-        metadata,
-      );
-      // Merge metadata
-      if (metadata?.gracePeriodEndsAt) {
-        (response as AuthResponseDTO & { gracePeriodEndsAt?: Date }).gracePeriodEndsAt = metadata.gracePeriodEndsAt;
-      }
-      if (metadata?.riskScore !== undefined) {
-        (response as AuthResponseDTO & { riskScore?: number }).riskScore = metadata.riskScore;
-      }
-      if (metadata?.riskLevel) {
-        (response as AuthResponseDTO & { riskLevel?: 'low' | 'medium' | 'high' }).riskLevel = metadata.riskLevel;
-      }
-      return response;
-    }
-
-    if (state === AuthFlowState.BLOCKED) {
-      // User is blocked - throw exception with metadata
-      const errorCode =
-        (context.config.mfa?.adaptive?.blockedSignIn?.errorCode as AuthErrorCode) ||
-        AuthErrorCode.SIGNIN_BLOCKED_HIGH_RISK;
-      const message =
-        metadata?.reason ||
-        context.config.mfa?.adaptive?.blockedSignIn?.message ||
-        'Sign-in blocked due to suspicious activity';
-      throw new NAuthException(errorCode, message, {
-        expiresAt: metadata?.blockedUntil,
-      });
-    }
-
-    // AUTHENTICATED state - return success
-    const isTrusted = context.computed.isDeviceTrusted;
-    return this.createSuccessResponse(context.user, deviceToken, isTrusted, context.authMethod === 'social', metadata);
-  }
-}