@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/services/auth.service.ts

@@ -1,3727 +0,0 @@
-import { Repository } from 'typeorm';
-import { IUser, ISession } from '../interfaces/entities.interface';
-import { BaseUser, BaseLoginAttempt, BaseMFADevice } from '../entities';
-import { PasswordService } from './password.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 { ChallengeService } from './challenge.service';
-import { AuthChallengeHelperService } from './auth-challenge-helper.service';
-import { AccountLockoutStorageService } from '../storage/account-lockout-storage.service';
-import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
-import { TrustedDeviceService } from './trusted-device.service';
-import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
-import { RiskFactor } from '../enums/risk-factor.enum';
-import { MFAService } from './mfa.service';
-import { ContextStorage } from '../utils/context-storage';
-import { SignupDTO } from '../dto/signup.dto';
-import { LoginDTO } from '../dto/login.dto';
-import { ChangePasswordRequestDTO } from '../dto/change-password-request.dto';
-import { ChangePasswordResponseDTO } from '../dto/change-password-response.dto';
-import { UpdateUserAttributesRequestDTO } from '../dto/update-user-attributes-request.dto';
-import { UserResponseDto } from '../dto/user-response.dto';
-import { AuthResponseDTO, TokenResponse } from '../dto/auth-response.dto';
-import { AuthChallenge } from '../dto/auth-challenge.dto';
-import {
-  ChallengeResponseData,
-  VerifyEmailResponse,
-  CollectPhoneResponse,
-  VerifyPhoneResponse,
-  VerifyMFACodeResponse,
-  VerifyMFAPasskeyResponse,
-  ForceChangePasswordResponse,
-  MFASetupResponse,
-} from '../dto/challenge-response.dto';
-import { RespondChallengeDTO } from '../dto/respond-challenge.dto';
-import { GetUserByEmailDTO } from '../dto/get-user-by-email.dto';
-import { GetUserByIdDTO } from '../dto/get-user-by-id.dto';
-import { LogoutDTO } from '../dto/logout.dto';
-import { LogoutResponseDTO } from '../dto/logout-response.dto';
-import { LogoutAllDTO } from '../dto/logout-all.dto';
-import { LogoutAllResponseDTO } from '../dto/logout-all-response.dto';
-import { RefreshTokenDTO } from '../dto/refresh-token.dto';
-import { ResendCodeDTO } from '../dto/resend-code.dto';
-import { ResendCodeResponseDTO } from '../dto/resend-code-response.dto';
-import { SetMustChangePasswordDTO } from '../dto/set-must-change-password.dto';
-import { SetMustChangePasswordResponseDTO } from '../dto/set-must-change-password-response.dto';
-import { TrustDeviceResponseDTO } from '../dto/trust-device-response.dto';
-import { IsTrustedDeviceResponseDTO } from '../dto/is-trusted-device-response.dto';
-import { VerifyEmailWithCodeDTO, ResendVerificationEmailDTO } from '../dto/verify-email.dto';
-import { SendVerificationSMSDTO, ResendVerificationSMSDTO } from '../dto/verify-phone.dto';
-import { VerifyPhoneWithCodeBySubDTO } from '../dto/verify-phone-by-sub.dto';
-
-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 } from '../enums/mfa-method.enum';
-import * as crypto from 'crypto';
-
-/**
- * Dummy Argon2 hash for constant-time response
- *
- * ⚠️ SECURITY CRITICAL: Used when user doesn't exist to prevent timing attacks
- * This dummy hash has same format/cost as real Argon2id hashes but verifies against nothing.
- *
- * Format: $argon2id$v=19$m=65536,t=3,p=4$salt$hash
- */
-const DUMMY_ARGON2_HASH =
-  '$argon2id$v=19$m=65536,t=3,p=4$RFVNTVlfU0FMVF9GT1JfVElNSU5H$dummyhashfordummyhashfordummyhash1234567890';
-
-export class AuthService {
-  constructor(
-    private readonly userRepository: Repository<BaseUser>,
-    private readonly loginAttemptRepository: Repository<BaseLoginAttempt>,
-    private readonly passwordService: PasswordService,
-    private readonly jwtService: JwtService,
-    private readonly sessionService: SessionService,
-    private readonly challengeService: ChallengeService,
-    private readonly challengeHelper: AuthChallengeHelperService,
-    private readonly emailVerificationService: EmailVerificationService,
-    private readonly clientInfoService: ClientInfoService,
-    private readonly accountLockoutStorage: AccountLockoutStorageService,
-    private readonly config: NAuthConfig,
-    private readonly logger: NAuthLogger,
-    private readonly auditService?: AuthAuditService, // Optional - audit trail service (enabled via config.auditLogs.enabled)
-    private readonly phoneVerificationService?: PhoneVerificationService, // Optional - only available when SMS provider is configured
-    private readonly mfaService?: MFAService, // Optional - available when MFA modules are imported
-    private readonly mfaDeviceRepository?: Repository<BaseMFADevice>, // Optional - available when MFA modules are imported
-    private readonly trustedDeviceService?: TrustedDeviceService, // Optional - only available when rememberDevices is not 'never'
-  ) {
-    this.logger?.log?.('AuthService initialized');
-  }
-
-  // ============================================================================
-  // User Signup
-  // ============================================================================
-
-  /**
-   * Register a new user.
-   *
-   * Checks for duplicates (email, username, phone), validates password, hashes it,
-   * creates the user, and returns tokens or a challenge if verification is required.
-   *
-   * @param dto - Signup payload
-   * @returns Auth response with tokens or a verification challenge
-   * @throws {NAuthException} If user exists, password is invalid, or signup is disabled
-   *
-   * @example
-   * ```typescript
-   * const result = await authService.signup({
-   *   email: 'user@example.com',
-   *   password: 'Password123!',
-   *   username: 'johndoe',
-   * });
-   * ```
-   */
-  async signup(dto: SignupDTO): Promise<AuthResponseDTO> {
-    // Get client info from request context (transparent!)
-    const clientInfo = this.clientInfoService.get();
-
-    this.logger?.log?.(`Signup attempt for email: ${dto.email}`);
-    this.logger?.debug?.(
-      `Signup details: { email: ${dto.email}, username: ${dto.username || 'none'}, ip: ${clientInfo.ipAddress} }`,
-    );
-
-    // Check if signup is enabled
-    if (this.config.signup?.enabled === false) {
-      this.logger?.warn?.(`Signup blocked - signup is disabled`);
-      throw new NAuthException(AuthErrorCode.SIGNUP_DISABLED, 'Signups are currently disabled');
-    }
-
-    // Check if user already exists (email and username)
-    this.logger?.debug?.(`Checking if user exists: ${dto.email}`);
-    const existingUserByEmail = await this.userRepository.findOne({
-      where: { email: dto.email },
-    });
-
-    if (existingUserByEmail) {
-      this.logger?.warn?.(`Signup failed - user already exists: ${dto.email}`);
-      throw new NAuthException(AuthErrorCode.EMAIL_EXISTS, 'User with this email already exists');
-    }
-
-    // Check for duplicate username if provided
-    if (dto.username) {
-      this.logger?.debug?.(`Checking if username exists: ${dto.username}`);
-      const existingUserByUsername = await this.userRepository.findOne({
-        where: { username: dto.username },
-      });
-
-      if (existingUserByUsername) {
-        this.logger?.warn?.(`Signup failed - username already exists: ${dto.username}`);
-        throw new NAuthException(AuthErrorCode.USERNAME_EXISTS, 'Username is already taken');
-      }
-    }
-
-    // Check for duplicate phone if provided and duplicates not allowed
-    if (dto.phone && !this.config.signup?.allowDuplicatePhones) {
-      this.logger?.debug?.(`Checking if phone exists: ${dto.phone}`);
-      const existingUserByPhone = await this.userRepository.findOne({
-        where: { phone: dto.phone },
-      });
-
-      if (existingUserByPhone) {
-        this.logger?.warn?.(`Signup failed - phone already exists: ${dto.phone}`);
-        throw new NAuthException(AuthErrorCode.PHONE_EXISTS, 'Phone number is already registered');
-      }
-    }
-
-    // Validate password policy
-    this.logger?.debug?.('Validating password against policy');
-    const passwordValidation = await this.passwordService.validatePassword(dto.password, {
-      email: dto.email,
-      username: dto.username,
-    });
-
-    if (!passwordValidation.valid) {
-      this.logger?.warn?.(`Password validation failed for ${dto.email}: ${passwordValidation.errors.join(', ')}`);
-      throw new NAuthException(AuthErrorCode.WEAK_PASSWORD, passwordValidation.errors.join(', '), {
-        errors: passwordValidation.errors,
-      });
-    }
-
-    // Hash password
-    const passwordHash = await this.passwordService.hashPassword(dto.password);
-
-    // Determine verification requirements based on verification method
-    const verificationMethod = this.config.signup?.verificationMethod;
-
-    // Validate required fields based on verification method
-    if ((verificationMethod === 'phone' || verificationMethod === 'both') && !dto.phone) {
-      this.logger?.warn?.(`Signup failed - phone required for verification method: ${verificationMethod}`);
-      throw new NAuthException(
-        AuthErrorCode.PHONE_REQUIRED,
-        'Phone number is required for the selected verification method',
-        { verificationMethod },
-      );
-    }
-
-    // Create user
-    // Users are always created as ACTIVE (so they can complete pending challenges)
-    // Verification status controls access via challenge system, not account activation
-    // Email and phone verification status is always false initially - must be explicitly verified
-    this.logger?.debug?.(`Creating user record for: ${dto.email} || ${dto.username} || ${dto.phone}`);
-    const user = this.userRepository.create({
-      email: dto.email,
-      username: dto.username,
-      firstName: dto.firstName,
-      lastName: dto.lastName,
-      phone: dto.phone,
-      passwordHash,
-      passwordChangedAt: new Date(),
-      isEmailVerified: false, // Always false initially - must be explicitly verified
-      isPhoneVerified: false, // Always false initially - must be verified via SMS
-      isActive: true, // Always active - challenges control access instead
-      metadata: dto.metadata,
-    });
-
-    let savedUser: IUser;
-    try {
-      savedUser = (await this.userRepository.save(user)) as unknown as IUser;
-      this.logger?.log?.(`User created successfully: ${dto.email} (sub: ${savedUser.sub})`);
-
-      // ============================================================================
-      // Audit: Record account creation
-      // ============================================================================
-      try {
-        await this.auditService?.recordEvent({
-          userId: savedUser.id,
-          eventType: AuthAuditEventType.ACCOUNT_CREATED,
-          eventStatus: 'INFO',
-          authMethod: 'password',
-          // Client info automatically included from context
-          metadata: {
-            email: savedUser.email,
-            username: savedUser.username || null,
-            verificationMethod,
-          },
-        });
-      } catch (auditError) {
-        // Non-blocking: Log but continue
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record ACCOUNT_CREATED audit event: ${errorMessage}`, {
-          error: auditError,
-          userId: savedUser.id,
-        });
-      }
-    } catch (error: unknown) {
-      // Handle database constraint violations gracefully
-      if (error && typeof error === 'object' && 'code' in error && error.code === '23505') {
-        // PostgreSQL unique constraint violation
-        const dbError = error as { code: string; detail?: string; message?: string };
-        if (dbError.detail?.includes('email')) {
-          this.logger?.warn?.(`Signup failed - email constraint violation: ${dto.email}`);
-          throw new NAuthException(AuthErrorCode.EMAIL_EXISTS, 'User with this email already exists');
-        } else if (dbError.detail?.includes('username')) {
-          this.logger?.warn?.(`Signup failed - username constraint violation: ${dto.username}`);
-          throw new NAuthException(AuthErrorCode.USERNAME_EXISTS, 'Username is already taken');
-        } else if (dbError.detail?.includes('phone')) {
-          this.logger?.warn?.(`Signup failed - phone constraint violation: ${dto.phone}`);
-          throw new NAuthException(AuthErrorCode.PHONE_EXISTS, 'Phone number is already registered');
-        } else {
-          this.logger?.error?.(`Signup failed - database constraint violation: ${dbError.message}`);
-          throw new NAuthException(AuthErrorCode.EMAIL_EXISTS, 'User with this information already exists', {
-            conflictType: 'unknown',
-          });
-        }
-      }
-
-      // Re-throw other database errors
-      const errorMessage = error instanceof Error ? error.message : 'Unknown database error';
-      this.logger?.error?.(`Signup failed - database error: ${errorMessage}`);
-      throw error;
-    }
-
-    // ============================================================================
-    // Verification Code Sending: Handled by challenge system (sequential flow)
-    // ============================================================================
-    // All verification codes are sent when challenges are created (in AuthChallengeHelperService.createChallengeResponse)
-    // This ensures proper sequential flow: email code first, then phone code after email is verified
-    // This prevents user confusion from receiving multiple codes at once
-
-    // Execute afterSignup hook if configured
-    if (this.config.hooks?.afterSignup) {
-      await this.config.hooks.afterSignup(savedUser, { requiresVerification: verificationMethod !== 'none' });
-    }
-
-    // ============================================================================
-    // Challenge System: Determine if user needs to complete challenges
-    // ============================================================================
-
-    const response = await this.challengeHelper.determineAuthResponse({
-      user: savedUser,
-      config: this.config,
-      deviceToken: clientInfo.deviceToken,
-    });
-
-    if (response.challengeName) {
-      this.logger?.log?.(`Challenge required for user ${savedUser.sub}: ${response.challengeName}`);
-    } else {
-      this.logger?.log?.(`Signup successful - tokens issued for: ${dto.email}`);
-    }
-
-    return response;
-  }
-
-  // ============================================================================
-  // User Login
-  // ============================================================================
-  /**
-   * Log in a user with identifier (email, username, or phone) and password.
-   *
-   * Handles client/device context, login hooks, lockout checks, audit logging, password verification,
-   * and challenge flow (MFA/verification) if required.
-   *
-   * @param dto - Login credentials (identifier and password)
-   * @returns Authentication response containing challenge details if required, or tokens on success
-   * @throws {NAuthException} On login failure, forbidden access, or account lockout
-   *
-   * @example
-   * ```typescript
-   * const res = await authService.login({ identifier: 'user@email.com', password: 'Pass123!' });
-   * if (res.challengeName) {
-   *   // prompt user for verification code
-   * }
-   * ```
-   */
-  async login(dto: LoginDTO): Promise<AuthResponseDTO> {
-    // Get client info from request context (transparent!)
-    const clientInfo = this.clientInfoService.get();
-    const fireAndForget = this.config.auditLogs?.fireAndForget === true;
-
-    this.logger?.log?.(`Login attempt for: ${dto.identifier}`);
-    this.logger?.debug?.(
-      `Login details: { identifier: ${dto.identifier}, ip: ${clientInfo.ipAddress}, deviceToken: ${clientInfo.deviceToken ? 'present' : 'none'} }`,
-    );
-
-    // Check IP-based account lockout
-    if (this.config.lockout?.enabled) {
-      const clientInfo = this.clientInfoService.get();
-      const ipAddress = clientInfo.ipAddress;
-
-      if (ipAddress) {
-        this.logger?.debug?.(`Checking IP lockout status for: ${ipAddress}`);
-        const isLocked = await this.accountLockoutStorage.isAccountLocked(ipAddress);
-        if (isLocked) {
-          this.logger?.warn?.(`Login blocked - IP locked: ${ipAddress}`);
-          await this.recordLoginAttempt(dto.identifier, false, 'ip_locked');
-
-          // ============================================================================
-          // Audit: Record blocked login (IP locked)
-          // ============================================================================
-          if (fireAndForget) {
-            this.auditService
-              ?.recordEvent({
-                userSub: dto.identifier,
-                eventType: AuthAuditEventType.LOGIN_BLOCKED,
-                eventStatus: 'FAILURE',
-                authMethod: 'password',
-                reason: 'ip_locked',
-                description: 'Login blocked - IP address locked due to too many failed attempts',
-              })
-              .catch((err) => {
-                const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-                this.logger?.error?.(`Failed to record LOGIN_BLOCKED audit event (fire-and-forget): ${errorMessage}`, {
-                  error: err,
-                  identifier: dto.identifier,
-                });
-              });
-          } else {
-            try {
-              await this.auditService?.recordEvent({
-                userSub: dto.identifier,
-                eventType: AuthAuditEventType.LOGIN_BLOCKED,
-                eventStatus: 'FAILURE',
-                authMethod: 'password',
-                reason: 'ip_locked',
-                description: 'Login blocked - IP address locked due to too many failed attempts',
-              });
-            } catch (auditError) {
-              const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-              this.logger?.error?.(`Failed to record LOGIN_BLOCKED audit event (IP locked): ${errorMessage}`, {
-                error: auditError,
-              });
-            }
-          }
-
-          throw new NAuthException(
-            AuthErrorCode.RATE_LIMIT_LOGIN,
-            'Too many failed attempts from this IP. Please try again later.',
-          );
-        }
-      }
-    }
-
-    // ============================================================================
-    // Validate identifier type based on configuration
-    // ============================================================================
-    const identifierType = this.config.login?.identifierType;
-    if (identifierType) {
-      this.logger?.debug?.(`Validating identifier type for: ${dto.identifier}, allowed type: ${identifierType}`);
-      const isValidIdentifier = this.validateIdentifierType(dto.identifier, identifierType);
-      if (!isValidIdentifier) {
-        this.logger?.warn?.(
-          `Login rejected - identifier type mismatch. Identifier: ${dto.identifier}, Required: ${identifierType}`,
-        );
-        await this.handleFailedLogin(dto.identifier, 'identifier_type_mismatch');
-        throw new NAuthException(
-          AuthErrorCode.INVALID_CREDENTIALS,
-          `Login with this identifier type is not allowed. Expected: ${identifierType}`,
-        );
-      }
-    }
-
-    // Find user by email, username, or phone (filtered by identifierType config)
-    this.logger?.debug?.(`Finding user by identifier: ${dto.identifier}`);
-    const user = await this.findUserByIdentifier(dto.identifier, identifierType);
-
-    // ⚠️ SECURITY CRITICAL: Always hash password even when user doesn't exist
-    // This ensures constant-time response to prevent user enumeration via timing attacks
-    const hashToVerify = user?.passwordHash || DUMMY_ARGON2_HASH;
-
-    // Verify password (takes ~200-300ms regardless of user existence)
-    this.logger?.debug?.('Verifying password');
-    const isPasswordValid = await this.passwordService.verifyPassword(dto.password, hashToVerify);
-
-    // Now check all conditions AFTER password verification (constant time achieved)
-    if (!user || !user.passwordHash || !isPasswordValid) {
-      this.logger?.warn?.(`Login failed - invalid credentials for: ${dto.identifier}`);
-      await this.handleFailedLogin(dto.identifier, 'invalid_credentials');
-
-      // ============================================================================
-      // Audit: Record failed login
-      // ============================================================================
-      if (user) {
-        if (fireAndForget) {
-          this.auditService
-            ?.recordEvent({
-              userId: user.id,
-              eventType: AuthAuditEventType.LOGIN_FAILED,
-              eventStatus: 'FAILURE',
-              authMethod: 'password',
-              reason: 'invalid_credentials',
-              description: 'Invalid password or user not found',
-            })
-            .catch((err) => {
-              const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-              this.logger?.error?.(`Failed to record LOGIN_FAILED audit event (fire-and-forget): ${errorMessage}`, {
-                error: err,
-                userId: user.id,
-                userSub: user.sub,
-              });
-            });
-        } else {
-          try {
-            await this.auditService?.recordEvent({
-              userId: user.id,
-              eventType: AuthAuditEventType.LOGIN_FAILED,
-              eventStatus: 'FAILURE',
-              authMethod: 'password',
-              reason: 'invalid_credentials',
-              description: 'Invalid password or user not found',
-            });
-          } catch (auditError) {
-            const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-            this.logger?.error?.(`Failed to record LOGIN_FAILED audit event: ${errorMessage}`, {
-              error: auditError,
-              userId: user?.id,
-            });
-          }
-        }
-      }
-
-      // Provide helpful error if user exists but has no password (social-only account)
-      if (user && !user.passwordHash && user.socialProviders && user.socialProviders.length > 0) {
-        const provider = user.socialProviders[0];
-        const providerName = provider.charAt(0).toUpperCase() + provider.slice(1);
-        throw new NAuthException(
-          AuthErrorCode.INVALID_CREDENTIALS,
-          `Invalid credentials - use your ${providerName} account`,
-          {
-            suggestedProvider: providerName,
-          },
-        );
-      }
-
-      throw new NAuthException(AuthErrorCode.INVALID_CREDENTIALS, 'Invalid credentials');
-    }
-
-    // ============================================================================
-    // Password Expiry Check
-    // ============================================================================
-    const expiryDays = this.config.password?.expiryDays;
-    if (expiryDays && expiryDays > 0 && user.passwordChangedAt) {
-      const expiryDate = new Date(user.passwordChangedAt);
-      expiryDate.setDate(expiryDate.getDate() + expiryDays);
-      const now = new Date();
-
-      if (now > expiryDate) {
-        this.logger?.warn?.(
-          `Password expired for user: ${user.sub}. Changed: ${user.passwordChangedAt}, Expiry: ${expiryDate}`,
-        );
-
-        // Force password change by setting mustChangePassword flag
-        await this.userRepository.update(user.id, {
-          mustChangePassword: true,
-        });
-        // Update in-memory user reference to include mustChangePassword
-        user.mustChangePassword = true;
-
-        // Check challenges - FORCE_CHANGE_PASSWORD will be included
-        const response = await this.challengeHelper.determineAuthResponse({
-          user,
-          config: this.config,
-          deviceToken: clientInfo.deviceToken,
-          isSocialLogin: false,
-        });
-
-        if (response.challengeName) {
-          this.logger?.warn?.(
-            `Login blocked - password expired, challenge: ${response.challengeName} for ${dto.identifier}`,
-          );
-          return response;
-        }
-      }
-    }
-
-    // ============================================================================
-    // Audit: Record login attempt for successful password verification
-    // ============================================================================
-    // Record LOGIN_ATTEMPT for all successful password verifications
-    // IMPORTANT: Always await this to ensure correct chronological order before risk assessment
-    try {
-      await this.auditService?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.LOGIN_ATTEMPT,
-        eventStatus: 'INFO',
-        authMethod: 'password',
-        description: 'Password verification successful',
-      });
-    } catch (auditError) {
-      // Non-blocking: Log but continue even if audit fails
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record LOGIN_ATTEMPT audit event: ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    // ============================================================================
-    // Challenge System: Determine authentication response using state machine
-    // ============================================================================
-    // All challenge determination is now handled by state machine in determineAuthResponse
-    // This replaces the old determinePendingChallenges and checkMFARequirement methods
-
-    const response = await this.challengeHelper.determineAuthResponse({
-      user,
-      config: this.config,
-      deviceToken: clientInfo.deviceToken,
-      isSocialLogin: false,
-    });
-
-    // If challenge is required, record login attempt and return challenge
-    if (response.challengeName) {
-      const reasonMap: Record<AuthChallenge, string> = {
-        [AuthChallenge.VERIFY_EMAIL]: 'verification_required',
-        [AuthChallenge.VERIFY_PHONE]: 'verification_required',
-        [AuthChallenge.MFA_SETUP_REQUIRED]: 'mfa_setup_required',
-        [AuthChallenge.FORCE_CHANGE_PASSWORD]: 'password_change_required',
-        [AuthChallenge.MFA_REQUIRED]: 'mfa_required',
-      };
-
-      this.logger?.warn?.(
-        `Login blocked - pending challenge: ${response.challengeName} for ${dto.identifier} (sub: ${user.sub})`,
-      );
-      await this.recordLoginAttempt(
-        dto.identifier,
-        false,
-        reasonMap[response.challengeName] || 'challenge_required',
-        user.id,
-      );
-
-      return response;
-    }
-
-    // If response already has tokens (session was created by challenge helper), return it
-    // This prevents duplicate session creation
-    if (response.accessToken && response.refreshToken) {
-      this.logger?.debug?.(
-        `Login successful - session already created by challenge helper for ${dto.identifier} (sub: ${user.sub})`,
-      );
-
-      // Record successful login attempt
-      await this.recordLoginAttempt(dto.identifier, true, undefined, user.id);
-      this.logger?.log?.(`Login successful for: ${dto.identifier} (sub: ${user.sub}) from ${clientInfo.ipAddress}`);
-
-      // Update user last login info
-      await this.userRepository.update(user.id, {
-        lastLoginAt: new Date(),
-        lastLoginIp: clientInfo.ipAddress,
-        failedLoginAttempts: 0,
-      });
-
-      // Reset IP-based failed attempts on successful login
-      if (this.config.lockout?.enabled && this.config.lockout.resetOnSuccess) {
-        const ipAddress = clientInfo.ipAddress;
-        if (ipAddress) {
-          this.logger?.debug?.(`Resetting failed login attempts for IP: ${ipAddress}`);
-          await this.accountLockoutStorage.resetFailedAttempts(ipAddress);
-        }
-      }
-
-      // Extract session ID and device info from token to record audit event
-      let sessionId: number | undefined;
-      let deviceId: string | undefined;
-      try {
-        const tokenPayload = this.jwtService.decodeToken(response.accessToken);
-        if (tokenPayload?.sessionId) {
-          sessionId = parseInt(String(tokenPayload.sessionId), 10);
-        }
-        // Get deviceId from session if available
-        if (sessionId) {
-          const session = await this.sessionService.findById(sessionId);
-          if (session && session.deviceId) {
-            deviceId = session.deviceId;
-          }
-        }
-      } catch (error) {
-        // Non-blocking: Continue without sessionId/deviceId
-        this.logger?.debug?.('Failed to extract sessionId/deviceId from token for audit');
-      }
-
-      // Determine trusted device and MFA bypass status from response
-      const isTrustedDevice = response.trusted || false;
-      const mfaBypassed = false; // Challenge helper handles MFA, so if we get here, MFA was not bypassed
-      const mfaBypassReason: 'trusted_device' | 'mfa_exempt' | null = null;
-
-      // Record successful login audit event
-      if (fireAndForget) {
-        this.auditService
-          ?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            sessionId: sessionId || undefined,
-            deviceId: deviceId || undefined,
-            authMethod: 'password',
-            metadata: { trustedDevice: isTrustedDevice, mfaBypassed, mfaBypassReason },
-          })
-          .catch((err) => {
-            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-            this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event (fire-and-forget): ${errorMessage}`, {
-              error: err,
-              userId: user.id,
-              userSub: user.sub,
-            });
-          });
-      } else {
-        try {
-          await this.auditService?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            sessionId: sessionId || undefined,
-            deviceId: deviceId || undefined,
-            authMethod: 'password',
-            metadata: { trustedDevice: isTrustedDevice, mfaBypassed, mfaBypassReason },
-          });
-        } catch (auditError) {
-          const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-          this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event: ${errorMessage}`, {
-            error: auditError,
-            userId: user.id,
-          });
-        }
-      }
-
-      return response;
-    }
-
-    // ============================================================================
-    // Trusted Device Status Check (for audit metadata)
-    // ============================================================================
-    let isTrustedDevice = false;
-    let mfaBypassed = false;
-    let mfaBypassReason: 'trusted_device' | 'mfa_exempt' | null = null;
-
-    if (
-      this.config.mfa?.rememberDevices &&
-      this.config.mfa?.rememberDevices !== 'never' &&
-      this.trustedDeviceService &&
-      clientInfo.deviceToken
-    ) {
-      isTrustedDevice = await this.trustedDeviceService.isDeviceTrusted(clientInfo.deviceToken, user.id);
-    }
-
-    // Check if user is exempt from MFA
-    const userEntityDebug = user as unknown as Record<string, unknown>;
-    const userMfaExempt = userEntityDebug.mfaExempt === true || userEntityDebug.mfaExempt === 'true';
-
-    // Determine if MFA was bypassed
-    // MFA is bypassed if:
-    // 1. No challenge was returned (meaning MFA was skipped)
-    // 2. MFA would have been required otherwise
-    // 3. Either:
-    //    a. Device is trusted AND bypassMFAForTrustedDevices is enabled (trusted device bypass)
-    //    b. User has mfaExempt = true (MFA exemption bypass)
-    if (!response.challengeName && this.config.mfa) {
-      const enforcement = this.config.mfa.enforcement || 'OPTIONAL';
-      // MFA would be required if:
-      // - OPTIONAL enforcement AND user has MFA enabled, OR
-      // - REQUIRED/ADAPTIVE enforcement (regardless of user.mfaEnabled for REQUIRED)
-      const wouldRequireMFA =
-        (enforcement === 'OPTIONAL' && user.mfaEnabled) || enforcement === 'REQUIRED' || enforcement === 'ADAPTIVE';
-
-      if (wouldRequireMFA) {
-        // Check if bypassed due to trusted device
-        if (
-          isTrustedDevice &&
-          this.config.mfa.bypassMFAForTrustedDevices === true &&
-          enforcement !== 'ADAPTIVE' && // Adaptive MFA could bypass it anyway if device is trusted but requires different logging
-          !userMfaExempt
-        ) {
-          mfaBypassed = true;
-          mfaBypassReason = 'trusted_device';
-          this.logger?.debug?.(`MFA bypassed for trusted device - user ${user.sub}`);
-        }
-        // Check if bypassed due to MFA exemption
-        else if (userMfaExempt) {
-          mfaBypassed = true;
-          mfaBypassReason = 'mfa_exempt';
-          this.logger?.debug?.(`MFA bypassed due to exemption - user ${user.sub}`);
-        }
-      }
-    }
-
-    // MFA challenge is already handled by determineAuthResponse above
-    // If response.challengeName is set, it was already returned
-
-    // Check if user is active (should never happen with new signups, but keep for legacy accounts)
-    if (!user.isActive) {
-      this.logger?.warn?.(`Login failed - account inactive: ${dto.identifier} (sub: ${user.sub})`);
-      await this.recordLoginAttempt(dto.identifier, false, 'account_inactive', user.id);
-
-      // ============================================================================
-      // Audit: Record blocked login (account inactive)
-      // ============================================================================
-      try {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.LOGIN_BLOCKED,
-          eventStatus: 'FAILURE',
-          authMethod: 'password',
-          reason: 'account_inactive',
-          description: 'Login blocked - account is inactive',
-          // Client info automatically included from context
-        });
-      } catch (auditError) {
-        // Non-blocking: Log but continue
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record LOGIN_BLOCKED audit event (account inactive): ${errorMessage}`, {
-          error: auditError,
-          userId: user.id,
-        });
-      }
-
-      throw new NAuthException(AuthErrorCode.ACCOUNT_INACTIVE, 'Account is inactive. Please contact support.');
-    }
-
-    // Reset IP-based failed attempts on successful login
-    if (this.config.lockout?.enabled && this.config.lockout.resetOnSuccess) {
-      const ipAddress = clientInfo.ipAddress;
-
-      if (ipAddress) {
-        this.logger?.debug?.(`Resetting failed login attempts for IP: ${ipAddress}`);
-        await this.accountLockoutStorage.resetFailedAttempts(ipAddress);
-      }
-    }
-
-    // ============================================================================
-    // Generate Device ID Server-Side (Security: Never accept from client)
-    // ============================================================================
-
-    // Always generate device ID server-side (no client input accepted)
-    // This device ID is used for session tracking, not for trusted device feature
-    // Trusted devices use separate deviceToken (generated after MFA verification)
-    const validatedDeviceId = crypto.randomUUID();
-    this.logger?.debug?.(`Generated server-side deviceId: ${validatedDeviceId}`);
-
-    // Generate token family for rotation tracking
-    const tokenFamily = this.jwtService.generateTokenFamily();
-
-    // ============================================================================
-    // Single Session Mode: Revoke other sessions if disallowMultipleSessions is enabled
-    // ============================================================================
-    if (this.config.session?.disallowMultipleSessions) {
-      this.logger?.debug?.(`Single session mode enabled - revoking other sessions for user: ${user.sub}`);
-      const revokedCount = await this.sessionService.revokeAllUserSessions(user.id, 'Login from new session');
-      if (revokedCount > 0) {
-        this.logger?.log?.(`Revoked ${revokedCount} other active session(s) for user: ${user.sub}`);
-      }
-    }
-
-    // Atomically create session and persist token hashes
-    this.logger?.debug?.(`Creating login session for user: ${user.sub}`);
-    const atomic = await this.sessionService.createSessionAtomic(
-      {
-        userId: user.id,
-        tokenFamily,
-        deviceId: validatedDeviceId,
-        deviceName: dto.deviceName,
-        deviceType: dto.deviceType,
-        // Client info (ipAddress, ipCountry, ipCity, userAgent) automatically extracted from ClientInfoService
-        isRemembered: false,
-        expiresAt: this.sessionService.getSessionExpirationDate(),
-        authMethod: 'password',
-      },
-      async (sessionId) => {
-        const pair = await this.jwtService.generateTokenPair({
-          userId: user.sub,
-          email: user.email,
-          sessionId: sessionId.toString(),
-          tokenFamily,
-        });
-        return {
-          accessTokenHash: this.jwtService.hashToken(pair.accessToken),
-          refreshTokenHash: this.jwtService.hashToken(pair.refreshToken),
-          extra: pair,
-        };
-      },
-    );
-    const session = atomic.session;
-    const tokens = atomic.extra!;
-    this.logger?.debug?.(`Session created: ${session.id}`);
-
-    // Update user last login info - use internal id for update
-    await this.userRepository.update(user.id, {
-      lastLoginAt: new Date(),
-      lastLoginIp: clientInfo.ipAddress,
-      failedLoginAttempts: 0,
-    });
-
-    // Record successful login attempt - use internal id
-    await this.recordLoginAttempt(dto.identifier, true, undefined, user.id);
-    this.logger?.log?.(`Login successful for: ${dto.identifier} (sub: ${user.sub}) from ${clientInfo.ipAddress}`);
-
-    // ============================================================================
-    // Audit: Record successful login with trusted device and MFA bypass metadata
-    // ============================================================================
-    if (fireAndForget) {
-      this.auditService
-        ?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.LOGIN_SUCCESS,
-          eventStatus: 'SUCCESS',
-          sessionId: session.id,
-          deviceId: validatedDeviceId || undefined,
-          authMethod: 'password',
-          metadata: { trustedDevice: isTrustedDevice, mfaBypassed, mfaBypassReason },
-        })
-        .catch((err) => {
-          const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-          this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event (fire-and-forget): ${errorMessage}`, {
-            error: err,
-            userId: user.id,
-            userSub: user.sub,
-          });
-        });
-    } else {
-      try {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.LOGIN_SUCCESS,
-          eventStatus: 'SUCCESS',
-          sessionId: session.id,
-          deviceId: validatedDeviceId || undefined,
-          authMethod: 'password',
-          metadata: { trustedDevice: isTrustedDevice, mfaBypassed, mfaBypassReason },
-        });
-      } catch (auditError) {
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event: ${errorMessage}`, {
-          error: auditError,
-          userId: user.id,
-        });
-      }
-    }
-
-    // // Execute afterLogin hook
-    // if (this.config.hooks?.afterLogin) {
-    //   await this.config.hooks.afterLogin(user, session);
-    // }
-
-    // ============================================================================
-    // Trusted Device Token Management (Remember Device Feature)
-    // ============================================================================
-    let deviceToken: string | undefined;
-    let isTrusted = false;
-
-    if (this.config.mfa?.rememberDevices && this.config.mfa?.rememberDevices !== 'never' && this.trustedDeviceService) {
-      const rememberDevicesMode = this.config.mfa.rememberDevices;
-
-      // Check if device is already trusted
-      if (clientInfo.deviceToken) {
-        isTrusted = await this.trustedDeviceService.isDeviceTrusted(clientInfo.deviceToken, user.id);
-        if (isTrusted) {
-          deviceToken = clientInfo.deviceToken; // Reuse existing token
-          this.logger?.debug?.(`Device already trusted for user ${user.sub}`);
-        }
-      }
-
-      // Auto-trust mode: Create device token automatically if not already trusted
-      if (rememberDevicesMode === 'always' && !isTrusted) {
-        try {
-          deviceToken = await this.trustedDeviceService.createTrustedDevice(
-            user.id,
-            dto.deviceName || clientInfo.deviceName,
-            dto.deviceType || clientInfo.deviceType,
-            clientInfo.ipAddress,
-            clientInfo.userAgent,
-            clientInfo.platform,
-            clientInfo.browser,
-          );
-          isTrusted = true;
-          this.logger?.debug?.(`Auto-created trusted device token for user ${user.sub} (always mode)`);
-        } catch (error) {
-          // Non-blocking: Log but continue without device token
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.warn?.(`Failed to create trusted device token: ${errorMessage}`, { error });
-        }
-      }
-      // user_opt_in mode: Don't create token here - user must call trust-device endpoint
-      // isTrusted flag is already set above if device token exists and is valid
-    }
-
-    // Decode tokens to get expiry times
-    const accessTokenValidation = await this.jwtService.validateAccessToken(tokens.accessToken);
-    const refreshTokenValidation = await this.jwtService.validateRefreshToken(tokens.refreshToken);
-
-    // Return sanitized user object with expiry timestamps
-    // Note: deviceToken inclusion in response body is handled by CookieTokenInterceptor
-    // which checks route-level @TokenDelivery decorator and global config
-    // to decide whether to set as cookie and/or strip from body
-    const userDto = UserResponseDto.fromEntity(user);
-    const authResponse: AuthResponseDTO = {
-      user: {
-        sub: userDto.sub,
-        email: userDto.email,
-        firstName: userDto.firstName,
-        lastName: userDto.lastName,
-        phone: userDto.phone ?? undefined,
-        isEmailVerified: userDto.isEmailVerified,
-        isPhoneVerified: userDto.isPhoneVerified ?? undefined,
-        socialProviders:
-          userDto.socialProviders && userDto.socialProviders.length > 0 ? userDto.socialProviders : undefined,
-      },
-      accessToken: tokens.accessToken,
-      refreshToken: tokens.refreshToken,
-      accessTokenExpiresAt: accessTokenValidation.payload?.exp || 0,
-      refreshTokenExpiresAt: refreshTokenValidation.payload?.exp || 0,
-      trusted: isTrusted, // Include trusted flag so frontend knows if device is already trusted
-      // Include deviceToken - CookieTokenInterceptor will handle cookie/stripping based on @TokenDelivery decorator
-      deviceToken,
-    };
-    return authResponse;
-  }
-
-  /**
-   * Complete an authentication challenge using the provided response data.
-   *
-   * Handles all challenge types (email verification, phone verification, MFA, password change, MFA setup).
-   * Validates the session, challenge type, and parameters, and returns the result (tokens or next challenge).
-   *
-   * @param responseData - Data for responding to the challenge
-   * @returns The authentication response (tokens or next challenge requirement)
-   * @throws {NAuthException} If validation fails or the challenge type is unknown
-   *
-   * @example
-   * ```typescript
-   * // Example for email verification:
-   * const dto = Object.assign(new RespondChallengeDTO(), {
-   *   session: 'session-token',
-   *   type: 'VERIFY_EMAIL',
-   *   code: '123456',
-   * });
-   * await authService.respondToChallenge(dto);
-   * ```
-   */
-  async respondToChallenge(dto: RespondChallengeDTO): Promise<AuthResponseDTO> {
-    const responseData = dto as ChallengeResponseData;
-    const { session, type } = responseData;
-    const requestTrace = `${Date.now()}-${Math.random().toString(36).substring(7)}`;
-
-    this.logger?.log?.(
-      `[${requestTrace}] Challenge response received: type=${type}, session=${session?.substring(0, 8)}...`,
-    );
-
-    // Validate session and get challenge type
-    const challengeSession = await this.challengeService.validateSession(session);
-
-    // Validate response matches expected challenge
-    this.validateChallengeTypeMatch(challengeSession.challengeName, type);
-
-    // Validate parameters for this challenge type
-    // TODO: Later check if we can use classvalidator to replicate the logic of DTO validation centrally
-    this.validateChallengeParams(type, responseData);
-
-    // Handle challenge based on type
-    switch (type) {
-      case 'VERIFY_EMAIL':
-        return await this.handleVerifyEmail(challengeSession, (responseData as VerifyEmailResponse).code);
-
-      case 'VERIFY_PHONE':
-        return await this.handleVerifyPhone(
-          challengeSession,
-          responseData as VerifyPhoneResponse | CollectPhoneResponse,
-        );
-
-      case 'MFA_REQUIRED':
-        return await this.handleMFAVerification(
-          challengeSession,
-          responseData as VerifyMFACodeResponse | VerifyMFAPasskeyResponse,
-        );
-
-      case 'FORCE_CHANGE_PASSWORD':
-        return await this.handleForceChangePassword(
-          challengeSession,
-          (responseData as ForceChangePasswordResponse).newPassword,
-        );
-
-      case 'MFA_SETUP_REQUIRED':
-        return await this.handleMFASetup(challengeSession, responseData as MFASetupResponse);
-
-      default:
-        throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, `Unknown challenge type: ${type}`);
-    }
-  }
-
-  /**
-   * Validate that response type matches expected challenge type
-   */
-  private validateChallengeTypeMatch(expected: string, provided: string): void {
-    if (expected !== provided) {
-      throw new NAuthException(
-        AuthErrorCode.VALIDATION_FAILED,
-        `Challenge type mismatch: expected ${expected}, got ${provided}`,
-      );
-    }
-  }
-
-  /**
-   * Validate parameters for challenge type
-   *
-   * Service-level validation ensures Express/other frameworks get same validation as NestJS.
-   * This is critical for non-DTO-based applications.
-   */
-  private validateChallengeParams(type: string, data: ChallengeResponseData): void {
-    switch (type) {
-      case 'VERIFY_EMAIL': {
-        const response = data as VerifyEmailResponse;
-        if (!response.code || typeof response.code !== 'string') {
-          throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'Verification code is required', { field: 'code' });
-        }
-        break;
-      }
-
-      case 'VERIFY_PHONE': {
-        const response = data as VerifyPhoneResponse | CollectPhoneResponse;
-        const hasCode = 'code' in response && response.code;
-        const hasPhone = 'phone' in response && response.phone;
-
-        if (!hasCode && !hasPhone) {
-          throw new NAuthException(
-            AuthErrorCode.VALIDATION_FAILED,
-            'Either phone number or verification code is required',
-            { fields: ['phone', 'code'] },
-          );
-        }
-        break;
-      }
-
-      case 'MFA_REQUIRED': {
-        const response = data as VerifyMFACodeResponse | VerifyMFAPasskeyResponse;
-        if (!response.method) {
-          throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'MFA method is required', { field: 'method' });
-        }
-
-        if (response.method === 'passkey') {
-          const passkeyResponse = response as VerifyMFAPasskeyResponse;
-          if (!passkeyResponse.credential) {
-            throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'Passkey credential is required', {
-              field: 'credential',
-            });
-          }
-        } else {
-          const codeResponse = response as VerifyMFACodeResponse;
-          if (!codeResponse.code || typeof codeResponse.code !== 'string') {
-            throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'MFA code is required', { field: 'code' });
-          }
-        }
-        break;
-      }
-
-      case 'FORCE_CHANGE_PASSWORD': {
-        const response = data as ForceChangePasswordResponse;
-        if (!response.newPassword || typeof response.newPassword !== 'string') {
-          throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'New password is required', {
-            field: 'newPassword',
-          });
-        }
-        break;
-      }
-
-      case 'MFA_SETUP_REQUIRED': {
-        const response = data as MFASetupResponse;
-        if (!response.method) {
-          throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'MFA setup method is required', {
-            field: 'method',
-          });
-        }
-        if (!response.setupData || typeof response.setupData !== 'object') {
-          throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'MFA setup data is required', {
-            field: 'setupData',
-          });
-        }
-        break;
-      }
-    }
-  }
-
-  /**
-   * Handle VERIFY_EMAIL challenge
-   */
-  private async handleVerifyEmail(challengeSession: any, code: string): Promise<AuthResponseDTO> {
-    const user = challengeSession.user;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.CHALLENGE_INVALID, 'User not found in challenge session');
-    }
-
-    this.logger?.log?.(`Verifying email for user: ${user.sub}`);
-
-    // Verify email with code, ensuring it belongs to this specific challenge session
-    const verifyDto = Object.assign(new VerifyEmailWithCodeDTO(), {
-      email: user.email,
-      code,
-      challengeSessionId: challengeSession.id, // Link verification to this specific session
-    });
-    const result = await this.emailVerificationService.verifyEmailWithCode(verifyDto);
-    const isVerified = result.message === 'Email verified successfully. Please log in to continue.';
-
-    if (!isVerified) {
-      // Increment attempts but don't consume session
-      await this.challengeService.incrementAttempts(challengeSession);
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid verification code');
-    }
-
-    // Consume challenge session
-    await this.challengeService.validateAndConsumeSession(challengeSession.sessionToken, AuthChallenge.VERIFY_EMAIL);
-
-    // Reload user to get updated emailVerified flag
-    const updatedUser = await this.userRepository.findOne({ where: { sub: user.sub } });
-    if (!updatedUser) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found after email verification');
-    }
-
-    // Get client info
-    const clientInfo = this.clientInfoService.get();
-
-    // Read auth context from challenge session metadata
-    const authMethod = (challengeSession.metadata?.authMethod as string) || 'password';
-    const authProvider = challengeSession.metadata?.authProvider as string | undefined;
-    const isSocialLogin = authMethod === 'social';
-
-    // Check for next challenges
-    const response = await this.challengeHelper.determineAuthResponse({
-      user: updatedUser as unknown as IUser,
-      config: this.config,
-      deviceToken: clientInfo.deviceToken,
-      isSocialLogin,
-      skipMFAVerification: false,
-      authProvider,
-    });
-
-    if (response.challengeName) {
-      this.logger?.log?.(`Additional challenge required: ${response.challengeName}`);
-    } else {
-      this.logger?.log?.(`Email verified, auth completed for: ${user.email}`);
-    }
-
-    return response;
-  }
-
-  /**
-   * Handle VERIFY_PHONE challenge
-   */
-  private async handleVerifyPhone(
-    challengeSession: any,
-    data: VerifyPhoneResponse | CollectPhoneResponse,
-  ): Promise<AuthResponseDTO> {
-    const user = challengeSession.user;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.CHALLENGE_INVALID, 'User not found in challenge session');
-    }
-
-    // Check if this is phone collection (first step) or verification (second step)
-    if ('phone' in data && data.phone) {
-      // Phone collection step
-      const phone = data.phone;
-
-      this.logger?.log?.(`Collecting phone number for user: ${user.sub}`);
-
-      // Validate phone format (E.164 format: +[country][number])
-      const phoneRegex = /^\+[1-9]\d{1,14}$/;
-      if (!phoneRegex.test(phone)) {
-        throw new NAuthException(
-          AuthErrorCode.INVALID_PHONE_FORMAT,
-          'Invalid phone number format. Use E.164 format (e.g., +1234567890)',
-        );
-      }
-
-      // Update user phone number
-      await this.userRepository.update({ sub: user.sub }, { phone });
-
-      this.logger?.log?.(`Phone number added for user ${user.sub}: ${phone}`);
-
-      // Send verification SMS to the newly added phone
-      let smsError: string | undefined;
-      if (this.phoneVerificationService) {
-        this.logger?.log?.(`Sending verification SMS to newly added phone: ${phone}`);
-        try {
-          const smsDto = Object.assign(new SendVerificationSMSDTO(), {
-            sub: user.sub,
-            challengeSessionId: challengeSession.id, // Link SMS code to this challenge session
-          });
-          await this.phoneVerificationService.sendVerificationSMS(smsDto);
-          this.logger?.log?.(`Verification SMS sent successfully to: ${phone}`);
-        } catch (error: unknown) {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.error?.(`Failed to send verification SMS to ${phone}: ${errorMessage}`);
-          smsError = errorMessage;
-        }
-      } else {
-        this.logger?.warn?.(
-          `Phone verification SMS not sent - PhoneVerificationService not available. ` +
-            'Phone verification requires an SMS provider to be configured.',
-        );
-      }
-
-      // DO NOT consume the challenge session yet - user still needs to verify the code
-      // Preserve auth context from original challenge session
-      const authMethod = (challengeSession.metadata?.authMethod as string) || 'password';
-      const authProvider = challengeSession.metadata?.authProvider as string | undefined;
-
-      // Return same challenge with updated phone in parameters
-      // Skip auto-send since SMS was already sent above during phone collection
-      const challengeResponse = await this.challengeHelper.createChallengeResponse(
-        { ...user, phone },
-        AuthChallenge.VERIFY_PHONE,
-        this.config,
-        authMethod as 'password' | 'social',
-        authProvider,
-        true, // skipAutoSend = true (SMS already sent during phone collection)
-      );
-
-      // Include SMS error in challenge parameters if SMS failed
-      if (smsError) {
-        challengeResponse.challengeParameters = challengeResponse.challengeParameters || {};
-        challengeResponse.challengeParameters.smsError = smsError;
-      }
-
-      return challengeResponse;
-    } else {
-      // Phone verification step (code provided)
-      const code = (data as VerifyPhoneResponse).code;
-
-      this.logger?.log?.(`Verifying phone for user: ${user.sub}`);
-
-      // Check if phone is set
-      if (!user.phone) {
-        throw new NAuthException(
-          AuthErrorCode.VALIDATION_FAILED,
-          'Phone number not yet provided. Submit phone number first.',
-        );
-      }
-
-      // Verify phone with code, ensuring it belongs to this specific challenge session
-      const verifyDto = Object.assign(new VerifyPhoneWithCodeBySubDTO(), {
-        sub: user.sub,
-        code,
-        challengeSessionId: challengeSession.id, // Link verification to this specific session
-      });
-      const result = await this.phoneVerificationService!.verifyPhoneWithCodeBySub(verifyDto);
-      const isVerified = result.message === 'Phone verified successfully. Please log in to continue.';
-
-      if (!isVerified) {
-        // Increment attempts but don't consume session
-        await this.challengeService.incrementAttempts(challengeSession);
-        throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid verification code');
-      }
-
-      // Consume challenge session
-      await this.challengeService.validateAndConsumeSession(challengeSession.sessionToken, AuthChallenge.VERIFY_PHONE);
-
-      // Reload user to get updated phoneVerified flag
-      const updatedUser = await this.userRepository.findOne({ where: { sub: user.sub } });
-      if (!updatedUser) {
-        throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found after phone verification');
-      }
-
-      // Get client info
-      const clientInfo = this.clientInfoService.get();
-
-      // Read auth context from challenge session metadata
-      const authMethod = (challengeSession.metadata?.authMethod as string) || 'password';
-      const authProvider = challengeSession.metadata?.authProvider as string | undefined;
-      const isSocialLogin = authMethod === 'social';
-
-      // Check for next challenges
-      const response = await this.challengeHelper.determineAuthResponse({
-        user: updatedUser as unknown as IUser,
-        config: this.config,
-        deviceToken: clientInfo.deviceToken,
-        isSocialLogin,
-        skipMFAVerification: false,
-        authProvider,
-      });
-
-      if (response.challengeName) {
-        this.logger?.log?.(`Additional challenge required: ${response.challengeName}`);
-      } else {
-        this.logger?.log?.(`Phone verified, auth completed for: ${user.email}`);
-
-        // ============================================================================
-        // Audit: Record successful login after phone verification
-        // ============================================================================
-        const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-        if (fireAndForget) {
-          this.auditService
-            ?.recordEvent({
-              userId: user.id,
-              eventType: AuthAuditEventType.LOGIN_SUCCESS,
-              eventStatus: 'SUCCESS',
-              authMethod: isSocialLogin ? authProvider || 'social' : 'password',
-              metadata: {
-                completedAfterPhoneVerification: true,
-              },
-            })
-            .catch((err) => {
-              const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-              this.logger?.error?.(
-                `Failed to record LOGIN_SUCCESS audit event after phone verification (fire-and-forget): ${errorMessage}`,
-                {
-                  error: err,
-                  userId: user.id,
-                  userSub: user.sub,
-                },
-              );
-            });
-        } else {
-          try {
-            await this.auditService?.recordEvent({
-              userId: user.id,
-              eventType: AuthAuditEventType.LOGIN_SUCCESS,
-              eventStatus: 'SUCCESS',
-              authMethod: isSocialLogin ? authProvider || 'social' : 'password',
-              metadata: {
-                completedAfterPhoneVerification: true,
-              },
-            });
-          } catch (auditError) {
-            const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-            this.logger?.error?.(
-              `Failed to record LOGIN_SUCCESS audit event after phone verification: ${errorMessage}`,
-              {
-                error: auditError,
-                userId: user.id,
-              },
-            );
-          }
-        }
-      }
-
-      return response;
-    }
-  }
-
-  /**
-   * Handle MFA_REQUIRED challenge
-   */
-  private async handleMFAVerification(
-    challengeSession: any,
-    data: VerifyMFACodeResponse | VerifyMFAPasskeyResponse,
-  ): Promise<AuthResponseDTO> {
-    const user = challengeSession.user;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.CHALLENGE_INVALID, 'User not found in challenge session');
-    }
-
-    const method = data.method;
-
-    this.logger?.log?.(`MFA verification attempt: method=${method}, user=${user.sub}`);
-
-    // Check if MFAService is available
-    if (!this.mfaService) {
-      throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
-    }
-
-    // Get client info
-    const clientInfo = this.clientInfoService.get();
-
-    // Verify MFA based on method
-    let isValid = false;
-
-    if (method === 'passkey') {
-      const passkeyData = data as VerifyMFAPasskeyResponse;
-      const credential = passkeyData.credential;
-
-      // Get expected challenge from session metadata
-      const expectedChallenge = challengeSession.metadata?.passkeyChallenge;
-      if (!expectedChallenge) {
-        throw new NAuthException(AuthErrorCode.CHALLENGE_INVALID, 'No passkey challenge found in session');
-      }
-
-      // Verify passkey via MFAService
-      const wrappedCredential = { credential, expectedChallenge };
-      const verifyResult = await this.mfaService.verifyCode({
-        sub: user.sub,
-        methodName: MFAMethod.PASSKEY,
-        code: wrappedCredential,
-      });
-      isValid = verifyResult.valid;
-    } else {
-      const codeData = data as VerifyMFACodeResponse;
-      const code = codeData.code;
-
-      // Verify code via MFAService (handles totp, sms, and backup)
-      const verifyResult = await this.mfaService.verifyCode({
-        sub: user.sub,
-        methodName: method,
-        code,
-      });
-      isValid = verifyResult.valid;
-    }
-
-    if (!isValid) {
-      this.logger?.warn?.(`MFA verification failed for user: ${user.sub}`);
-
-      // Audit: Record MFA verification failure
-      if (this.config.auditLogs?.fireAndForget) {
-        this.auditService
-          ?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.MFA_VERIFICATION_FAILED,
-            eventStatus: 'FAILURE',
-            challengeSessionId: challengeSession.id,
-            authMethod: method,
-            metadata: { mfaMethod: method },
-          })
-          .catch((err) => {
-            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-            this.logger?.error?.(
-              `Failed to record MFA_VERIFICATION_FAILED audit event (fire-and-forget): ${errorMessage}`,
-              {
-                error: err,
-                userId: user.id,
-                userSub: user.sub,
-              },
-            );
-          });
-      } else {
-        try {
-          await this.auditService?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.MFA_VERIFICATION_FAILED,
-            eventStatus: 'FAILURE',
-            challengeSessionId: challengeSession.id,
-            authMethod: method,
-            metadata: { mfaMethod: method },
-          });
-        } catch (auditError) {
-          const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-          this.logger?.error?.(`Failed to record MFA_VERIFICATION_FAILED audit event: ${errorMessage}`, {
-            error: auditError,
-            userId: user.id,
-          });
-        }
-      }
-
-      // Increment challenge attempts (session not consumed, so user can retry)
-      await this.challengeService.incrementAttempts(challengeSession);
-
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid MFA code');
-    }
-
-    this.logger?.log?.(`MFA verified successfully for user: ${user.sub}`);
-
-    // Audit: Record MFA verification success
-    if (this.config.auditLogs?.fireAndForget) {
-      this.auditService
-        ?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.MFA_VERIFICATION_SUCCESS,
-          eventStatus: 'SUCCESS',
-          challengeSessionId: challengeSession.id,
-          authMethod: method,
-          metadata: { mfaMethod: method },
-        })
-        .catch((err) => {
-          const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-          this.logger?.error?.(
-            `Failed to record MFA_VERIFICATION_SUCCESS audit event (fire-and-forget): ${errorMessage}`,
-            {
-              error: err,
-              userId: user.id,
-              userSub: user.sub,
-            },
-          );
-        });
-    } else {
-      try {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.MFA_VERIFICATION_SUCCESS,
-          eventStatus: 'SUCCESS',
-          challengeSessionId: challengeSession.id,
-          authMethod: method,
-          metadata: { mfaMethod: method },
-        });
-      } catch (auditError) {
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record MFA_VERIFICATION_SUCCESS audit event: ${errorMessage}`, {
-          error: auditError,
-          userId: user.id,
-        });
-      }
-    }
-
-    // Store MFA method in challenge session metadata for CHALLENGE_COMPLETED audit event
-    await this.challengeService.updateMetadata(challengeSession.sessionToken, {
-      mfaMethod: method,
-    });
-
-    // Only consume the session AFTER successful verification
-    await this.challengeService.validateAndConsumeSession(challengeSession.sessionToken, AuthChallenge.MFA_REQUIRED);
-
-    // Read auth context from challenge session metadata
-    const authMethod = (challengeSession.metadata?.authMethod as string) || 'password';
-    const authProvider = challengeSession.metadata?.authProvider as string | undefined;
-    const isSocialLogin = authMethod === 'social';
-
-    // ============================================================================
-    // Trusted Device Token Management (Remember Device Feature)
-    // ============================================================================
-    // NOTE:
-    // - We only create / update trusted device tokens AFTER MFA has been successfully
-    //   verified to avoid trusting devices that haven't completed full auth.
-    // - For 'always' mode, this mirrors the behavior in the primary login flow.
-    let deviceToken = clientInfo.deviceToken as string | undefined;
-    let isTrustedDevice = false;
-
-    if (this.trustedDeviceService && this.config.mfa?.rememberDevices && this.config.mfa.rememberDevices !== 'never') {
-      const rememberMode = this.config.mfa.rememberDevices;
-
-      // If a device token is already present, check if it's trusted
-      if (deviceToken) {
-        try {
-          isTrustedDevice = await this.trustedDeviceService.isDeviceTrusted(deviceToken, user.id);
-          if (isTrustedDevice) {
-            this.logger?.debug?.(
-              `MFA flow: existing trusted device token detected for user ${user.sub} (token reused)`,
-            );
-          }
-        } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.warn?.(
-            `MFA flow: failed to validate existing trusted device token for user ${user.sub}: ${errorMessage}`,
-            { error },
-          );
-        }
-      }
-
-      // Auto-trust mode: create device token automatically if not already trusted
-      if (rememberMode === 'always' && !isTrustedDevice) {
-        try {
-          deviceToken = await this.trustedDeviceService.createTrustedDevice(
-            user.id,
-            clientInfo.deviceName,
-            clientInfo.deviceType,
-            clientInfo.ipAddress,
-            clientInfo.userAgent,
-            clientInfo.platform,
-            clientInfo.browser,
-          );
-          isTrustedDevice = true;
-          this.logger?.debug?.(
-            `MFA flow: auto-created trusted device token for user ${user.sub} (rememberDevices='always')`,
-          );
-        } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.warn?.(`MFA flow: failed to create trusted device token for user ${user.sub}: ${errorMessage}`, {
-            error,
-          });
-        }
-      }
-    }
-
-    // Check for next challenges (MFA is usually the last challenge)
-    const response = await this.challengeHelper.determineAuthResponse({
-      user,
-      config: this.config,
-      deviceToken,
-      isSocialLogin,
-      skipMFAVerification: true, // Already verified
-      authProvider,
-    });
-
-    // Propagate trusted device metadata into response so that:
-    // - CookieTokenInterceptor can set the nauth_device_token cookie (cookies mode)
-    // - Mobile clients in JSON mode can store the device token securely
-    if (isTrustedDevice) {
-      response.trusted = response.trusted ?? true;
-    }
-    if (deviceToken && !response.deviceToken) {
-      response.deviceToken = deviceToken;
-    }
-
-    if (response.challengeName) {
-      this.logger?.log?.(`Additional challenge required: ${response.challengeName}`);
-    } else {
-      this.logger?.log?.(`MFA verified, auth completed for: ${user.email}`);
-
-      // ============================================================================
-      // Audit: Record successful login after MFA completion
-      // ============================================================================
-      const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-      if (fireAndForget) {
-        this.auditService
-          ?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            authMethod: isSocialLogin ? authProvider || 'social' : 'password',
-            metadata: {
-              completedAfterMFA: true,
-            },
-          })
-          .catch((err) => {
-            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-            this.logger?.error?.(
-              `Failed to record LOGIN_SUCCESS audit event after MFA (fire-and-forget): ${errorMessage}`,
-              {
-                error: err,
-                userId: user.id,
-                userSub: user.sub,
-              },
-            );
-          });
-      } else {
-        try {
-          await this.auditService?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            authMethod: isSocialLogin ? authProvider || 'social' : 'password',
-            metadata: {
-              completedAfterMFA: true,
-            },
-          });
-        } catch (auditError) {
-          const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-          this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event after MFA: ${errorMessage}`, {
-            error: auditError,
-            userId: user.id,
-          });
-        }
-      }
-    }
-
-    return response;
-  }
-
-  /**
-   * Handle FORCE_CHANGE_PASSWORD challenge
-   */
-  private async handleForceChangePassword(challengeSession: any, newPassword: string): Promise<AuthResponseDTO> {
-    const user = challengeSession.user;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.CHALLENGE_INVALID, 'User not found in challenge session');
-    }
-
-    this.logger?.log?.(`Changing password for user: ${user.sub}`);
-
-    // Validate new password
-    const validation = await this.passwordService.validatePassword(newPassword, {
-      email: user.email,
-      username: user.username || undefined,
-    });
-
-    if (!validation.valid) {
-      throw new NAuthException(AuthErrorCode.WEAK_PASSWORD, validation.errors.join(', '), {
-        errors: validation.errors,
-      });
-    }
-
-    // Check password history
-    if (this.config.password?.historyCount) {
-      const historyToCheck = user.passwordHistory || [];
-      const allPreviousPasswords = user.passwordHash ? [user.passwordHash, ...historyToCheck] : historyToCheck;
-
-      const isReused = await this.passwordService.isPasswordInHistory(newPassword, allPreviousPasswords);
-
-      if (isReused) {
-        throw new NAuthException(
-          AuthErrorCode.PASSWORD_REUSED,
-          'You have used this password recently. Please choose a different password.',
-        );
-      }
-    }
-
-    // Hash new password
-    const newHash = await this.passwordService.hashPassword(newPassword);
-
-    // Update password history
-    const newHistory = this.passwordService.addToHistory(user.passwordHistory || [], user.passwordHash);
-
-    // Update user password and clear mustChangePassword flag - use save() for array fields
-    user.passwordHash = newHash;
-    user.passwordChangedAt = new Date();
-    user.passwordHistory = newHistory;
-    user.mustChangePassword = false;
-    await this.userRepository.save(user);
-
-    this.logger?.log?.(`Password changed successfully for user: ${user.sub}`);
-
-    // Consume challenge session
-    await this.challengeService.validateAndConsumeSession(
-      challengeSession.sessionToken,
-      AuthChallenge.FORCE_CHANGE_PASSWORD,
-    );
-
-    // Reload user from database to get updated mustChangePassword flag
-    const updatedUser = await this.userRepository.findOne({ where: { sub: user.sub } });
-    if (!updatedUser) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found after password update');
-    }
-
-    // Get client info
-    const clientInfo = this.clientInfoService.get();
-
-    // Read auth context from challenge session metadata
-    const authMethod = (challengeSession.metadata?.authMethod as string) || 'password';
-    const authProvider = challengeSession.metadata?.authProvider as string | undefined;
-    const isSocialLogin = authMethod === 'social';
-
-    // Check for next challenges
-    const response = await this.challengeHelper.determineAuthResponse({
-      user: updatedUser as unknown as IUser,
-      config: this.config,
-      deviceToken: clientInfo.deviceToken,
-      isSocialLogin,
-      skipMFAVerification: false,
-      authProvider,
-    });
-
-    if (response.challengeName) {
-      this.logger?.log?.(`Additional challenge required: ${response.challengeName}`);
-    } else {
-      this.logger?.log?.(`Password changed, auth completed for: ${user.email}`);
-
-      // ============================================================================
-      // Audit: Record successful login after password change
-      // ============================================================================
-      const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-      if (fireAndForget) {
-        this.auditService
-          ?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            authMethod: isSocialLogin ? authProvider || 'social' : 'password',
-            metadata: {
-              completedAfterPasswordChange: true,
-            },
-          })
-          .catch((err) => {
-            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-            this.logger?.error?.(
-              `Failed to record LOGIN_SUCCESS audit event after password change (fire-and-forget): ${errorMessage}`,
-              {
-                error: err,
-                userId: user.id,
-                userSub: user.sub,
-              },
-            );
-          });
-      } else {
-        try {
-          await this.auditService?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            authMethod: isSocialLogin ? authProvider || 'social' : 'password',
-            metadata: {
-              completedAfterPasswordChange: true,
-            },
-          });
-        } catch (auditError) {
-          const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-          this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event after password change: ${errorMessage}`, {
-            error: auditError,
-            userId: user.id,
-          });
-        }
-      }
-    }
-
-    return response;
-  }
-
-  /**
-   * Handle MFA_SETUP_REQUIRED challenge
-   */
-  private async handleMFASetup(challengeSession: any, data: MFASetupResponse): Promise<AuthResponseDTO> {
-    const user = challengeSession.user;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.CHALLENGE_INVALID, 'User not found in challenge session');
-    }
-
-    const method = data.method;
-    const setupData = data.setupData;
-
-    const requestTrace = `${Date.now()}-${Math.random().toString(36).substring(7)}`;
-    this.logger?.log?.(`[${requestTrace}] MFA setup attempt: method=${method}, user=${user.sub}`);
-
-    // Check if MFAService is available
-    if (!this.mfaService) {
-      throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
-    }
-
-    // Get provider
-    const provider = this.mfaService.getProvider(method);
-
-    // Verify setup based on method
-    let deviceId: number;
-
-    try {
-      deviceId = await provider.verifySetup(user, setupData);
-      this.logger?.log?.(`MFA device setup completed: method=${method}, deviceId=${deviceId}`);
-    } catch (error) {
-      this.logger?.warn?.(`MFA setup verification failed: method=${method}, user=${user.sub}`);
-
-      // Increment attempts but don't consume session
-      await this.challengeService.incrementAttempts(challengeSession);
-
-      // Re-throw the error
-      throw error;
-    }
-
-    // Store MFA method in challenge session metadata for CHALLENGE_COMPLETED audit event
-    await this.challengeService.updateMetadata(challengeSession.sessionToken, {
-      mfaMethod: method,
-    });
-
-    // Consume challenge session
-    await this.challengeService.validateAndConsumeSession(
-      challengeSession.sessionToken,
-      AuthChallenge.MFA_SETUP_REQUIRED,
-    );
-
-    // Reload user from database to get updated mfaEnabled flag
-    const updatedUser = await this.userRepository.findOne({ where: { sub: user.sub } });
-    if (!updatedUser) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found after MFA setup');
-    }
-
-    // Get client info
-    const clientInfo = this.clientInfoService.get();
-
-    // Check for next challenges with updated user data
-    // Skip MFA verification because device was already verified during setup
-    const response = await this.challengeHelper.determineAuthResponse({
-      user: updatedUser as unknown as IUser,
-      config: this.config,
-      deviceToken: clientInfo.deviceToken,
-      isSocialLogin: false,
-      skipMFAVerification: true, // Device already verified during setup
-    });
-
-    if (response.challengeName) {
-      this.logger?.log?.(`Additional challenge required: ${response.challengeName}`);
-    } else {
-      this.logger?.log?.(`MFA setup completed, auth completed for: ${user.email}`);
-
-      // ============================================================================
-      // Audit: Record successful login after MFA setup
-      // ============================================================================
-      const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-      if (fireAndForget) {
-        this.auditService
-          ?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            authMethod: 'password',
-            metadata: {
-              completedAfterMFASetup: true,
-            },
-          })
-          .catch((err) => {
-            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
-            this.logger?.error?.(
-              `Failed to record LOGIN_SUCCESS audit event after MFA setup (fire-and-forget): ${errorMessage}`,
-              {
-                error: err,
-                userId: user.id,
-                userSub: user.sub,
-              },
-            );
-          });
-      } else {
-        try {
-          await this.auditService?.recordEvent({
-            userId: user.id,
-            eventType: AuthAuditEventType.LOGIN_SUCCESS,
-            eventStatus: 'SUCCESS',
-            authMethod: 'password',
-            metadata: {
-              completedAfterMFASetup: true,
-            },
-          });
-        } catch (auditError) {
-          const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-          this.logger?.error?.(`Failed to record LOGIN_SUCCESS audit event after MFA setup: ${errorMessage}`, {
-            error: auditError,
-            userId: user.id,
-          });
-        }
-      }
-    }
-
-    return response;
-  }
-
-  // ============================================================================
-  // Challenge Helper Methods
-  // ============================================================================
-
-  /**
-   * Resend verification code for current challenge
-   *
-   * Determines the challenge type from the session and resends the appropriate code:
-   * - VERIFY_EMAIL: Resends email verification code
-   * - VERIFY_PHONE: Resends SMS verification code
-   * - MFA_REQUIRED: Resends MFA code (for SMS MFA)
-   *
-   * Rate limits are enforced internally by the verification services.
-   *
-   * @param session - Challenge session token
-   * @returns Destination info (masked email/phone)
-   * @throws {NAuthException} INVALID_CHALLENGE_SESSION | RATE_LIMIT_* | VALIDATION_FAILED
-   *
-   * @example
-   * ```typescript
-   * const result = await authService.resendCode(session);
-   * // Returns: { destination: 'u***r@example.com' }
-   * ```
-   */
-  async resendCode(dto: ResendCodeDTO): Promise<ResendCodeResponseDTO> {
-    this.logger?.debug?.(`Resending verification code: session=${dto.session}`);
-
-    // Validate session (session must be valid to resend)
-    const challengeSession = await this.challengeService.validateSession(dto.session);
-
-    // Get user from session
-    const user = challengeSession.user;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'Challenge session has no associated user');
-    }
-
-    // Handle based on challenge type
-    switch (challengeSession.challengeName) {
-      case AuthChallenge.VERIFY_EMAIL: {
-        // Resend email verification
-        const resendDto = Object.assign(new ResendVerificationEmailDTO(), { sub: user.sub });
-        await this.emailVerificationService.resendVerificationEmail(resendDto);
-        const maskedEmail = this.maskEmail(user.email);
-        this.logger?.debug?.(`Email verification code resent: user=${user.sub}, email=${maskedEmail}`);
-        return { destination: maskedEmail };
-      }
-
-      case AuthChallenge.VERIFY_PHONE: {
-        // Check if phone already collected
-        if (!user.phone) {
-          throw new NAuthException(
-            AuthErrorCode.VALIDATION_FAILED,
-            'Phone number not yet provided. Submit phone number first.',
-          );
-        }
-
-        if (!this.phoneVerificationService) {
-          throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'Phone verification service is not available');
-        }
-
-        // Resend SMS verification
-        const resendDto = Object.assign(new ResendVerificationSMSDTO(), { sub: user.sub });
-        await this.phoneVerificationService.resendVerificationSMS(resendDto);
-        const maskedPhone = this.maskPhone(user.phone);
-        this.logger?.debug?.(`Phone verification code resent: user=${user.sub}, phone=${maskedPhone}`);
-        return { destination: maskedPhone };
-      }
-
-      case AuthChallenge.MFA_REQUIRED: {
-        // For MFA, we need to know which method is being used
-        // Method is stored in metadata when challenge is created (see auth-challenge-helper.service.ts line 403)
-        // Note: challengeParameters is never populated - only metadata is used
-        const metadata = challengeSession.metadata as { method?: string };
-        const method = metadata?.method;
-
-        if (!method) {
-          throw new NAuthException(
-            AuthErrorCode.VALIDATION_FAILED,
-            'Cannot resend MFA code: method not specified in session',
-          );
-        }
-
-        // SMS and Email MFA support resending codes
-        if (method === 'sms' || method === 'email') {
-          // For SMS, use phone verification service directly to pass challengeSessionId
-          if (method === 'sms' && this.phoneVerificationService) {
-            const smsDto = Object.assign(new SendVerificationSMSDTO(), {
-              sub: user.sub,
-              skipAlreadyVerifiedCheck: true,
-              challengeSessionId: challengeSession.id, // Link resend code to this challenge session
-            });
-            await this.phoneVerificationService.sendVerificationSMS(smsDto);
-            this.logger?.debug?.(`SMS MFA code resent: user=${user.sub}`);
-            // Get masked phone from user or device
-            const maskedPhone = user.phone ? this.maskPhone(user.phone) : '***-***-****';
-            return { destination: maskedPhone };
-          }
-
-          // For Email, use email verification service directly to pass challengeSessionId
-          if (method === 'email' && this.emailVerificationService) {
-            const emailDto = Object.assign(new ResendVerificationEmailDTO(), {
-              sub: user.sub,
-              challengeSessionId: challengeSession.id, // Link resend code to this challenge session
-            });
-            await this.emailVerificationService.resendVerificationEmail(emailDto);
-            this.logger?.debug?.(`Email MFA code resent: user=${user.sub}`);
-            const maskedEmail = user.email ? this.maskEmail(user.email) : 'u***r@example.com';
-            return { destination: maskedEmail };
-          }
-
-          // Fallback to provider if services not available (shouldn't happen)
-          if (!this.mfaService) {
-            throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
-          }
-
-          const provider = this.mfaService.getProvider(method);
-
-          if (!provider.sendChallenge) {
-            throw new NAuthException(
-              AuthErrorCode.VALIDATION_FAILED,
-              `${method.toUpperCase()} MFA provider does not support sending challenges`,
-            );
-          }
-
-          const result = await provider.sendChallenge(user);
-          this.logger?.debug?.(`${method.toUpperCase()} MFA code resent: user=${user.sub}`);
-
-          // Provider returns masked phone or email
-          return { destination: result as string };
-        }
-
-        throw new NAuthException(
-          AuthErrorCode.VALIDATION_FAILED,
-          `Cannot resend code for MFA method '${method}'. Only SMS and Email support code resending.`,
-        );
-      }
-
-      default:
-        throw new NAuthException(
-          AuthErrorCode.VALIDATION_FAILED,
-          `Cannot resend code for challenge type '${challengeSession.challengeName}'`,
-        );
-    }
-  }
-
-  /**
-   * Mask email for display (helper method)
-   */
-  private maskEmail(email: string): string {
-    const [localPart, domain] = email.split('@');
-    if (localPart.length <= 2) {
-      return `${localPart[0]}***@${domain}`;
-    }
-    return `${localPart[0]}***${localPart[localPart.length - 1]}@${domain}`;
-  }
-
-  /**
-   * Mask phone number for display (helper method)
-   */
-  private maskPhone(phone: string): string {
-    const digits = phone.replace(/\D/g, '');
-    const lastFour = digits.slice(-4);
-    return `***-***-${lastFour}`;
-  }
-
-  /**
-   * Registers the current device as trusted for the user (opt-in).
-   *
-   * Only available when rememberDevices is set to 'user_opt_in'. Generates and returns a trusted device token for the device associated with the current authenticated session.
-   *
-   * Session ID is automatically extracted from the JWT token context (via ClientInfoService), similar to how IP address and user agent are handled.
-   *
-   * @returns Object containing the new device token
-   * @throws {NAuthException} If the feature is unavailable, service is not enabled, or session ID is not available
-   *
-   * @example
-   * ```typescript
-   * const result = await authService.trustDevice();
-   * // { deviceToken: 'abc123' }
-   * ```
-   */
-  async trustDevice(): Promise<TrustDeviceResponseDTO> {
-    if (this.config.mfa?.rememberDevices !== 'user_opt_in') {
-      throw new NAuthException(AuthErrorCode.FORBIDDEN, 'Trust device feature is only available in user_opt_in mode');
-    }
-
-    if (!this.trustedDeviceService) {
-      throw new NAuthException(AuthErrorCode.INTERNAL_ERROR, 'Trusted device service not available');
-    }
-
-    // Get sessionId from context (automatically extracted from JWT token)
-    const clientInfo = this.clientInfoService.get();
-    const sessionId = clientInfo.sessionId;
-
-    if (!sessionId) {
-      throw new NAuthException(
-        AuthErrorCode.SESSION_NOT_FOUND,
-        'Session ID not found in request context. Ensure the request is authenticated.',
-      );
-    }
-
-    // Get session to extract device info
-    const session = await this.sessionService.findById(sessionId);
-    if (!session || session.isRevoked) {
-      throw new NAuthException(AuthErrorCode.SESSION_NOT_FOUND, 'Session not found or revoked');
-    }
-
-    // Get user
-    const user = await this.userRepository.findOne({ where: { id: session.userId } });
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    // Check if device is already trusted
-    const userId = typeof user.id === 'number' ? user.id : parseInt(String(user.id), 10);
-    if (clientInfo.deviceToken) {
-      const isAlreadyTrusted = await this.trustedDeviceService.isDeviceTrusted(clientInfo.deviceToken, userId);
-      if (isAlreadyTrusted) {
-        this.logger?.debug?.(`Device already trusted for user ${user.sub}`);
-        return { deviceToken: clientInfo.deviceToken };
-      }
-      // If device token exists but not trusted, revoke it first (may be expired/invalid)
-      try {
-        await this.trustedDeviceService.revokeTrustedDevice(clientInfo.deviceToken, userId);
-        this.logger?.debug?.(`Revoked existing untrusted device token for user ${user.sub}`);
-      } catch {
-        // Non-blocking - may not exist
-      }
-    }
-
-    // Create trusted device token using session device info
-    const deviceToken = await this.trustedDeviceService.createTrustedDevice(
-      userId,
-      session.deviceName || clientInfo.deviceName,
-      session.deviceType || clientInfo.deviceType,
-      session.ipAddress || clientInfo.ipAddress,
-      session.userAgent || clientInfo.userAgent,
-      clientInfo.platform,
-      clientInfo.browser,
-    );
-
-    this.logger?.log?.(`Device trusted for user ${user.sub} (user opt-in)`);
-
-    // ============================================================================
-    // Audit: Record device trust event
-    // ============================================================================
-    try {
-      // Ensure userId is a number for audit
-      const userId = typeof user.id === 'number' ? user.id : parseInt(String(user.id), 10);
-
-      await this.auditService?.recordEvent({
-        userId,
-        eventType: AuthAuditEventType.DEVICE_TRUSTED,
-        eventStatus: 'SUCCESS',
-        // Override deviceId with the newly created device token
-        deviceId: deviceToken,
-        sessionId: session.id,
-        description: `Device trusted by user (opt-in) - ${session.deviceName || 'Unknown device'}`,
-        // Client info (deviceName, deviceType, etc.) automatically included from context
-        metadata: {
-          rememberDeviceDays: this.config.mfa?.rememberDeviceDays || 30,
-          trustedUntil: new Date(
-            Date.now() + (this.config.mfa?.rememberDeviceDays || 30) * 24 * 60 * 60 * 1000,
-          ).toISOString(),
-        },
-      });
-    } catch (auditError) {
-      // Non-blocking: Log but continue
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record DEVICE_TRUSTED audit event: ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    return { deviceToken };
-  }
-
-  /**
-   * Check if the current device is trusted
-   *
-   * Returns whether the device associated with the current authenticated session
-   * is trusted. Works for both cookies mode (reads from httpOnly cookie) and
-   * JSON mode (reads from X-Device-Token header).
-   *
-   * This endpoint validates the device token on the server side and checks:
-   * - Device token exists and is valid
-   * - Device token matches a trusted device record in the database
-   * - Trust has not expired
-   *
-   * @returns Object containing the trusted status
-   * @throws {NAuthException} If the session is not found or user is not authenticated
-   *
-   * @example
-   * ```typescript
-   * const result = await authService.isTrustedDevice();
-   * // { trusted: true }
-   * ```
-   */
-  async isTrustedDevice(): Promise<IsTrustedDeviceResponseDTO> {
-    if (!this.trustedDeviceService) {
-      // If trusted device service is not available, device is not trusted
-      return { trusted: false };
-    }
-
-    // Get sessionId from context (automatically extracted from JWT token)
-    const clientInfo = this.clientInfoService.get();
-    const sessionId = clientInfo.sessionId;
-
-    if (!sessionId) {
-      throw new NAuthException(
-        AuthErrorCode.SESSION_NOT_FOUND,
-        'Session ID not found in request context. Ensure the request is authenticated.',
-      );
-    }
-
-    // Get session to extract user
-    const session = await this.sessionService.findById(sessionId);
-    if (!session || session.isRevoked) {
-      throw new NAuthException(AuthErrorCode.SESSION_NOT_FOUND, 'Session not found or revoked');
-    }
-
-    // Get user
-    const user = await this.userRepository.findOne({ where: { id: session.userId } });
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    // Check if device is trusted
-    const userId = typeof user.id === 'number' ? user.id : parseInt(String(user.id), 10);
-    const deviceToken = clientInfo.deviceToken;
-
-    if (!deviceToken) {
-      return { trusted: false };
-    }
-
-    const isTrusted = await this.trustedDeviceService.isDeviceTrusted(deviceToken, userId);
-    return { trusted: isTrusted };
-  }
-
-  /**
-   * Refresh the access token using a refresh token.
-   *
-   * Handles secure token rotation with distributed locking, reuse detection,
-   * and family revocation to prevent race conditions and replay attacks.
-   *
-   * @param refreshToken - The refresh token issued to the client
-   * @returns Newly generated access and refresh tokens
-   * @throws {NAuthException} If the session is not found, revoked, or refresh is abused
-   *
-   * @example
-   * ```typescript
-   * const tokens = await authService.refreshToken(refreshToken);
-   * ```
-   */
-  async refreshToken(dto: RefreshTokenDTO): Promise<TokenResponse> {
-    const tokenHash = this.jwtService.hashToken(dto.refreshToken);
-
-    // ============================================================================
-    // CRITICAL SECURITY FIX #1 & #2: Distributed Lock + Reuse Detection
-    // ============================================================================
-
-    // CRITICAL: We need to get session ID for locking, but we must lock BEFORE validation
-    // to prevent race conditions. So we do a quick, lightweight lookup first.
-    // Find session by refresh token hash - this is fast and allows us to get session ID
-    const session = await this.sessionService.findByRefreshToken(tokenHash);
-
-    if (!session || session.isRevoked) {
-      // Validate token to get user info for error message
-      const validation = await this.jwtService.validateRefreshToken(dto.refreshToken);
-      const userId = validation.payload?.sub || 'unknown';
-      this.logger?.debug?.(
-        `Session not found or revoked for user ${userId}. Possible issue where token are not cleared on logout`,
-      );
-      throw new NAuthException(AuthErrorCode.SESSION_NOT_FOUND, 'Session not found or revoked');
-    }
-
-    // Acquire distributed lock using SESSION ID (not token hash)
-    // THIS MUST HAPPEN BEFORE VALIDATION to prevent race conditions
-    // where multiple requests validate the same token before any lock is acquired
-    const lockKey = `session-refresh:${session.id}`;
-    this.logger?.debug?.(
-      `[REFRESH DEBUG] Attempting to acquire lock ${lockKey} for token hash ${tokenHash.substring(0, 16)}...`,
-    );
-    let lockAcquired = false;
-    try {
-      const lockStartTime = Date.now();
-      lockAcquired = await this.sessionService.acquireRefreshLock(lockKey, 10000);
-      const lockDuration = Date.now() - lockStartTime;
-
-      if (!lockAcquired) {
-        this.logger?.warn?.(
-          `[REFRESH DEBUG] Lock ${lockKey} NOT acquired - refresh already in progress for session ${session.id}`,
-        );
-        throw new NAuthException(AuthErrorCode.RATE_LIMIT_LOGIN, 'Token refresh already in progress', {
-          retryAfter: 5,
-        });
-      }
-
-      this.logger?.debug?.(
-        `[REFRESH DEBUG] Lock ${lockKey} acquired successfully in ${lockDuration}ms for token hash ${tokenHash.substring(0, 16)}...`,
-      );
-
-      // CRITICAL: Check for token reuse IMMEDIATELY after acquiring lock
-      // If same session + cookie race → return current tokens (don't reissue)
-      // If different session → invalidate that session and reject (attack)
-      if (this.config.jwt.refreshToken.reuseDetection) {
-        const isAlreadyUsed = await this.sessionService.isRefreshTokenUsed(tokenHash);
-        if (isAlreadyUsed) {
-          // Decode token to get sessionId from JWT payload (without full validation)
-          // This allows us to check if the token belongs to the session we found
-          const tokenPayload = this.jwtService.decodeToken(dto.refreshToken);
-          const tokenSessionId = tokenPayload?.sessionId;
-
-          // Get current session state to ensure it's still valid
-          const currentSession = (await this.sessionService.findByIdLight(session.id)) as unknown as ISession | null;
-          if (!currentSession || currentSession.isRevoked) {
-            throw new NAuthException(AuthErrorCode.SESSION_NOT_FOUND, 'Session not found or revoked');
-          }
-
-          // Check if token's sessionId matches the session we found
-          // If they match → cookie race (same session)
-          // If they don't match → attack (token stolen from different session)
-          if (tokenSessionId && tokenSessionId === session.id.toString()) {
-            // Same session - this is a cookie race condition
-            // Return the current valid tokens (user already has them from first request)
-
-            this.logger?.debug?.(
-              `[REFRESH DEBUG] Token hash ${tokenHash.substring(0, 16)}... already used for same session ${session.id} - cookie race detected, returning current tokens`,
-            );
-
-            // Get user info
-            const user = (await this.userRepository.findOne({
-              where: { id: currentSession.userId },
-            })) as IUser | null;
-
-            if (!user) {
-              throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-            }
-
-            // Generate tokens from current session state (same as what the first request returned)
-            // These will match what the user already has, so no change needed
-            // Note: deviceId not included in token - session.deviceId is source of truth
-            const newTokens = await this.jwtService.generateTokenPair({
-              userId: user.sub,
-              email: user.email,
-              sessionId: currentSession.id.toString(),
-              tokenFamily: currentSession.tokenFamily,
-            });
-
-            // Update session with these tokens (they're already there, but ensures consistency)
-            await this.sessionService.updateTokens(
-              currentSession.id,
-              this.jwtService.hashToken(newTokens.accessToken),
-              this.jwtService.hashToken(newTokens.refreshToken),
-            );
-
-            // Decode tokens to get expiry times
-            const accessTokenValidation = await this.jwtService.validateAccessToken(newTokens.accessToken);
-            const refreshTokenValidation = await this.jwtService.validateRefreshToken(newTokens.refreshToken);
-
-            // Return success with current tokens
-            return {
-              accessToken: newTokens.accessToken,
-              refreshToken: newTokens.refreshToken,
-              accessTokenExpiresAt: accessTokenValidation.payload?.exp || 0,
-              refreshTokenExpiresAt: refreshTokenValidation.payload?.exp || 0,
-            };
-          } else {
-            // Different session - this is an attack!
-            // A refresh token from one session cannot be used by another session
-            this.logger?.error?.(
-              `[REFRESH DEBUG] Token hash ${tokenHash.substring(0, 16)}... already used for different session - ATTACK DETECTED! Token sessionId: ${tokenSessionId}, Found session: ${session.id}. Revoking session ${session.id}`,
-            );
-
-            // Revoke the session that's trying to use a stolen token
-            await this.sessionService.revokeSession(session.id, 'Token reuse detected - possible token theft');
-
-            // Audit the attack
-            let userForAudit: IUser | null = null;
-            try {
-              userForAudit = (await this.userRepository.findOne({
-                where: { id: session.userId },
-              })) as IUser | null;
-              if (userForAudit) {
-                await this.auditService?.recordEvent({
-                  userId: userForAudit.id,
-                  eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
-                  eventStatus: 'SUSPICIOUS',
-                  riskFactor: 90,
-                  riskFactors: [RiskFactor.TOKEN_THEFT_ATTEMPT, RiskFactor.REFRESH_TOKEN_REUSE_DIFFERENT_SESSION],
-                  reason: 'Refresh token reuse from different session',
-                  // Client info automatically included from context
-                  description:
-                    'Refresh token from another session attempted to be used. Session revoked as security measure.',
-                  metadata: {
-                    sessionId: session.id,
-                    tokenSessionId,
-                    tokenHash: `${tokenHash.substring(0, 16)}...`,
-                    detectedAt: new Date().toISOString(),
-                    action: 'session_revoked',
-                  },
-                });
-              }
-            } catch (auditError) {
-              const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-              this.logger?.error?.(`Failed to record SUSPICIOUS_ACTIVITY audit event (token reuse): ${errorMessage}`, {
-                error: auditError,
-                userId: userForAudit?.id || session.userId,
-              });
-            }
-
-            throw new NAuthException(AuthErrorCode.TOKEN_INVALID, 'Refresh token has already been used');
-          }
-        }
-      }
-
-      // NOW validate the refresh token (after lock is acquired and reuse check)
-      // This ensures only one request can validate at a time per session
-      const validation = await this.jwtService.validateRefreshToken(dto.refreshToken);
-
-      if (!validation.valid || !validation.payload) {
-        throw new NAuthException(AuthErrorCode.TOKEN_INVALID, 'Invalid refresh token');
-      }
-
-      const payload = validation.payload;
-
-      // Re-check session after acquiring lock (it might have been revoked/updated)
-      // Since we have the lock, no other request can modify this session, but it might have been revoked
-      // We already have currentSession from the early reuse check, but re-fetch to ensure it's still valid
-      const lockedSession = (await this.sessionService.findByIdLight(session.id)) as unknown as ISession | null;
-      if (!lockedSession || lockedSession.isRevoked || lockedSession.id !== session.id) {
-        this.logger?.debug?.(
-          `Session changed after lock acquisition for user ${payload.sub}. Session may have been revoked.`,
-        );
-        throw new NAuthException(AuthErrorCode.SESSION_NOT_FOUND, 'Session not found or revoked');
-      }
-
-      // ============================================================================
-      // NOTE: We still do the atomic mark operation below as a double-check
-      // The early check above handles cookie race conditions where old tokens
-      // are sent before new cookies are received
-      // ============================================================================
-
-      // Mark token as used BEFORE generating new tokens (prevents reuse)
-      if (this.config.jwt.refreshToken.reuseDetection) {
-        const refreshTokenTTL = this.jwtService.getRefreshTokenTTL();
-        const marked = await this.sessionService.markRefreshTokenAsUsed(tokenHash, refreshTokenTTL);
-
-        if (!marked) {
-          // Token was already marked as used - reuse detected!
-          this.logger?.error?.(
-            `Token reuse detected for user ${payload.sub} - atomic mark failed, revoking entire token family ${payload.tokenFamily}`,
-          );
-
-          // Audit the reuse attempt
-          try {
-            const userForAudit = (await this.userRepository.findOne({
-              where: { sub: payload.sub },
-            })) as IUser | null;
-            if (userForAudit) {
-              await this.auditService?.recordEvent({
-                userId: userForAudit.id,
-                eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
-                eventStatus: 'SUSPICIOUS',
-                riskFactor: 75,
-                riskFactors: [RiskFactor.TOKEN_REUSE_ATTEMPT],
-                reason: 'Token reuse attempt blocked',
-                // Client info automatically included from context
-                description:
-                  'Refresh token reuse attempt detected via atomic operation. Legitimate user session preserved.',
-                metadata: {
-                  tokenFamily: payload.tokenFamily,
-                  detectedAt: new Date().toISOString(),
-                  action: 'reuse_blocked_atomic',
-                },
-              });
-            }
-          } catch (auditError) {
-            this.logger?.warn?.('Failed to record SUSPICIOUS_ACTIVITY audit event', { error: auditError });
-          }
-
-          throw new NAuthException(AuthErrorCode.TOKEN_INVALID, 'Refresh token has already been used');
-        }
-
-        this.logger?.debug?.(`Marked refresh token as used for session ${lockedSession.id}`);
-      }
-
-      // Generate new token pair with same family
-      // Note: deviceId not included in token - session.deviceId is source of truth
-      const newTokens = await this.jwtService.generateTokenPair({
-        userId: payload.sub,
-        email: payload.email,
-        sessionId: lockedSession.id.toString(), // Convert integer to string for JWT
-        tokenFamily: payload.tokenFamily,
-      });
-
-      // Update session with new token hashes (token rotation)
-      // This automatically invalidates the old tokens as they won't match the session
-      await this.sessionService.updateTokens(
-        lockedSession.id,
-        this.jwtService.hashToken(newTokens.accessToken),
-        this.jwtService.hashToken(newTokens.refreshToken),
-      );
-
-      this.logger?.log?.(`Token refreshed successfully for user ${payload.sub}`);
-
-      // Decode new tokens to get expiry times
-      const accessTokenValidation = await this.jwtService.validateAccessToken(newTokens.accessToken);
-      const refreshTokenValidation = await this.jwtService.validateRefreshToken(newTokens.refreshToken);
-
-      return {
-        accessToken: newTokens.accessToken,
-        refreshToken: newTokens.refreshToken,
-        accessTokenExpiresAt: accessTokenValidation.payload?.exp || 0,
-        refreshTokenExpiresAt: refreshTokenValidation.payload?.exp || 0,
-      };
-    } finally {
-      // Always release lock, even if error occurs
-      // Only release if we successfully acquired it
-      if (lockAcquired) {
-        await this.sessionService.releaseRefreshLock(lockKey);
-        this.logger?.debug?.(`[REFRESH DEBUG] Released lock ${lockKey}`);
-      }
-    }
-  }
-
-  // ============================================================================
-  // Logout
-  // ============================================================================
-
-  /**
-   * Logout user (revoke session)
-   *
-   * Session ID is automatically extracted from the JWT token context (via ClientInfoService), similar to how IP address and user agent are handled.
-   *
-   * @param dto - Logout options (forgetMe flag)
-   * @returns Success status
-   * @throws {NAuthException} If session ID is not available in request context
-   */
-  async logout(dto: LogoutDTO): Promise<LogoutResponseDTO> {
-    // Get sessionId from context (automatically extracted from JWT token)
-    const clientInfo = this.clientInfoService.get();
-    let sessionId = clientInfo.sessionId;
-
-    // Fallback: Try to get sessionId from JWT payload in context
-    if (!sessionId) {
-      const jwtPayload = ContextStorage.get<any>('JWT_PAYLOAD');
-      if (jwtPayload?.sessionId) {
-        // Parse sessionId to number (JWT payload has it as string)
-        const sessionIdStr = String(jwtPayload.sessionId);
-        const sessionIdNumber = parseInt(sessionIdStr, 10);
-        if (!isNaN(sessionIdNumber) && sessionIdNumber > 0) {
-          sessionId = sessionIdNumber;
-          // Update CLIENT_INFO in context for future use
-          const clientInfoInContext = ContextStorage.get<any>('CLIENT_INFO');
-          if (clientInfoInContext) {
-            clientInfoInContext.sessionId = sessionIdNumber;
-            ContextStorage.set('CLIENT_INFO', clientInfoInContext);
-          }
-        }
-      }
-    }
-
-    if (!sessionId) {
-      throw new NAuthException(
-        AuthErrorCode.SESSION_NOT_FOUND,
-        'Session ID not found in request context. Ensure the request is authenticated.',
-      );
-    }
-
-    // Prepare metadata for audit trail
-    const auditMetadata: Record<string, unknown> | undefined = dto.forgetMe
-      ? {
-          deviceForgotten: true,
-          reason: 'User requested device to be forgotten on logout',
-        }
-      : undefined;
-
-    await this.sessionService.revokeSession(sessionId, 'User logout', auditMetadata);
-
-    // If forgetMe is true, revoke trusted device
-    if (
-      dto.forgetMe &&
-      this.config.mfa?.rememberDevices &&
-      this.config.mfa?.rememberDevices !== 'never' &&
-      this.trustedDeviceService
-    ) {
-      if (clientInfo.deviceToken) {
-        try {
-          // Get session to get userId
-          const session = await this.sessionService.findById(sessionId);
-          if (session) {
-            await this.trustedDeviceService.revokeTrustedDevice(clientInfo.deviceToken, session.userId);
-            this.logger?.log?.(`Revoked trusted device token for user (forgetMe=true)`);
-
-            // Get user for audit
-            const user = await this.userRepository.findOne({ where: { id: session.userId } });
-            if (user) {
-              // ============================================================================
-              // Audit: Record device untrust event
-              // ============================================================================
-              try {
-                // Ensure userId is a number for audit
-                const userId = typeof user.id === 'number' ? user.id : parseInt(String(user.id), 10);
-
-                await this.auditService?.recordEvent({
-                  userId,
-                  eventType: AuthAuditEventType.DEVICE_UNTRUSTED,
-                  eventStatus: 'SUCCESS',
-                  sessionId: session.id,
-                  description: `Device untrusted by user (forgetMe=true) - ${session.deviceName || 'Unknown device'}`,
-                  // Client info (deviceId, deviceName, deviceType, etc.) automatically included from context
-                  metadata: {
-                    reason: 'user_logout_forget_me',
-                  },
-                });
-              } catch (auditError) {
-                // Non-blocking: Log but continue
-                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                this.logger?.error?.(`Failed to record DEVICE_UNTRUSTED audit event: ${errorMessage}`, {
-                  error: auditError,
-                  userId: session.userId,
-                });
-              }
-            }
-          }
-        } catch (error) {
-          // Non-blocking: Log but continue
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-          this.logger?.debug?.(`Failed to revoke trusted device token on logout: ${errorMessage}`, { error });
-        }
-      }
-    }
-
-    // ============================================================================
-    // Automatically Clear Auth Cookies (if using cookie-based token delivery)
-    // ============================================================================
-    const response = this.clientInfoService.getResponse();
-    if (response && this.config.tokenDelivery?.method !== 'json') {
-      this.clearAuthCookies(response, dto.forgetMe ?? false);
-      this.logger?.debug?.('Auth cookies cleared automatically on logout');
-    }
-
-    return { success: true };
-  }
-
-  /**
-   * Clear authentication cookies from response
-   *
-   * @param response - HTTP response object with clearCookie method
-   * @param forgetDevice - Whether to also clear device token cookie
-   * @private
-   */
-  private clearAuthCookies(
-    response: { clearCookie?: (name: string, options?: unknown) => void },
-    forgetDevice: boolean,
-  ): void {
-    if (!response.clearCookie) {
-      return; // Response doesn't support cookie clearing (shouldn't happen)
-    }
-
-    const cookieOptions = this.config.tokenDelivery?.cookieOptions || {};
-    const prefix = this.config.tokenDelivery?.cookieNamePrefix || 'nauth';
-
-    // Clear access and refresh tokens
-    response.clearCookie(`${prefix}_access_token`, cookieOptions);
-    response.clearCookie(`${prefix}_refresh_token`, cookieOptions);
-
-    // Clear CSRF token cookie (httpOnly: false, so it can be cleared)
-    // Use the same cookie options but with httpOnly: false to match how it was set
-    const csrfCookieOptions = {
-      ...cookieOptions,
-      httpOnly: false, // CSRF token cookie is not httpOnly
-    };
-    const csrfCookieName = this.config.security?.csrf?.cookieName || `${prefix}_csrf_token`;
-    response.clearCookie(csrfCookieName, csrfCookieOptions);
-
-    // Clear device token if forgetting device
-    if (forgetDevice) {
-      response.clearCookie(`${prefix}_device_token`, cookieOptions);
-    }
-  }
-
-  /**
-   * Global signout (revoke all user sessions)
-   * @param sub - External user identifier (sub/UUID)
-   * @returns Number of sessions revoked
-   */
-  async logoutAll(dto: LogoutAllDTO): Promise<LogoutAllResponseDTO> {
-    // Get user by sub to get internal id
-    const user = (await this.userRepository.findOne({ where: { sub: dto.sub } })) as IUser | null;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    // Use internal id for session queries
-    const revokedCount = await this.sessionService.revokeAllUserSessions(user.id, 'Global signout');
-
-    // Revoke all trusted devices if forgetDevices flag is set
-    let revokedDevicesCount = 0;
-    let revokedDevices: Array<{
-      id: number | string;
-      deviceName: string | null;
-      lastUsedAt: Date | null;
-      trustedUntil: Date | null;
-    }> = [];
-    if (
-      dto.forgetDevices &&
-      this.config.mfa?.rememberDevices &&
-      this.config.mfa?.rememberDevices !== 'never' &&
-      this.trustedDeviceService
-    ) {
-      try {
-        const deviceRevocationResult = await this.trustedDeviceService.revokeAllTrustedDevices(user.id);
-        revokedDevicesCount = deviceRevocationResult.revokedCount;
-        revokedDevices = deviceRevocationResult.devices;
-        this.logger?.log?.(
-          `Revoked ${revokedDevicesCount} trusted device(s) for user ${user.sub} (forgetDevices=true)`,
-        );
-
-        // Record audit event for device revocation
-        if (revokedDevicesCount > 0 && this.auditService) {
-          try {
-            const userId = typeof user.id === 'number' ? user.id : parseInt(String(user.id), 10);
-            await this.auditService.recordEvent({
-              userId,
-              eventType: AuthAuditEventType.DEVICE_UNTRUSTED,
-              eventStatus: 'SUCCESS',
-              description: `Global signout: All trusted devices revoked (${revokedDevicesCount} device(s))`,
-              metadata: {
-                reason: 'global_logout_forget_devices',
-                revokedDevicesCount,
-                devices: revokedDevices.map((d) => ({
-                  id: d.id,
-                  deviceName: d.deviceName,
-                  lastUsedAt: d.lastUsedAt?.toISOString() || null,
-                  trustedUntil: d.trustedUntil?.toISOString() || null,
-                })),
-              },
-            });
-          } catch (auditError) {
-            // Non-blocking: Log but continue
-            const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-            this.logger?.error?.(`Failed to record DEVICE_UNTRUSTED audit event: ${errorMessage}`, {
-              error: auditError,
-              userId: user.id,
-            });
-          }
-        }
-      } catch (error) {
-        // Non-blocking: Log but continue
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        this.logger?.debug?.(`Failed to revoke trusted devices on global logout: ${errorMessage}`, { error });
-      }
-    }
-
-    // ============================================================================
-    // Audit: Record GLOBAL_SIGNOUT event (individual SESSION_REVOKED events recorded in SessionService)
-    // ============================================================================
-    if (this.auditService && revokedCount > 0) {
-      try {
-        const userId = typeof user.id === 'number' ? user.id : parseInt(String(user.id), 10);
-        const description =
-          dto.forgetDevices && revokedDevicesCount > 0
-            ? `Global signout: ${revokedCount} session(s) revoked, ${revokedDevicesCount} trusted device(s) forgotten`
-            : `Global signout: ${revokedCount} session(s) revoked`;
-
-        await this.auditService.recordEvent({
-          userId,
-          eventType: AuthAuditEventType.GLOBAL_SIGNOUT,
-          eventStatus: 'INFO',
-          reason: 'Global signout',
-          description,
-          metadata: {
-            revokedCount,
-            forgetDevices: dto.forgetDevices ?? false,
-            ...(dto.forgetDevices && revokedDevicesCount > 0
-              ? {
-                  revokedDevicesCount,
-                  devices: revokedDevices.map((d) => ({
-                    id: d.id,
-                    deviceName: d.deviceName,
-                    lastUsedAt: d.lastUsedAt?.toISOString() || null,
-                    trustedUntil: d.trustedUntil?.toISOString() || null,
-                  })),
-                }
-              : {}),
-          },
-        });
-      } catch (auditError) {
-        // Non-blocking: Log but continue (individual SESSION_REVOKED events already recorded in SessionService)
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record GLOBAL_SIGNOUT audit event: ${errorMessage}`, {
-          error: auditError,
-          userId: user.id,
-        });
-      }
-    }
-
-    // ============================================================================
-    // Automatically Clear Auth Cookies (if using cookie-based token delivery)
-    // ============================================================================
-    const response = this.clientInfoService.getResponse();
-    if (response && this.config.tokenDelivery?.method !== 'json') {
-      // Clear auth cookies
-      // If forgetDevices is true, also clear device token cookie
-      this.clearAuthCookies(response, dto.forgetDevices ?? false);
-      this.logger?.debug?.('Auth cookies cleared automatically on global logout');
-    }
-
-    return { revokedCount };
-  }
-
-  // ============================================================================
-  // Password Management
-  // ============================================================================
-
-  /**
-   * Change the password for an existing user.
-   *
-   * Verifies the current password, validates the new password,
-   * checks password reuse policy, and updates the user's password hash and history.
-   * Executes configured pre-change hooks if provided.
-   *
-   * @param sub - External user identifier (sub/UUID)
-   * @param dto - ChangePasswordDTO containing old and new password
-   * @returns void
-   * @throws {NAuthException} If the user is not found, current password is incorrect, the new password is weak, password reuse is detected, or password change is disallowed by hooks.
-   *
-   * @example
-   * ```typescript
-   * await authService.changePassword('user-uuid', {
-   *   oldPassword: 'currentPass123!',
-   *   newPassword: 'newStr0ngPass!@#',
-   * });
-   * ```
-   */
-  async changePassword(dto: ChangePasswordRequestDTO): Promise<ChangePasswordResponseDTO> {
-    // Get user by sub
-    const user = (await this.userRepository.findOne({ where: { sub: dto.sub } })) as IUser | null;
-
-    if (!user || !user.passwordHash) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    // Execute beforePasswordChange hook (use sub for external API)
-    if (this.config.hooks?.beforePasswordChange) {
-      const result = await this.config.hooks.beforePasswordChange(dto.sub, dto.oldPassword);
-      if (result === false) {
-        throw new NAuthException(AuthErrorCode.PASSWORD_CHANGE_NOT_ALLOWED, 'Password change not allowed');
-      }
-    }
-
-    // Verify old password
-    const isValid = await this.passwordService.verifyPassword(dto.oldPassword, user.passwordHash);
-
-    if (!isValid) {
-      throw new NAuthException(AuthErrorCode.PASSWORD_INCORRECT, 'Current password is incorrect');
-    }
-
-    // Validate new password
-    const validation = await this.passwordService.validatePassword(dto.newPassword, {
-      email: user.email,
-      username: user.username || undefined,
-    });
-
-    if (!validation.valid) {
-      throw new NAuthException(AuthErrorCode.WEAK_PASSWORD, validation.errors.join(', '), {
-        errors: validation.errors,
-      });
-    }
-
-    // Check password history
-    if (this.config.password?.historyCount) {
-      // Include current password hash in the check to prevent immediate reuse
-      const historyToCheck = user.passwordHistory || [];
-      const allPreviousPasswords = user.passwordHash ? [user.passwordHash, ...historyToCheck] : historyToCheck;
-
-      const isReused = await this.passwordService.isPasswordInHistory(dto.newPassword, allPreviousPasswords);
-
-      if (isReused) {
-        throw new NAuthException(
-          AuthErrorCode.PASSWORD_REUSED,
-          'You have used this password recently. Please choose a different password.',
-        );
-      }
-    }
-
-    // Hash new password
-    const newHash = await this.passwordService.hashPassword(dto.newPassword);
-
-    // Update password history
-    const newHistory = this.passwordService.addToHistory(user.passwordHistory || [], user.passwordHash);
-
-    // Update user - use save() instead of update() to ensure TypeORM properly serializes simple-array fields
-    user.passwordHash = newHash;
-    user.passwordChangedAt = new Date();
-    user.passwordHistory = newHistory;
-    await this.userRepository.save(user);
-
-    // Execute afterPasswordChange hook (use sub for external API)
-    if (this.config.hooks?.afterPasswordChange) {
-      await this.config.hooks.afterPasswordChange(dto.sub);
-    }
-
-    // Optionally revoke all sessions (force re-login) - use internal id
-    await this.sessionService.revokeAllUserSessions(user.id, 'Password changed');
-
-    // ============================================================================
-    // Audit: Record password change
-    // ============================================================================
-    try {
-      await this.auditService?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.PASSWORD_CHANGED,
-        eventStatus: 'SUCCESS',
-        // Client info automatically included from context
-      });
-    } catch (auditError) {
-      // Non-blocking: Log but continue
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record PASSWORD_CHANGED audit event: ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    return { success: true };
-  }
-
-  /**
-   * Update user profile attributes.
-   *
-   * Updates user fields (name, email, phone, username, metadata) and enforces unique constraints and verification rules.
-   *
-   * @param sub - User sub/UUID
-   * @param updateData - User fields to update
-   * @returns Updated user object
-   * @throws {NAuthException} If user not found or unique constraint violated
-   *
-   * @example
-   * await authService.updateUserAttributes(sub, { email: 'test@example.com' });
-   */
-  async updateUserAttributes(dto: UpdateUserAttributesRequestDTO): Promise<UserResponseDto> {
-    // Find user by sub (external identifier)
-    const user = (await this.userRepository.findOne({ where: { sub: dto.sub } })) as IUser | null;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    // Check for uniqueness constraints - use internal id
-    await this.validateUniquenessConstraints(user.id, dto);
-
-    // Prepare update object
-    const updateFields: Partial<IUser> = {};
-
-    // Update basic fields if provided
-    if (dto.firstName !== undefined) {
-      updateFields.firstName = dto.firstName;
-    }
-    if (dto.lastName !== undefined) {
-      updateFields.lastName = dto.lastName;
-    }
-    if (dto.username !== undefined) {
-      updateFields.username = dto.username;
-    }
-    if (dto.email !== undefined) {
-      const oldEmail = user.email;
-      updateFields.email = dto.email;
-      // Reset email verification if email changed (unless retainVerification is true)
-      if (dto.email !== user.email) {
-        if (!dto.retainVerification) {
-          updateFields.isEmailVerified = false;
-        } else {
-          // Explicitly retain current verification status
-          updateFields.isEmailVerified = user.isEmailVerified;
-        }
-
-        // ============================================================================
-        // MFA Device Management: Handle Email MFA devices when email changes
-        // ============================================================================
-        // When email address changes, Email MFA devices become invalid.
-        // We deactivate them and check if user has any other active MFA devices.
-        // If Email was the only MFA method, user will need to set up MFA again.
-        // This happens automatically via challenge system at next login.
-        if (oldEmail && this.mfaDeviceRepository) {
-          try {
-            // Find all Email MFA devices (email field may be null in legacy devices)
-            const emailDevices = (await this.mfaDeviceRepository.find({
-              where: {
-                userId: user.id,
-                type: MFAMethod.EMAIL,
-                isActive: true,
-              },
-            } as Record<string, unknown>)) as unknown as Array<Record<string, unknown>>;
-
-            if (emailDevices.length > 0) {
-              this.logger?.log?.(
-                `Deleting ${emailDevices.length} Email MFA device(s) for user ${user.sub} due to email address change (old: ${oldEmail}, new: ${dto.email})`,
-              );
-
-              // Delete all Email devices (can't be reactivated with old email)
-              for (const device of emailDevices) {
-                const deviceId = (device as Record<string, unknown>).id as number;
-                await this.mfaDeviceRepository.delete(deviceId);
-              }
-
-              // Record audit event for removed Email MFA devices
-              if (this.auditService) {
-                try {
-                  await this.auditService.recordEvent({
-                    userId: user.id,
-                    eventType: AuthAuditEventType.MFA_DEVICE_REMOVED,
-                    eventStatus: 'INFO',
-                    reason: 'email_changed',
-                    description: `Email MFA device(s) removed due to email address change (${oldEmail} → ${dto.email})`,
-                    metadata: {
-                      method: MFAMethod.EMAIL,
-                      deletedCount: emailDevices.length,
-                      oldEmail,
-                      newEmail: dto.email,
-                      reason: 'email_address_changed_requires_reverification',
-                    },
-                  });
-                } catch (auditError) {
-                  const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                  this.logger?.error?.(
-                    `Failed to record MFA_DEVICE_REMOVED audit event for email change: ${errorMessage}`,
-                    { error: auditError, userId: user.id },
-                  );
-                }
-              }
-
-              // Check if user has any other active MFA devices
-              const allActiveDevices = (await this.mfaDeviceRepository.find({
-                where: {
-                  userId: user.id,
-                  isActive: true,
-                },
-              } as Record<string, unknown>)) as unknown as Array<Record<string, unknown>>;
-
-              // If no active devices remain and user had MFA enabled, disable MFA
-              if (allActiveDevices.length === 0 && user.mfaEnabled) {
-                updateFields.mfaEnabled = false;
-                updateFields.mfaMethods = [];
-                updateFields.preferredMfaMethod = null;
-                this.logger?.log?.(
-                  `MFA disabled for user ${user.sub} - no active MFA devices remaining after email change`,
-                );
-              } else {
-                this.logger?.log?.(
-                  `User ${user.sub} still has ${allActiveDevices.length} active MFA device(s) - MFA remains enabled`,
-                );
-              }
-            }
-          } catch (error: unknown) {
-            // Log error but don't fail the email update
-            // This handles cases where MFA module is not imported (mfaDeviceRepository might not be available)
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            this.logger?.warn?.(
-              `Failed to handle MFA device deactivation during email change for user ${user.sub}: ${errorMessage}`,
-            );
-          }
-        }
-      }
-    }
-    if (dto.phone !== undefined) {
-      const oldPhone = user.phone;
-      updateFields.phone = dto.phone;
-      // Reset phone verification if phone changed (unless retainVerification is true)
-      if (dto.phone !== user.phone) {
-        if (!dto.retainVerification) {
-          updateFields.isPhoneVerified = false;
-        } else {
-          // Explicitly retain current verification status
-          updateFields.isPhoneVerified = user.isPhoneVerified;
-        }
-
-        // ============================================================================
-        // MFA Device Management: Handle SMS MFA devices when phone changes
-        // ============================================================================
-        // When phone number changes, SMS MFA devices become invalid.
-        // We delete them and check if user has any other active MFA devices.
-        // If SMS was the only MFA method, user will need to set up MFA again.
-        // This happens automatically via challenge system at next login.
-        if (oldPhone && this.mfaDeviceRepository) {
-          try {
-            // Find all SMS MFA devices (SMS MFA is tied to user.phone, not device phoneNumber)
-            const smsDevices = (await this.mfaDeviceRepository.find({
-              where: {
-                userId: user.id,
-                type: MFAMethod.SMS,
-                isActive: true,
-              },
-            } as Record<string, unknown>)) as unknown as Array<Record<string, unknown>>;
-
-            if (smsDevices.length > 0) {
-              this.logger?.log?.(
-                `Deleting ${smsDevices.length} SMS MFA device(s) for user ${user.sub} due to phone number change (old: ${oldPhone}, new: ${dto.phone})`,
-              );
-
-              // Delete all SMS devices (can't be reactivated with old phone number)
-              for (const device of smsDevices) {
-                const deviceId = (device as Record<string, unknown>).id as number;
-                await this.mfaDeviceRepository.delete(deviceId);
-              }
-
-              // Record audit event for removed SMS MFA devices
-              if (this.auditService) {
-                try {
-                  await this.auditService.recordEvent({
-                    userId: user.id,
-                    eventType: AuthAuditEventType.MFA_DEVICE_REMOVED,
-                    eventStatus: 'INFO',
-                    reason: 'phone_changed',
-                    description: `SMS MFA device(s) removed due to phone number change (${oldPhone} → ${dto.phone})`,
-                    metadata: {
-                      method: MFAMethod.SMS,
-                      deletedCount: smsDevices.length,
-                      oldPhone,
-                      newPhone: dto.phone,
-                      reason: 'phone_number_changed_requires_reverification',
-                    },
-                  });
-                } catch (auditError) {
-                  const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                  this.logger?.error?.(
-                    `Failed to record MFA_DEVICE_REMOVED audit event for phone change: ${errorMessage}`,
-                    { error: auditError, userId: user.id },
-                  );
-                }
-              }
-
-              // Check if user has any other active MFA devices
-              const allActiveDevices = (await this.mfaDeviceRepository.find({
-                where: {
-                  userId: user.id,
-                  isActive: true,
-                },
-              } as Record<string, unknown>)) as unknown as Array<Record<string, unknown>>;
-
-              // If no active devices remain and user had MFA enabled, disable MFA
-              if (allActiveDevices.length === 0 && user.mfaEnabled) {
-                updateFields.mfaEnabled = false;
-                updateFields.mfaMethods = [];
-                updateFields.preferredMfaMethod = null;
-                this.logger?.log?.(
-                  `MFA disabled for user ${user.sub} - no active MFA devices remaining after phone change`,
-                );
-              } else {
-                this.logger?.log?.(
-                  `User ${user.sub} still has ${allActiveDevices.length} active MFA device(s) - MFA remains enabled`,
-                );
-              }
-            }
-          } catch (error: unknown) {
-            // Log error but don't fail the phone update
-            // This handles cases where MFA module is not imported (mfaDeviceRepository might not be available)
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            this.logger?.warn?.(
-              `Failed to handle MFA device deactivation during phone change for user ${user.sub}: ${errorMessage}`,
-            );
-          }
-        }
-      }
-    }
-
-    // Handle preferred MFA method
-    if (dto.preferredMfaMethod !== undefined) {
-      updateFields.preferredMfaMethod = dto.preferredMfaMethod as string | null;
-    }
-
-    // Handle metadata merge
-    if (dto.metadata !== undefined) {
-      const existingMetadata = user.metadata || {};
-      updateFields.metadata = { ...existingMetadata, ...dto.metadata };
-    }
-
-    // Update user in database - use internal id for update query
-    await this.userRepository.update(user.id, updateFields as Record<string, unknown>);
-
-    // Fetch updated user - use internal id
-    const updatedUser = (await this.userRepository.findOne({ where: { id: user.id } })) as IUser | null;
-    if (!updatedUser) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found after update');
-    }
-
-    // ============================================================================
-    // Audit: Record profile and attribute updates
-    // ============================================================================
-    try {
-      // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-      // Note: ClientInfoService is used transparently by SessionService and AuditService
-      const updatedFieldNames = Object.keys(updateFields);
-
-      // Build field changes map with before/after values
-      const fieldChanges: Record<string, unknown> = {};
-
-      // Capture before/after values for each updated field
-      if (dto.firstName !== undefined && dto.firstName !== user.firstName) {
-        fieldChanges.firstName = {
-          before: user.firstName ?? null,
-          after: dto.firstName ?? null,
-        };
-      }
-
-      if (dto.lastName !== undefined && dto.lastName !== user.lastName) {
-        fieldChanges.lastName = {
-          before: user.lastName ?? null,
-          after: dto.lastName ?? null,
-        };
-      }
-
-      if (dto.username !== undefined && dto.username !== user.username) {
-        fieldChanges.username = {
-          before: user.username ?? null,
-          after: dto.username ?? null,
-        };
-      }
-
-      // Note: email and phone are tracked separately with specific audit events,
-      // but we include them in fieldChanges for completeness
-      if (dto.email !== undefined && dto.email !== user.email) {
-        fieldChanges.email = {
-          before: user.email ?? null,
-          after: dto.email ?? null,
-        };
-      }
-
-      if (dto.phone !== undefined && dto.phone !== user.phone) {
-        fieldChanges.phone = {
-          before: user.phone ?? null,
-          after: dto.phone ?? null,
-        };
-      }
-
-      if (dto.preferredMfaMethod !== undefined && dto.preferredMfaMethod !== user.preferredMfaMethod) {
-        fieldChanges.preferredMfaMethod = {
-          before: user.preferredMfaMethod ?? null,
-          after: dto.preferredMfaMethod ?? null,
-        };
-      }
-
-      // Handle metadata changes (merged, so track what was added/changed)
-      if (dto.metadata !== undefined) {
-        const oldMetadata = user.metadata || {};
-        const newMetadata = { ...oldMetadata, ...dto.metadata };
-        const metadataChanges: Record<string, { before: unknown; after: unknown }> = {};
-
-        // Track all keys in new metadata
-        const allKeys = new Set([...Object.keys(oldMetadata), ...Object.keys(dto.metadata)]);
-
-        for (const key of allKeys) {
-          const oldValue = oldMetadata[key];
-          const newValue = newMetadata[key];
-
-          // Only track if value actually changed
-          if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
-            metadataChanges[key] = {
-              before: oldValue ?? null,
-              after: newValue ?? null,
-            };
-          }
-        }
-
-        if (Object.keys(metadataChanges).length > 0) {
-          fieldChanges.metadata = metadataChanges;
-        }
-      }
-
-      // Track verification status changes if email/phone changed
-      if (dto.email !== undefined && dto.email !== user.email) {
-        const emailVerificationChanged = !dto.retainVerification && updateFields.isEmailVerified === false;
-        if (emailVerificationChanged) {
-          fieldChanges.isEmailVerified = {
-            before: user.isEmailVerified,
-            after: false,
-          };
-        }
-      }
-
-      if (dto.phone !== undefined && dto.phone !== user.phone) {
-        const phoneVerificationChanged = !dto.retainVerification && updateFields.isPhoneVerified === false;
-        if (phoneVerificationChanged) {
-          fieldChanges.isPhoneVerified = {
-            before: user.isPhoneVerified,
-            after: false,
-          };
-        }
-      }
-
-      // Record general profile update with field changes
-      await this.auditService?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.PROFILE_UPDATED,
-        eventStatus: 'INFO',
-        metadata: {
-          // Client info automatically included from context
-          updatedFields: updatedFieldNames,
-          fieldChanges: Object.keys(fieldChanges).length > 0 ? fieldChanges : undefined,
-        },
-      });
-
-      // Record specific field changes
-      if (dto.email !== undefined && dto.email !== user.email) {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.EMAIL_CHANGED,
-          eventStatus: 'INFO',
-          metadata: {
-            // Client info automatically included from context
-            oldEmail: user.email,
-            newEmail: dto.email,
-            retainVerification: dto.retainVerification || false,
-          },
-        });
-      }
-
-      if (dto.phone !== undefined && dto.phone !== user.phone) {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.PHONE_CHANGED,
-          eventStatus: 'INFO',
-          metadata: {
-            // Client info automatically included from context
-            oldPhone: user.phone,
-            newPhone: dto.phone,
-            retainVerification: dto.retainVerification || false,
-          },
-        });
-      }
-
-      if (dto.username !== undefined && dto.username !== user.username) {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.USERNAME_CHANGED,
-          eventStatus: 'INFO',
-          metadata: {
-            // Client info automatically included from context
-            oldUsername: user.username,
-            newUsername: dto.username,
-          },
-        });
-      }
-    } catch (auditError) {
-      // Non-blocking: Log but continue
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record profile update audit events: ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    // Return user response DTO
-    return UserResponseDto.fromEntity(updatedUser);
-  }
-
-  /**
-   * Ensures email, phone, and username are unique for other users before update.
-   *
-   * Throws if another user already has the specified email, phone, or username.
-   *
-   * @param userId - Internal numeric user ID (excluded from check)
-   * @param updateData - User fields to check for uniqueness
-   * @throws {NAuthException} If a unique constraint is violated for email, phone, or username
-   *
-   * @example
-   * ```typescript
-   * await authService.validateUniquenessConstraints(1, { email: "test@example.com" });
-   * ```
-   */
-  private async validateUniquenessConstraints(
-    userId: number,
-    updateData: UpdateUserAttributesRequestDTO,
-  ): Promise<void> {
-    const conflicts: string[] = [];
-
-    // Check email uniqueness
-    if (updateData.email) {
-      const existingUser = await this.userRepository.findOne({
-        where: { email: updateData.email },
-      });
-      if (existingUser && existingUser.id !== userId) {
-        conflicts.push('Email already exists');
-      }
-    }
-
-    // Check phone uniqueness
-    if (updateData.phone) {
-      const existingUser = await this.userRepository.findOne({
-        where: { phone: updateData.phone },
-      });
-      if (existingUser && existingUser.id !== userId) {
-        conflicts.push('Phone number already exists');
-      }
-    }
-
-    // Check username uniqueness
-    if (updateData.username) {
-      const existingUser = await this.userRepository.findOne({
-        where: { username: updateData.username },
-      });
-      if (existingUser && existingUser.id !== userId) {
-        conflicts.push('Username already exists');
-      }
-    }
-
-    if (conflicts.length > 0) {
-      throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, conflicts.join(', '), {
-        conflicts,
-      });
-    }
-  }
-
-  // ============================================================================
-  // Helper Methods
-  // ============================================================================
-
-  /**
-   * Checks if the login identifier matches the specified allowed type.
-   *
-   * Determines if the given identifier is a valid email, username, phone, or allowed hybrid,
-   * according to the configured identifier type restriction.
-   *
-   * @param identifier - The login identifier to check (email, username, or phone)
-   * @param allowedType - The permitted identifier type ('email', 'username', 'phone', or 'email_or_username')
-   * @returns True if the identifier conforms to the allowed type, otherwise false
-   *
-   * @example
-   * ```typescript
-   * // Email check
-   * const valid = this.validateIdentifierType('user@example.com', 'email'); // true
-   *
-   * // Username check
-   * const valid = this.validateIdentifierType('johndoe', 'username'); // true
-   * ```
-   */
-  private validateIdentifierType(
-    identifier: string,
-    allowedType: 'email' | 'username' | 'phone' | 'email_or_username',
-  ): boolean {
-    // Check if identifier is an email (contains @)
-    const isEmail = identifier.includes('@');
-    // Check if identifier looks like a phone (starts with + and contains digits)
-    const isPhone = /^\+[1-9]\d{1,14}$/.test(identifier.trim());
-    // If not email or phone, assume it's a username
-    const isUsername = !isEmail && !isPhone;
-
-    switch (allowedType) {
-      case 'email':
-        return isEmail;
-      case 'username':
-        return isUsername;
-      case 'phone':
-        return isPhone;
-      case 'email_or_username':
-        return isEmail || isUsername;
-      default:
-        return true; // No restriction
-    }
-  }
-
-  /**
-   * Retrieves a user entity by login identifier.
-   *
-   * Performs a lookup for a user by email, username, or phone number.
-   * The search respects the identifierType restriction when provided, limiting which fields are queried.
-   *
-   * @param identifier - Login credential (email, username, or phone)
-   * @param identifierType - Restricts search to a specific identifier type ('email', 'username', 'phone', or 'email_or_username')
-   * @returns The user entity if found, otherwise null
-   *
-   * @example
-   * ```typescript
-   * const user = await this.findUserByIdentifier('user@example.com');
-   * const user2 = await this.findUserByIdentifier('johndoe', 'username');
-   * ```
-   */
-  private async findUserByIdentifier(
-    identifier: string,
-    identifierType?: 'email' | 'username' | 'phone' | 'email_or_username',
-  ): Promise<IUser | null> {
-    const queryBuilder = this.userRepository.createQueryBuilder('user');
-
-    // Build query based on identifier type restriction
-    if (!identifierType) {
-      // No restriction - search all fields
-      queryBuilder
-        .where('user.email = :identifier', { identifier })
-        .orWhere('user.username = :identifier', { identifier })
-        .orWhere('user.phone = :identifier', { identifier });
-    } else {
-      // Apply restriction based on identifier type
-      switch (identifierType) {
-        case 'email':
-          queryBuilder.where('user.email = :identifier', { identifier });
-          break;
-        case 'username':
-          queryBuilder.where('user.username = :identifier', { identifier });
-          break;
-        case 'phone':
-          queryBuilder.where('user.phone = :identifier', { identifier });
-          break;
-        case 'email_or_username':
-          queryBuilder
-            .where('user.email = :identifier', { identifier })
-            .orWhere('user.username = :identifier', { identifier });
-          break;
-      }
-    }
-
-    // Select only columns required for login checks and response shaping to reduce row size
-    queryBuilder.select([
-      'user.id',
-      'user.sub',
-      'user.email',
-      'user.firstName',
-      'user.lastName',
-      'user.username',
-      'user.phone',
-      'user.passwordHash',
-      'user.passwordChangedAt',
-      'user.mustChangePassword',
-      'user.isActive',
-      'user.mfaEnabled',
-      'user.preferredMfaMethod',
-      'user.isEmailVerified',
-      'user.isPhoneVerified',
-      'user.mfaExempt', // Required for MFA exemption check in challenge flow
-      // The following are used for messaging/challenge determination when needed
-      'user.socialProviders',
-      'user.backupCodes',
-    ]);
-
-    return (await queryBuilder.getOne()) as IUser | null;
-  }
-
-  /**
-   * Handles a failed login by recording the attempt, applying IP-based lockout policy,
-   * and invoking relevant hooks.
-   *
-   * @param identifier - User identifier (email/username/phone)
-   * @param reason - Optional reason for failure
-   * @returns Promise<void>
-   *
-   * @example
-   * ```typescript
-   * await authService.handleFailedLogin('user@example.com', 'invalid_credentials');
-   * ```
-   */
-  private async handleFailedLogin(identifier: string, reason?: string): Promise<void> {
-    // Get client IP address for lockout tracking
-    const clientInfo = this.clientInfoService.get();
-    const ipAddress = clientInfo.ipAddress;
-
-    // Record failed attempt
-    await this.recordLoginAttempt(identifier, false, reason);
-
-    // Increment IP-based lockout counter if enabled
-    if (this.config.lockout?.enabled && ipAddress) {
-      const attempts = await this.accountLockoutStorage.recordFailedAttempt(ipAddress);
-
-      // Lock IP if max attempts reached
-      if (attempts >= (this.config.lockout.maxAttempts || 5)) {
-        await this.accountLockoutStorage.blockIpAdresss(
-          ipAddress,
-          this.config.lockout.duration || 900, // 15 minutes default
-          'Too many failed login attempts from this IP',
-        );
-
-        // // Execute hook with IP address
-        // if (this.config.hooks?.afterAccountLock) {
-        //   await this.config.hooks.afterAccountLock(identifier, 'Too many failed attempts from IP', clientInfo);
-        // }
-      }
-    }
-
-    // // Execute hook
-    // if (this.config.hooks?.afterLoginFailed) {
-    //   await this.config.hooks.afterLoginFailed(identifier, reason || 'unknown');
-    // }
-  }
-
-  /**
-   * Records a login attempt with client context.
-   *
-   * @param email - User's email address
-   * @param success - True if login succeeded, false if failed
-   * @param failureReason - Optional reason for failure
-   * @param userId - Optional internal user ID (only for successful logins)
-   * @returns Promise<void>
-   */
-  private async recordLoginAttempt(
-    email: string,
-    success: boolean,
-    failureReason?: string,
-    userId?: number,
-  ): Promise<void> {
-    // Get client info from context
-    const clientInfo = this.clientInfoService.get();
-
-    const attempt = this.loginAttemptRepository.create({
-      email,
-      userId, // Internal user ID (integer)
-      ipAddress: clientInfo.ipAddress,
-      userAgent: clientInfo.userAgent,
-      success,
-      failureReason,
-    });
-
-    await this.loginAttemptRepository.save(attempt);
-  }
-
-  /**
-   * Get user by ID (sub)
-   * @param sub - User sub (external identifier)
-   * @returns User entity or null
-   */
-  async getUserById(dto: GetUserByIdDTO): Promise<UserResponseDto | null> {
-    const user = (await this.userRepository.findOne({ where: { sub: dto.sub } })) as IUser | null;
-    return user ? UserResponseDto.fromEntity(user) : null;
-  }
-
-  /**
-   * Get user by email address.
-   *
-   * @param email - User email
-   * @param requireEmailVerified - Only return user if email is verified (default: false)
-   * @returns User entity or null
-   * @internal - For use by social auth providers
-   *
-   * @example
-   * ```typescript
-   * const user = await authService.getUserByEmail('user@example.com', true);
-   * ```
-   */
-  async getUserByEmail(dto: GetUserByEmailDTO): Promise<UserResponseDto | null> {
-    const where: Record<string, unknown> = dto.requireEmailVerified
-      ? { email: dto.email, isEmailVerified: true }
-      : { email: dto.email };
-    const user = (await this.userRepository.findOne({ where })) as IUser | null;
-    return user ? UserResponseDto.fromEntity(user) : null;
-  }
-
-  /**
-   * Require user to change password at next login.
-   *
-   * Throws if user not found or has no password set (e.g. social login only).
-   *
-   * @param userId - User's sub identifier
-   * @returns Resolves when flag is set
-   * @throws {NAuthException} If user is not found or cannot change password
-   *
-   * @example
-   * await authService.setMustChangePassword('user-uuid-123');
-   */
-  async setMustChangePassword(dto: SetMustChangePasswordDTO): Promise<SetMustChangePasswordResponseDTO> {
-    const user = await this.userRepository.findOne({ where: { sub: dto.userId } });
-
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    //  CRITICAL PROTECTION: Only allow for users with password authentication
-    // Pure social users cannot be forced to change password
-    if (!user.passwordHash) {
-      this.logger?.warn?.(
-        `Cannot force password change for user ${dto.userId} - user doesn't have a password (pure social signup)`,
-      );
-      throw new NAuthException(
-        AuthErrorCode.PASSWORD_CHANGE_NOT_ALLOWED,
-        'Password change not available. This account uses social authentication only and has no password.',
-      );
-    }
-
-    await this.userRepository.update({ sub: dto.userId }, { mustChangePassword: true });
-
-    this.logger?.log?.(`Must-change-password flag set for user: ${dto.userId}`);
-
-    return { success: true };
-  }
-}