@nauth-toolkit/core 0.1.39 → 0.1.40

package/dist/services/auth-service-internal-helpers.js

@@ -0,0 +1,1004 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthServiceInternalHelpers = void 0;
+const auth_audit_event_type_enum_1 = require("../enums/auth-audit-event-type.enum");
+const auth_challenge_dto_1 = require("../dto/auth-challenge.dto");
+const verify_email_dto_1 = require("../dto/verify-email.dto");
+const verify_phone_dto_1 = require("../dto/verify-phone.dto");
+const verify_phone_by_sub_dto_1 = require("../dto/verify-phone-by-sub.dto");
+const mfa_method_enum_1 = require("../enums/mfa-method.enum");
+const nauth_exception_1 = require("../exceptions/nauth.exception");
+const error_codes_enum_1 = require("../enums/error-codes.enum");
+/**
+ * Internal helper service for AuthService
+ *
+ * Contains private utility methods for challenge handling, validation,
+ * password management, and login tracking. This class is NOT exported from
+ * the package and should only be used internally by AuthService.
+ *
+ * INTERNAL USE ONLY - DO NOT IMPORT DIRECTLY
+ *
+ * @internal
+ */
+class AuthServiceInternalHelpers {
+    userRepository;
+    loginAttemptRepository;
+    emailVerificationService;
+    phoneVerificationService;
+    challengeService;
+    challengeHelper;
+    clientInfoService;
+    sessionService;
+    accountLockoutStorage;
+    config;
+    logger;
+    constructor(userRepository, loginAttemptRepository, emailVerificationService, phoneVerificationService, challengeService, challengeHelper, clientInfoService, sessionService, accountLockoutStorage, config, logger) {
+        this.userRepository = userRepository;
+        this.loginAttemptRepository = loginAttemptRepository;
+        this.emailVerificationService = emailVerificationService;
+        this.phoneVerificationService = phoneVerificationService;
+        this.challengeService = challengeService;
+        this.challengeHelper = challengeHelper;
+        this.clientInfoService = clientInfoService;
+        this.sessionService = sessionService;
+        this.accountLockoutStorage = accountLockoutStorage;
+        this.config = config;
+        this.logger = logger;
+    }
+    // ============================================================================
+    // Challenge Response Handlers
+    // ============================================================================
+    /**
+     * Handle VERIFY_EMAIL challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param code - Email verification code
+     * @returns Authentication response with tokens or next challenge
+     */
+    async handleVerifyEmail(challengeSession, code) {
+        const user = challengeSession.user;
+        if (!user) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 verify_email_dto_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid verification code');
+        }
+        // Consume challenge session
+        await this.challengeService.validateAndConsumeSession(challengeSession.sessionToken, auth_challenge_dto_1.AuthChallenge.VERIFY_EMAIL);
+        // Reload user to get updated emailVerified flag
+        const updatedUser = await this.userRepository.findOne({ where: { sub: user.sub } });
+        if (!updatedUser) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 || 'password';
+        const authProvider = challengeSession.metadata?.authProvider;
+        const isSocialLogin = authMethod === 'social';
+        // Check for next challenges
+        const response = await this.challengeHelper.determineAuthResponse({
+            user: updatedUser,
+            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
+     *
+     * @param challengeSession - Challenge session with user
+     * @param data - Phone verification data (phone number or code)
+     * @returns Authentication response with tokens or next challenge
+     */
+    async handleVerifyPhone(challengeSession, data) {
+        const user = challengeSession.user;
+        if (!user) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.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;
+            if (this.phoneVerificationService) {
+                this.logger?.log?.(`Sending verification SMS to newly added phone: ${phone}`);
+                try {
+                    const smsDto = Object.assign(new verify_phone_dto_1.SendVerificationSMSDTO(), {
+                        sub: user.sub,
+                        skipAlreadyVerifiedCheck: false, // Explicitly set to false for phone verification (not MFA)
+                        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) {
+                    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 || 'password';
+            const authProvider = challengeSession.metadata?.authProvider;
+            // 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 }, auth_challenge_dto_1.AuthChallenge.VERIFY_PHONE, this.config, authMethod, authProvider, true);
+            // 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.code;
+            this.logger?.log?.(`Verifying phone for user: ${user.sub}`);
+            // Check if phone is set
+            if (!user.phone) {
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 verify_phone_by_sub_dto_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid verification code');
+            }
+            // Consume challenge session
+            await this.challengeService.validateAndConsumeSession(challengeSession.sessionToken, auth_challenge_dto_1.AuthChallenge.VERIFY_PHONE);
+            // Reload user to get updated phoneVerified flag
+            const updatedUser = await this.userRepository.findOne({ where: { sub: user.sub } });
+            if (!updatedUser) {
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 || 'password';
+            const authProvider = challengeSession.metadata?.authProvider;
+            const isSocialLogin = authMethod === 'social';
+            // Check for next challenges
+            const response = await this.challengeHelper.determineAuthResponse({
+                user: updatedUser,
+                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}`);
+            }
+            return response;
+        }
+    }
+    /**
+     * Handle MFA_REQUIRED challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param data - MFA verification data
+     * @param mfaService - MFA service (passed from AuthService)
+     * @param trustedDeviceService - Trusted device service (optional, passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Authentication response with tokens or next challenge
+     */
+    async handleMFAVerification(challengeSession, data, mfaService, trustedDeviceService, auditService) {
+        const user = challengeSession.user;
+        if (!user) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 (!mfaService) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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;
+            const credential = passkeyData.credential;
+            // Get expected challenge from session metadata
+            const expectedChallenge = challengeSession.metadata?.passkeyChallenge;
+            if (!expectedChallenge) {
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.CHALLENGE_INVALID, 'No passkey challenge found in session');
+            }
+            // Verify passkey via MFAService
+            const wrappedCredential = { credential, expectedChallenge };
+            const verifyResult = await mfaService.verifyCode({
+                sub: user.sub,
+                methodName: mfa_method_enum_1.MFAMethod.PASSKEY,
+                code: wrappedCredential,
+            });
+            isValid = verifyResult.valid;
+        }
+        else {
+            const codeData = data;
+            const code = codeData.code;
+            // Verify code via MFAService (handles totp, sms, and backup)
+            const verifyResult = await 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) {
+                auditService
+                    ?.recordEvent({
+                    userId: user.id,
+                    eventType: auth_audit_event_type_enum_1.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 auditService?.recordEvent({
+                        userId: user.id,
+                        eventType: auth_audit_event_type_enum_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.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) {
+            auditService
+                ?.recordEvent({
+                userId: user.id,
+                eventType: auth_audit_event_type_enum_1.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 auditService?.recordEvent({
+                    userId: user.id,
+                    eventType: auth_audit_event_type_enum_1.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, auth_challenge_dto_1.AuthChallenge.MFA_REQUIRED);
+        // Read auth context from challenge session metadata
+        const authMethod = challengeSession.metadata?.authMethod || 'password';
+        const authProvider = challengeSession.metadata?.authProvider;
+        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;
+        let isTrustedDevice = false;
+        if (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 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 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}`);
+        }
+        return response;
+    }
+    /**
+     * Handle FORCE_CHANGE_PASSWORD challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param newPassword - New password
+     * @param passwordService - Password service (passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Authentication response with tokens or next challenge
+     */
+    async handleForceChangePassword(challengeSession, newPassword, passwordService, auditService) {
+        const user = challengeSession.user;
+        if (!user) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.CHALLENGE_INVALID, 'User not found in challenge session');
+        }
+        this.logger?.log?.(`Changing password for user: ${user.sub}`);
+        await this.updateUserPassword({
+            user,
+            newPassword,
+            mustChangePassword: false,
+            revokeSessions: true,
+            revokeReason: 'Password changed (force change password)',
+            audit: {
+                eventType: auth_audit_event_type_enum_1.AuthAuditEventType.PASSWORD_CHANGED,
+                eventStatus: 'SUCCESS',
+                reason: 'force_change_password',
+                description: 'Password changed due to FORCE_CHANGE_PASSWORD challenge',
+            },
+        }, passwordService, auditService);
+        // Consume challenge session
+        await this.challengeService.validateAndConsumeSession(challengeSession.sessionToken, auth_challenge_dto_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.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 || 'password';
+        const authProvider = challengeSession.metadata?.authProvider;
+        const isSocialLogin = authMethod === 'social';
+        // Check for next challenges
+        const response = await this.challengeHelper.determineAuthResponse({
+            user: updatedUser,
+            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}`);
+        }
+        return response;
+    }
+    /**
+     * Handle MFA_SETUP_REQUIRED challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param data - MFA setup data
+     * @param mfaService - MFA service (passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Authentication response with tokens or next challenge
+     */
+    async handleMFASetup(challengeSession, data, mfaService, _auditService) {
+        const user = challengeSession.user;
+        if (!user) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 (!mfaService) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
+        }
+        // Get provider
+        const provider = mfaService.getProvider(method);
+        // Verify setup based on method
+        let deviceId;
+        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, auth_challenge_dto_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.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,
+            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}`);
+        }
+        return response;
+    }
+    // ============================================================================
+    // Validation Helpers
+    // ============================================================================
+    /**
+     * Validate that response type matches expected challenge type
+     *
+     * @param expected - Expected challenge type
+     * @param provided - Provided challenge type
+     * @throws {NAuthException} If types don't match
+     */
+    validateChallengeTypeMatch(expected, provided) {
+        if (expected !== provided) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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.
+     *
+     * @param type - Challenge type
+     * @param data - Challenge response data
+     * @throws {NAuthException} If validation fails
+     */
+    validateChallengeParams(type, data) {
+        switch (type) {
+            case 'VERIFY_EMAIL': {
+                const response = data;
+                if (!response.code || typeof response.code !== 'string') {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Verification code is required', { field: 'code' });
+                }
+                break;
+            }
+            case 'VERIFY_PHONE': {
+                const response = data;
+                const hasCode = 'code' in response && response.code;
+                const hasPhone = 'phone' in response && response.phone;
+                if (!hasCode && !hasPhone) {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Either phone number or verification code is required', { fields: ['phone', 'code'] });
+                }
+                break;
+            }
+            case 'MFA_REQUIRED': {
+                const response = data;
+                if (!response.method) {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'MFA method is required', { field: 'method' });
+                }
+                if (response.method === 'passkey') {
+                    const passkeyResponse = response;
+                    if (!passkeyResponse.credential) {
+                        throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Passkey credential is required', {
+                            field: 'credential',
+                        });
+                    }
+                }
+                else {
+                    const codeResponse = response;
+                    if (!codeResponse.code || typeof codeResponse.code !== 'string') {
+                        throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'MFA code is required', { field: 'code' });
+                    }
+                }
+                break;
+            }
+            case 'FORCE_CHANGE_PASSWORD': {
+                const response = data;
+                if (!response.newPassword || typeof response.newPassword !== 'string') {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'New password is required', {
+                        field: 'newPassword',
+                    });
+                }
+                break;
+            }
+            case 'MFA_SETUP_REQUIRED': {
+                const response = data;
+                if (!response.method) {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'MFA setup method is required', {
+                        field: 'method',
+                    });
+                }
+                if (!response.setupData || typeof response.setupData !== 'object') {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'MFA setup data is required', {
+                        field: 'setupData',
+                    });
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * 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
+     */
+    validateIdentifierType(identifier, allowedType) {
+        // 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
+        }
+    }
+    /**
+     * 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
+     */
+    async validateUniquenessConstraints(userId, updateData) {
+        const conflicts = [];
+        // 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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, conflicts.join(', '), {
+                conflicts,
+            });
+        }
+    }
+    // ============================================================================
+    // User Lookup Helpers
+    // ============================================================================
+    /**
+     * 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
+     */
+    async findUserByIdentifier(identifier, identifierType) {
+        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
+            // Lock fields - required for account lock check in login flow
+            'user.isLocked',
+            'user.lockReason',
+            'user.lockedAt',
+            'user.lockedUntil',
+            // The following are used for messaging/challenge determination when needed
+            'user.socialProviders',
+            'user.backupCodes',
+        ]);
+        return (await queryBuilder.getOne());
+    }
+    // ============================================================================
+    // Password Management Helpers
+    // ============================================================================
+    /**
+     * Centralized password update flow used by:
+     * - changePassword()
+     * - confirmForgotPassword()
+     * - adminSetPassword()
+     * - FORCE_CHANGE_PASSWORD challenge handler
+     *
+     * WHY:
+     * - Prevent logic drift between different password-changing entrypoints
+     * - Ensure consistent validation, history enforcement, persistence, session revocation, and audit trails
+     *
+     * @param params - Password update parameters
+     * @param passwordService - Password service (passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Sessions revoked count (0 when not revoked)
+     * @throws {NAuthException} WEAK_PASSWORD | PASSWORD_REUSED | NOT_FOUND
+     */
+    async updateUserPassword(params, passwordService, auditService) {
+        const { user, newPassword, mustChangePassword, revokeSessions, revokeReason, beforePersist, audit } = params;
+        // ============================================================================
+        // Load full user entity (important for passwordHistory serialization + reuse checks)
+        // ============================================================================
+        // WHY: Some call sites use a slim projection (e.g., findUserByIdentifier) which may omit passwordHistory.
+        const userEntity = (await this.userRepository.findOne({ where: { id: user.id } }));
+        if (!userEntity) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
+        }
+        // ============================================================================
+        // Validate new password + history
+        // ============================================================================
+        const validation = await passwordService.validatePassword(newPassword, {
+            email: userEntity.email,
+            username: userEntity.username || undefined,
+        });
+        if (!validation.valid) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.WEAK_PASSWORD, validation.errors.join(', '), {
+                errors: validation.errors,
+            });
+        }
+        if (this.config.password?.historyCount) {
+            const historyToCheck = userEntity.passwordHistory || [];
+            const allPreviousPasswords = userEntity.passwordHash
+                ? [userEntity.passwordHash, ...historyToCheck]
+                : historyToCheck;
+            const isReused = await passwordService.isPasswordInHistory(newPassword, allPreviousPasswords);
+            if (isReused) {
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.PASSWORD_REUSED, 'Cannot reuse a recent password');
+            }
+        }
+        // Hook point for flows that must prove possession of a reset code before persisting (forgot-password confirm)
+        if (beforePersist) {
+            await beforePersist();
+        }
+        // ============================================================================
+        // Persist password update
+        // ============================================================================
+        const newHash = await passwordService.hashPassword(newPassword);
+        const newHistory = userEntity.passwordHash
+            ? passwordService.addToHistory(userEntity.passwordHistory || [], userEntity.passwordHash)
+            : userEntity.passwordHistory || [];
+        userEntity.passwordHash = newHash;
+        userEntity.passwordChangedAt = new Date();
+        userEntity.passwordHistory = newHistory;
+        userEntity.mustChangePassword = mustChangePassword;
+        await this.userRepository.save(userEntity);
+        // ============================================================================
+        // Session revocation
+        // ============================================================================
+        let sessionsRevoked = 0;
+        if (revokeSessions) {
+            sessionsRevoked = await this.sessionService.revokeAllUserSessions(userEntity.id, revokeReason);
+        }
+        // ============================================================================
+        // Audit
+        // ============================================================================
+        if (audit) {
+            try {
+                await auditService?.recordEvent({
+                    userId: userEntity.id,
+                    eventType: audit.eventType,
+                    eventStatus: audit.eventStatus,
+                    reason: audit.reason,
+                    description: audit.description,
+                    authMethod: audit.authMethod,
+                    metadata: {
+                        ...audit.metadata,
+                        mustChangePassword,
+                        sessionsRevoked,
+                    },
+                });
+            }
+            catch (auditError) {
+                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                this.logger?.error?.(`Failed to record ${audit.eventType} audit event: ${errorMessage}`, {
+                    error: auditError,
+                    userId: userEntity.id,
+                });
+            }
+        }
+        return { sessionsRevoked };
+    }
+    // ============================================================================
+    // Login Tracking Helpers
+    // ============================================================================
+    /**
+     * 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
+     */
+    async handleFailedLogin(identifier, reason) {
+        // 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.lockIpAddress(ipAddress, this.config.lockout.duration || 900, // 15 minutes default
+                'Too many failed login attempts from this IP');
+            }
+        }
+    }
+    /**
+     * 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)
+     */
+    async recordLoginAttempt(email, success, failureReason, userId) {
+        // 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);
+    }
+    // ============================================================================
+    // Cookie Management Helpers
+    // ============================================================================
+    /**
+     * Clear authentication cookies from response
+     *
+     * @param response - HTTP response object with clearCookie method
+     * @param forgetDevice - Whether to also clear device token cookie
+     */
+    clearAuthCookies(response, forgetDevice) {
+        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);
+        }
+    }
+    // ============================================================================
+    // Formatting Helpers
+    // ============================================================================
+    /**
+     * Mask email address for privacy (show first char and domain)
+     *
+     * @param email - Email address to mask
+     * @returns Masked email (e.g., 'u***r@example.com')
+     */
+    maskEmail(email) {
+        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 privacy (show last 4 digits)
+     *
+     * @param phone - Phone number to mask
+     * @returns Masked phone (e.g., '***-***-1234')
+     */
+    maskPhone(phone) {
+        const digits = phone.replace(/\D/g, '');
+        const lastFour = digits.slice(-4);
+        return `***-***-${lastFour}`;
+    }
+}
+exports.AuthServiceInternalHelpers = AuthServiceInternalHelpers;
+//# sourceMappingURL=auth-service-internal-helpers.js.map