@nauth-toolkit/core 0.1.39 → 0.1.41

package/dist/services/auth.service.js

@@ -40,34 +40,27 @@ const context_storage_1 = require("../utils/context-storage");
 const signup_dto_1 = require("../dto/signup.dto");
 const admin_signup_dto_1 = require("../dto/admin-signup.dto");
 const admin_signup_social_dto_1 = require("../dto/admin-signup-social.dto");
-const delete_user_dto_1 = require("../dto/delete-user.dto");
-const get_users_dto_1 = require("../dto/get-users.dto");
-const disable_user_dto_1 = require("../dto/disable-user.dto");
-const enable_user_dto_1 = require("../dto/enable-user.dto");
 const login_dto_1 = require("../dto/login.dto");
 const change_password_request_dto_1 = require("../dto/change-password-request.dto");
-const update_user_attributes_request_dto_1 = require("../dto/update-user-attributes-request.dto");
-const update_verified_status_request_dto_1 = require("../dto/update-verified-status-request.dto");
 const user_response_dto_1 = require("../dto/user-response.dto");
 const auth_response_dto_1 = require("../dto/auth-response.dto");
 const auth_challenge_dto_1 = require("../dto/auth-challenge.dto");
 const respond_challenge_dto_1 = require("../dto/respond-challenge.dto");
-const get_user_by_email_dto_1 = require("../dto/get-user-by-email.dto");
-const get_user_by_id_dto_1 = require("../dto/get-user-by-id.dto");
 const logout_dto_1 = require("../dto/logout.dto");
 const logout_all_dto_1 = require("../dto/logout-all.dto");
+const get_user_sessions_dto_1 = require("../dto/get-user-sessions.dto");
+const logout_session_dto_1 = require("../dto/logout-session.dto");
 const refresh_token_dto_1 = require("../dto/refresh-token.dto");
 const resend_code_dto_1 = require("../dto/resend-code.dto");
-const set_must_change_password_dto_1 = require("../dto/set-must-change-password.dto");
 const admin_set_password_dto_1 = require("../dto/admin-set-password.dto");
 const forgot_password_dto_1 = require("../dto/forgot-password.dto");
 const confirm_forgot_password_dto_1 = require("../dto/confirm-forgot-password.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 auth_service_internal_helpers_1 = require("./auth-service-internal-helpers");
+const user_service_1 = require("./user.service");
 const nauth_exception_1 = require("../exceptions/nauth.exception");
 const error_codes_enum_1 = require("../enums/error-codes.enum");
-const mfa_method_enum_1 = require("../enums/mfa-method.enum");
 const class_validator_1 = require("class-validator");
 const crypto = __importStar(require("crypto"));
 const password_generator_1 = require("../utils/password-generator");
@@ -108,6 +101,8 @@ class AuthService {
     challengeSessionRepository;
     authAuditRepository;
     trustedDeviceRepository;
+    helpers;
+    userService;
     constructor(userRepository, loginAttemptRepository, passwordService, jwtService, sessionService, challengeService, challengeHelper, emailVerificationService, clientInfoService, accountLockoutStorage, config, logger, hookRegistry, auditService, // Optional - audit trail service (enabled via config.auditLogs.enabled)
     phoneVerificationService, // Optional - only available when SMS provider is configured
     mfaService, // Optional - available when MFA modules are imported
@@ -147,6 +142,10 @@ class AuthService {
         this.challengeSessionRepository = challengeSessionRepository;
         this.authAuditRepository = authAuditRepository;
         this.trustedDeviceRepository = trustedDeviceRepository;
+        // Initialize internal helpers with only needed dependencies
+        this.helpers = new auth_service_internal_helpers_1.AuthServiceInternalHelpers(userRepository, loginAttemptRepository, emailVerificationService, phoneVerificationService, challengeService, challengeHelper, clientInfoService, sessionService, accountLockoutStorage, config, logger);
+        // Initialize UserService for user data management
+        this.userService = new user_service_1.UserService(userRepository, loginAttemptRepository, sessionService, config, logger, mfaDeviceRepository, auditService, hookRegistry, clientInfoService, sessionRepository, verificationTokenRepository, socialAccountRepository, challengeSessionRepository, authAuditRepository, trustedDeviceRepository, this.helpers);
         this.logger?.log?.('AuthService initialized');
     }
     // ============================================================================
@@ -853,124 +852,7 @@ class AuthService {
      * ```
      */
     async deleteUser(dto) {
-        // Ensure DTO is validated
-        dto = await (0, dto_validator_1.ensureValidatedDto)(delete_user_dto_1.DeleteUserDTO, dto);
-        // Get client info for audit
-        const clientInfo = this.clientInfoService.get();
-        this.logger?.log?.(`Admin deleteUser initiated for sub: ${dto.sub}`);
-        // Find user by sub
-        const user = await this.userRepository.findOne({ where: { sub: dto.sub } });
-        if (!user) {
-            this.logger?.warn?.(`User not found for deletion: ${dto.sub}`);
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USER_NOT_FOUND, 'User not found');
-        }
-        this.logger?.debug?.(`Deleting user ${user.email} (id: ${user.id}, sub: ${dto.sub})`);
-        // ============================================================================
-        // Explicit Cascade Deletion (to track counts)
-        // ============================================================================
-        // Even though database has CASCADE, we explicitly delete each table to track counts
-        // 1. Delete Sessions
-        let sessionsCount = 0;
-        if (this.sessionRepository) {
-            const result = await this.sessionRepository.delete({ userId: user.id });
-            sessionsCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${sessionsCount} sessions for user ${dto.sub}`);
-        }
-        // 2. Delete Verification Tokens
-        let verificationTokensCount = 0;
-        if (this.verificationTokenRepository) {
-            const result = await this.verificationTokenRepository.delete({ userId: user.id });
-            verificationTokensCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${verificationTokensCount} verification tokens for user ${dto.sub}`);
-        }
-        // 3. Delete MFA Devices
-        let mfaDevicesCount = 0;
-        if (this.mfaDeviceRepository) {
-            const result = await this.mfaDeviceRepository.delete({ userId: user.id });
-            mfaDevicesCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${mfaDevicesCount} MFA devices for user ${dto.sub}`);
-        }
-        // 4. Delete Trusted Devices
-        let trustedDevicesCount = 0;
-        if (this.trustedDeviceRepository) {
-            const result = await this.trustedDeviceRepository.delete({ userId: user.id });
-            trustedDevicesCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${trustedDevicesCount} trusted devices for user ${dto.sub}`);
-        }
-        // 5. Delete Social Accounts
-        let socialAccountsCount = 0;
-        if (this.socialAccountRepository) {
-            const result = await this.socialAccountRepository.delete({ userId: user.id });
-            socialAccountsCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${socialAccountsCount} social accounts for user ${dto.sub}`);
-        }
-        // 6. Delete Login Attempts
-        let loginAttemptsCount = 0;
-        const loginAttemptResult = await this.loginAttemptRepository.delete({ userId: user.id });
-        loginAttemptsCount = loginAttemptResult.affected || 0;
-        this.logger?.debug?.(`Deleted ${loginAttemptsCount} login attempts for user ${dto.sub}`);
-        // 7. Delete Challenge Sessions
-        let challengeSessionsCount = 0;
-        if (this.challengeSessionRepository) {
-            const result = await this.challengeSessionRepository.delete({ userId: user.id });
-            challengeSessionsCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${challengeSessionsCount} challenge sessions for user ${dto.sub}`);
-        }
-        // 8. Delete Audit Logs (user-specific)
-        let auditLogsCount = 0;
-        if (this.authAuditRepository) {
-            const result = await this.authAuditRepository.delete({ userId: user.id });
-            auditLogsCount = result.affected || 0;
-            this.logger?.debug?.(`Deleted ${auditLogsCount} audit logs for user ${dto.sub}`);
-        }
-        // ============================================================================
-        // Record Admin Action (BEFORE deleting user to satisfy foreign key constraint)
-        // ============================================================================
-        try {
-            await this.auditService?.recordEvent({
-                userId: user.id,
-                eventType: auth_audit_event_type_enum_1.AuthAuditEventType.ACCOUNT_DELETED,
-                eventStatus: 'INFO',
-                authMethod: 'admin',
-                metadata: {
-                    deletedEmail: user.email,
-                    deletedSub: dto.sub,
-                    adminIdentifier: clientInfo.ipAddress || 'unknown',
-                    deletedRecords: {
-                        sessions: sessionsCount,
-                        verificationTokens: verificationTokensCount,
-                        mfaDevices: mfaDevicesCount,
-                        trustedDevices: trustedDevicesCount,
-                        socialAccounts: socialAccountsCount,
-                        loginAttempts: loginAttemptsCount,
-                        challengeSessions: challengeSessionsCount,
-                        auditLogs: auditLogsCount,
-                    },
-                },
-            });
-        }
-        catch (auditError) {
-            // Non-blocking: Log but continue
-            const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-            this.logger?.error?.(`Failed to record ACCOUNT_DELETED audit event: ${errorMessage}`);
-        }
-        // 9. Delete User Record (final)
-        await this.userRepository.delete({ id: user.id });
-        this.logger?.log?.(`User deleted successfully: ${user.email} (sub: ${dto.sub})`);
-        return {
-            success: true,
-            deletedUserId: dto.sub,
-            deletedRecords: {
-                sessions: sessionsCount,
-                verificationTokens: verificationTokensCount,
-                mfaDevices: mfaDevicesCount,
-                trustedDevices: trustedDevicesCount,
-                socialAccounts: socialAccountsCount,
-                loginAttempts: loginAttemptsCount,
-                challengeSessions: challengeSessionsCount,
-                auditLogs: auditLogsCount,
-            },
-        };
+        return await this.userService.deleteUser(dto);
     }
     /**
      * Get paginated list of users with advanced filtering
@@ -999,100 +881,7 @@ class AuthService {
      * ```
      */
     async getUsers(dto) {
-        // Ensure DTO is validated
-        dto = await (0, dto_validator_1.ensureValidatedDto)(get_users_dto_1.GetUsersDTO, dto);
-        this.logger?.debug?.(`Admin getUsers initiated with filters: ${JSON.stringify(dto)}`);
-        // ============================================================================
-        // Build Query with Filters
-        // ============================================================================
-        const qb = this.userRepository.createQueryBuilder('user');
-        // Apply partial match filters (email and phone) - case-insensitive
-        // Using LOWER() for cross-database compatibility (works on both MySQL and PostgreSQL)
-        if (dto.email) {
-            qb.andWhere('LOWER(user.email) LIKE LOWER(:email)', { email: `%${dto.email}%` });
-        }
-        if (dto.phone) {
-            qb.andWhere('LOWER(user.phone) LIKE LOWER(:phone)', { phone: `%${dto.phone}%` });
-        }
-        // Apply boolean filters
-        if (dto.isEmailVerified !== undefined) {
-            qb.andWhere('user.isEmailVerified = :isEmailVerified', { isEmailVerified: dto.isEmailVerified });
-        }
-        if (dto.isPhoneVerified !== undefined) {
-            qb.andWhere('user.isPhoneVerified = :isPhoneVerified', { isPhoneVerified: dto.isPhoneVerified });
-        }
-        if (dto.hasSocialAuth !== undefined) {
-            qb.andWhere('user.hasSocialAuth = :hasSocialAuth', { hasSocialAuth: dto.hasSocialAuth });
-        }
-        if (dto.isLocked !== undefined) {
-            qb.andWhere('user.isLocked = :isLocked', { isLocked: dto.isLocked });
-        }
-        if (dto.mfaEnabled !== undefined) {
-            qb.andWhere('user.mfaEnabled = :mfaEnabled', { mfaEnabled: dto.mfaEnabled });
-        }
-        // Apply date filters with operators
-        if (dto.createdAt) {
-            const { operator, value } = dto.createdAt;
-            if (operator === 'gt') {
-                qb.andWhere('user.createdAt > :createdAtValue', { createdAtValue: value });
-            }
-            else if (operator === 'gte') {
-                qb.andWhere('user.createdAt >= :createdAtValue', { createdAtValue: value });
-            }
-            else if (operator === 'lt') {
-                qb.andWhere('user.createdAt < :createdAtValue', { createdAtValue: value });
-            }
-            else if (operator === 'lte') {
-                qb.andWhere('user.createdAt <= :createdAtValue', { createdAtValue: value });
-            }
-            else if (operator === 'eq') {
-                qb.andWhere('user.createdAt = :createdAtValue', { createdAtValue: value });
-            }
-        }
-        if (dto.updatedAt) {
-            const { operator, value } = dto.updatedAt;
-            if (operator === 'gt') {
-                qb.andWhere('user.updatedAt > :updatedAtValue', { updatedAtValue: value });
-            }
-            else if (operator === 'gte') {
-                qb.andWhere('user.updatedAt >= :updatedAtValue', { updatedAtValue: value });
-            }
-            else if (operator === 'lt') {
-                qb.andWhere('user.updatedAt < :updatedAtValue', { updatedAtValue: value });
-            }
-            else if (operator === 'lte') {
-                qb.andWhere('user.updatedAt <= :updatedAtValue', { updatedAtValue: value });
-            }
-            else if (operator === 'eq') {
-                qb.andWhere('user.updatedAt = :updatedAtValue', { updatedAtValue: value });
-            }
-        }
-        // ============================================================================
-        // Apply Sorting
-        // ============================================================================
-        const sortBy = dto.sortBy || 'createdAt';
-        const sortOrder = dto.sortOrder || 'DESC';
-        qb.orderBy(`user.${sortBy}`, sortOrder);
-        // ============================================================================
-        // Apply Pagination
-        // ============================================================================
-        const page = dto.page || 1;
-        const limit = dto.limit || 10;
-        qb.skip((page - 1) * limit).take(limit);
-        // Execute query
-        const [users, total] = await qb.getManyAndCount();
-        this.logger?.debug?.(`Found ${users.length} users (total: ${total}) with filters`);
-        // Sanitize user data
-        const sanitizedUsers = users.map((user) => user_response_dto_1.UserResponseDto.fromEntity(user));
-        return {
-            users: sanitizedUsers,
-            pagination: {
-                page,
-                limit,
-                total,
-                totalPages: Math.ceil(total / limit),
-            },
-        };
+        return await this.userService.getUsers(dto);
     }
     /**
      * Administrative permanent account locking
@@ -1123,112 +912,7 @@ class AuthService {
      * ```
      */
     async disableUser(dto) {
-        // Ensure DTO is validated
-        dto = await (0, dto_validator_1.ensureValidatedDto)(disable_user_dto_1.DisableUserDTO, dto);
-        // Get client info for audit
-        const clientInfo = this.clientInfoService.get();
-        this.logger?.log?.(`Admin disableUser initiated for sub: ${dto.sub}`);
-        // Find user by sub
-        const user = await this.userRepository.findOne({ where: { sub: dto.sub } });
-        if (!user) {
-            this.logger?.warn?.(`User not found for disabling: ${dto.sub}`);
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USER_NOT_FOUND, 'User not found');
-        }
-        this.logger?.debug?.(`Disabling user ${user.email} (id: ${user.id}, sub: ${dto.sub})`);
-        // ============================================================================
-        // Set Permanent Lock (lockedUntil = NULL)
-        // ============================================================================
-        // Use update() to ensure persistence and avoid entity state issues
-        await this.userRepository.update({ id: user.id }, {
-            isLocked: true,
-            lockReason: dto.reason || 'Account disabled',
-            lockedAt: new Date(),
-            lockedUntil: null, // NULL = permanent lock (vs rate-limit's future date)
-        });
-        // Reload user to get updated entity with lock fields
-        const updatedUser = (await this.userRepository.findOne({ where: { id: user.id } }));
-        if (!updatedUser) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USER_NOT_FOUND, 'User not found after update');
-        }
-        this.logger?.log?.(`User locked permanently: ${updatedUser.email} (sub: ${dto.sub})`);
-        // ============================================================================
-        // Revoke All Sessions (force logout)
-        // ============================================================================
-        let revokedCount = 0;
-        try {
-            revokedCount = await this.sessionService.revokeAllUserSessions(updatedUser.id, 'Account disabled');
-            this.logger?.debug?.(`Revoked ${revokedCount} sessions for user ${dto.sub}`);
-        }
-        catch (sessionError) {
-            // Non-blocking: Log but continue
-            const errorMessage = sessionError instanceof Error ? sessionError.message : 'Unknown error';
-            this.logger?.warn?.(`Failed to revoke sessions for user ${dto.sub}: ${errorMessage}`);
-        }
-        // ============================================================================
-        // Record Admin Action (ACCOUNT_DISABLED)
-        // ============================================================================
-        if (!this.auditService) {
-            this.logger?.warn?.(`Audit service not available - ACCOUNT_DISABLED event not recorded for user ${dto.sub}. Enable audit logs in config.auditLogs.enabled`);
-        }
-        else {
-            try {
-                // Get admin user ID from client info (the currently logged in user performing this action)
-                // This is extracted from the JWT token by interceptors/handlers
-                const adminUserId = clientInfo?.userId;
-                // Set performedBy to the admin's user ID (who locked the account)
-                // This identifies which admin user performed the action in the audit trail
-                const performedBy = adminUserId ? String(adminUserId) : clientInfo.ipAddress || 'system';
-                if (adminUserId) {
-                    this.logger?.debug?.(`Admin user ID ${adminUserId} (currently logged in) is disabling account for user ${dto.sub}`);
-                }
-                else {
-                    this.logger?.warn?.(`No admin user ID in clientInfo - performedBy will be set to IP address or 'system' for user ${dto.sub}`);
-                }
-                const auditResult = await this.auditService.recordEvent({
-                    userId: updatedUser.id, // The user whose account is being disabled
-                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.ACCOUNT_DISABLED,
-                    eventStatus: 'INFO',
-                    authMethod: 'admin',
-                    performedBy, // The admin user ID (currently logged in user) who performed this action
-                    reason: updatedUser.lockReason || 'Account disabled',
-                    description: `Account disabled by administrator. User: ${updatedUser.email} (sub: ${dto.sub}). ${revokedCount} session(s) revoked.`,
-                    metadata: {
-                        email: updatedUser.email,
-                        userSub: dto.sub,
-                        reason: updatedUser.lockReason,
-                        adminIdentifier: clientInfo.ipAddress || 'unknown',
-                        adminUserId: adminUserId || null,
-                        revokedSessions: revokedCount,
-                        lockedAt: updatedUser.lockedAt,
-                        lockedUntil: updatedUser.lockedUntil,
-                    },
-                });
-                if (auditResult) {
-                    this.logger?.debug?.(`ACCOUNT_DISABLED audit event recorded successfully for user ${dto.sub}`);
-                }
-                else {
-                    this.logger?.warn?.(`ACCOUNT_DISABLED audit event returned null for user ${dto.sub}`);
-                }
-            }
-            catch (auditError) {
-                // Non-blocking: Log but continue
-                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                const errorStack = auditError instanceof Error ? auditError.stack : undefined;
-                this.logger?.error?.(`Failed to record ACCOUNT_DISABLED audit event: ${errorMessage}`, {
-                    error: auditError,
-                    errorStack,
-                    userId: updatedUser.id,
-                    userSub: dto.sub,
-                });
-            }
-        }
-        // Return sanitized user and revoked session count
-        const userDto = user_response_dto_1.UserResponseDto.fromEntity(updatedUser);
-        return {
-            success: true,
-            user: userDto,
-            revokedSessions: revokedCount,
-        };
+        return await this.userService.disableUser(dto);
     }
     /**
      * Enable (unlock) user account
@@ -1255,94 +939,7 @@ class AuthService {
      * ```
      */
     async enableUser(dto) {
-        // Ensure DTO is validated
-        dto = await (0, dto_validator_1.ensureValidatedDto)(enable_user_dto_1.EnableUserDTO, dto);
-        // Get client info for audit
-        const clientInfo = this.clientInfoService.get();
-        this.logger?.log?.(`Admin enableUser initiated for sub: ${dto.sub}`);
-        // Find user by sub
-        const user = await this.userRepository.findOne({ where: { sub: dto.sub } });
-        if (!user) {
-            this.logger?.warn?.(`User not found for enabling: ${dto.sub}`);
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USER_NOT_FOUND, 'User not found');
-        }
-        this.logger?.debug?.(`Enabling user ${user.email} (id: ${user.id}, sub: ${dto.sub})`);
-        // ============================================================================
-        // Clear Lock Fields (unlock account)
-        // ============================================================================
-        await this.userRepository.update({ id: user.id }, {
-            isLocked: false,
-            lockReason: null,
-            lockedAt: null,
-            lockedUntil: null,
-            failedLoginAttempts: 0, // Reset failed attempts counter
-        });
-        // Reload user to get updated entity
-        const updatedUser = (await this.userRepository.findOne({ where: { id: user.id } }));
-        if (!updatedUser) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USER_NOT_FOUND, 'User not found after update');
-        }
-        this.logger?.log?.(`User unlocked: ${updatedUser.email} (sub: ${dto.sub})`);
-        // ============================================================================
-        // Record Admin Action (ACCOUNT_ENABLED)
-        // ============================================================================
-        if (!this.auditService) {
-            this.logger?.warn?.(`Audit service not available - ACCOUNT_ENABLED event not recorded for user ${dto.sub}. Enable audit logs in config.auditLogs.enabled`);
-        }
-        else {
-            try {
-                // Get admin user ID from client info (the currently logged in user performing this action)
-                const adminUserId = clientInfo?.userId;
-                // Set performedBy to the admin's user ID (who unlocked the account)
-                const performedBy = adminUserId ? String(adminUserId) : clientInfo.ipAddress || 'system';
-                if (adminUserId) {
-                    this.logger?.debug?.(`Admin user ID ${adminUserId} (currently logged in) is enabling account for user ${dto.sub}`);
-                }
-                else {
-                    this.logger?.warn?.(`No admin user ID in clientInfo - performedBy will be set to IP address or 'system' for user ${dto.sub}`);
-                }
-                const auditResult = await this.auditService.recordEvent({
-                    userId: updatedUser.id,
-                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.ACCOUNT_ENABLED,
-                    eventStatus: 'INFO',
-                    authMethod: 'admin',
-                    performedBy,
-                    reason: 'admin_unlock',
-                    description: 'Account unlocked by administrator',
-                    metadata: {
-                        userSub: dto.sub,
-                        adminIdentifier: clientInfo.ipAddress || 'unknown',
-                        adminUserId: adminUserId || null,
-                        previousLockReason: user.lockReason,
-                        previousLockedAt: user.lockedAt,
-                        previousLockedUntil: user.lockedUntil,
-                    },
-                });
-                if (auditResult) {
-                    this.logger?.debug?.(`ACCOUNT_ENABLED audit event recorded successfully for user ${dto.sub}`);
-                }
-                else {
-                    this.logger?.warn?.(`ACCOUNT_ENABLED audit event returned null for user ${dto.sub}`);
-                }
-            }
-            catch (auditError) {
-                // Non-blocking: Log but continue
-                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                const errorStack = auditError instanceof Error ? auditError.stack : undefined;
-                this.logger?.error?.(`Failed to record ACCOUNT_ENABLED audit event: ${errorMessage}`, {
-                    error: auditError,
-                    errorStack,
-                    userId: updatedUser.id,
-                    userSub: dto.sub,
-                });
-            }
-        }
-        // Return sanitized user
-        const userDto = user_response_dto_1.UserResponseDto.fromEntity(updatedUser);
-        return {
-            success: true,
-            user: userDto,
-        };
+        return await this.userService.enableUser(dto);
     }
     // ============================================================================
     // User Login
@@ -1382,7 +979,7 @@ class AuthService {
                 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');
+                    await this.helpers.recordLoginAttempt(dto.identifier, false, 'ip_locked');
                     // ============================================================================
                     // Audit: Record blocked login (IP locked)
                     // ============================================================================
@@ -1432,16 +1029,16 @@ class AuthService {
         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);
+            const isValidIdentifier = this.helpers.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');
+                await this.helpers.handleFailedLogin(dto.identifier, 'identifier_type_mismatch');
                 throw new nauth_exception_1.NAuthException(error_codes_enum_1.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);
+        const user = await this.helpers.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;
@@ -1451,7 +1048,7 @@ class AuthService {
         // 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');
+            await this.helpers.handleFailedLogin(dto.identifier, 'invalid_credentials');
             // ============================================================================
             // Audit: Record failed login
             // ============================================================================
@@ -1517,7 +1114,7 @@ class AuthService {
                 const lockReason = user.lockReason || 'Account is locked';
                 this.logger?.warn?.(`Login blocked - account locked for user: ${user.email} (sub: ${user.sub}). Reason: ${lockReason}`);
                 // Record blocked login attempt
-                await this.recordLoginAttempt(dto.identifier, false, 'account_locked');
+                await this.helpers.recordLoginAttempt(dto.identifier, false, 'account_locked');
                 // ============================================================================
                 // Audit: Record blocked login (account locked)
                 // ============================================================================
@@ -1660,7 +1257,7 @@ class AuthService {
                 [auth_challenge_dto_1.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);
+            await this.helpers.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
@@ -1668,7 +1265,7 @@ class AuthService {
         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);
+            await this.helpers.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, {
@@ -1802,7 +1399,7 @@ class AuthService {
         // 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);
+            await this.helpers.recordLoginAttempt(dto.identifier, false, 'account_inactive', user.id);
             // ============================================================================
             // Audit: Record blocked login (account inactive)
             // ============================================================================
@@ -1890,7 +1487,7 @@ class AuthService {
             failedLoginAttempts: 0,
         });
         // Record successful login attempt - use internal id
-        await this.recordLoginAttempt(dto.identifier, true, undefined, user.id);
+        await this.helpers.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
@@ -2022,896 +1619,140 @@ class AuthService {
         // Validate session and get challenge type
         const challengeSession = await this.challengeService.validateSession(session);
         // Validate response matches expected challenge
-        this.validateChallengeTypeMatch(challengeSession.challengeName, type);
+        this.helpers.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);
+        this.helpers.validateChallengeParams(type, responseData);
         // Handle challenge based on type
         switch (type) {
             case 'VERIFY_EMAIL':
-                return await this.handleVerifyEmail(challengeSession, responseData.code);
+                return await this.helpers.handleVerifyEmail(challengeSession, responseData.code);
             case 'VERIFY_PHONE':
-                return await this.handleVerifyPhone(challengeSession, responseData);
+                return await this.helpers.handleVerifyPhone(challengeSession, responseData);
             case 'MFA_REQUIRED':
-                return await this.handleMFAVerification(challengeSession, responseData);
+                return await this.helpers.handleMFAVerification(challengeSession, responseData, this.mfaService, this.trustedDeviceService, this.auditService);
             case 'FORCE_CHANGE_PASSWORD':
-                return await this.handleForceChangePassword(challengeSession, responseData.newPassword);
+                return await this.helpers.handleForceChangePassword(challengeSession, responseData.newPassword, this.passwordService, this.auditService);
             case 'MFA_SETUP_REQUIRED':
-                return await this.handleMFASetup(challengeSession, responseData);
+                return await this.helpers.handleMFASetup(challengeSession, responseData, this.mfaService, this.auditService);
             default:
                 throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Unknown challenge type: ${type}`);
         }
     }
     /**
-     * Validate that response type matches expected challenge type
-     */
-    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
+     * 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 dto - Resend code request with challenge session token
+     * @returns Destination info (masked email/phone)
+     * @throws {NAuthException} INVALID_CHALLENGE_SESSION | RATE_LIMIT_* | VALIDATION_FAILED
      *
-     * Service-level validation ensures Express/other frameworks get same validation as NestJS.
-     * This is critical for non-DTO-based applications.
+     * @example
+     * ```typescript
+     * const result = await authService.resendCode({ session: 'challenge-token' });
+     * // Returns: { destination: 'u***r@example.com' }
+     * ```
      */
-    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;
+    async resendCode(dto) {
+        // Ensure DTO is validated (supports direct usage without framework validation)
+        dto = await (0, dto_validator_1.ensureValidatedDto)(resend_code_dto_1.ResendCodeDTO, dto);
+        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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Challenge session has no associated user');
+        }
+        // Handle based on challenge type
+        switch (challengeSession.challengeName) {
+            case auth_challenge_dto_1.AuthChallenge.VERIFY_EMAIL: {
+                // Resend email verification
+                // Pass challengeSessionId to ensure new token is linked to this challenge session
+                const resendDto = Object.assign(new verify_email_dto_1.ResendVerificationEmailDTO(), {
+                    sub: user.sub,
+                    challengeSessionId: challengeSession.id,
+                });
+                await this.emailVerificationService.resendVerificationEmail(resendDto);
+                const maskedEmail = this.helpers.maskEmail(user.email);
+                this.logger?.debug?.(`Email verification code resent: user=${user.sub}, email=${maskedEmail}`);
+                return { destination: maskedEmail };
             }
-            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'] });
+            case auth_challenge_dto_1.AuthChallenge.VERIFY_PHONE: {
+                // Check if phone already collected
+                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.');
+                }
+                if (!this.phoneVerificationService) {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'Phone verification service is not available');
                 }
-                break;
+                // Resend SMS verification
+                const resendDto = Object.assign(new verify_phone_dto_1.ResendVerificationSMSDTO(), { sub: user.sub });
+                await this.phoneVerificationService.resendVerificationSMS(resendDto);
+                const maskedPhone = this.helpers.maskPhone(user.phone);
+                this.logger?.debug?.(`Phone verification code resent: user=${user.sub}, phone=${maskedPhone}`);
+                return { destination: maskedPhone };
             }
-            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' });
+            case auth_challenge_dto_1.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;
+                const method = metadata?.method;
+                if (!method) {
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Cannot resend MFA code: method not specified in session');
                 }
-                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',
+                // 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 verify_phone_dto_1.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.helpers.maskPhone(user.phone) : '***-***-****';
+                        return { destination: maskedPhone };
                     }
-                }
-                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' });
+                    // For Email, use email verification service directly to pass challengeSessionId
+                    if (method === 'email' && this.emailVerificationService) {
+                        const emailDto = Object.assign(new verify_email_dto_1.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.helpers.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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
+                    }
+                    const provider = this.mfaService.getProvider(method);
+                    if (!provider.sendChallenge) {
+                        throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 };
                 }
-                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;
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Cannot resend code for MFA method '${method}'. Only SMS and Email support code resending.`);
             }
+            default:
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Cannot resend code for challenge type '${challengeSession.challengeName}'`);
         }
     }
-    /**
-     * Handle VERIFY_EMAIL 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
-     */
-    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}`);
-                // ============================================================================
-                // Audit: Record successful login after phone verification
-                // ============================================================================
-                const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-                if (fireAndForget) {
-                    this.auditService
-                        ?.recordEvent({
-                        userId: user.id,
-                        eventType: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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
-     */
-    async handleMFAVerification(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');
-        }
-        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 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 this.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 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: 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 this.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) {
-            this.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 this.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 (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: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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
-     */
-    async handleForceChangePassword(challengeSession, newPassword) {
-        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',
-            },
-        });
-        // 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}`);
-            // ============================================================================
-            // Audit: Record successful login after password change
-            // ============================================================================
-            const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-            if (fireAndForget) {
-                this.auditService
-                    ?.recordEvent({
-                    userId: user.id,
-                    eventType: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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
-     */
-    async handleMFASetup(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');
-        }
-        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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
-        }
-        // Get provider
-        const provider = this.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}`);
-            // ============================================================================
-            // Audit: Record successful login after MFA setup
-            // ============================================================================
-            const fireAndForget = this.config.auditLogs?.fireAndForget !== false;
-            if (fireAndForget) {
-                this.auditService
-                    ?.recordEvent({
-                    userId: user.id,
-                    eventType: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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) {
-        // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(resend_code_dto_1.ResendCodeDTO, dto);
-        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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Challenge session has no associated user');
-        }
-        // Handle based on challenge type
-        switch (challengeSession.challengeName) {
-            case auth_challenge_dto_1.AuthChallenge.VERIFY_EMAIL: {
-                // Resend email verification
-                // Pass challengeSessionId to ensure new token is linked to this challenge session
-                const resendDto = Object.assign(new verify_email_dto_1.ResendVerificationEmailDTO(), {
-                    sub: user.sub,
-                    challengeSessionId: challengeSession.id,
-                });
-                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 auth_challenge_dto_1.AuthChallenge.VERIFY_PHONE: {
-                // Check if phone already collected
-                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.');
-                }
-                if (!this.phoneVerificationService) {
-                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'Phone verification service is not available');
-                }
-                // Resend SMS verification
-                const resendDto = Object.assign(new verify_phone_dto_1.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 auth_challenge_dto_1.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;
-                const method = metadata?.method;
-                if (!method) {
-                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 verify_phone_dto_1.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 verify_email_dto_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'MFA service is not available');
-                    }
-                    const provider = this.mfaService.getProvider(method);
-                    if (!provider.sendChallenge) {
-                        throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 };
-                }
-                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Cannot resend code for MFA method '${method}'. Only SMS and Email support code resending.`);
-            }
-            default:
-                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Cannot resend code for challenge type '${challengeSession.challengeName}'`);
-        }
-    }
-    /**
-     * Mask email for display (helper method)
-     */
-    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 display (helper method)
-     */
-    maskPhone(phone) {
-        const digits = phone.replace(/\D/g, '');
-        const lastFour = digits.slice(-4);
-        return `***-***-${lastFour}`;
-    }
     /**
      * Registers the current device as trusted for the user (opt-in).
      *
@@ -3289,13 +2130,39 @@ class AuthService {
     // Logout
     // ============================================================================
     /**
-     * Logout user (revoke session)
+     * Logout user from current session
      *
-     * Session ID is automatically extracted from the JWT token context (via ClientInfoService), similar to how IP address and user agent are handled.
+     * Revokes 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.
+     *
+     * Usage Pattern:
+     * - **User-context only**: This method operates on the current authenticated session
+     * - Session ID is transparently extracted from JWT token in request context
+     * - User can only logout their own current session (not other sessions)
+     * - For logging out other sessions, use logoutSession() or logoutAll()
      *
-     * @param dto - Logout options (forgetMe flag)
+     * Security:
+     * - Requires authentication - session ID must be present in request context
+     * - Endpoint MUST be protected by authentication guards
+     * - User cannot specify which session to logout (always current session)
+     * - Optional sub validation for additional security
+     *
+     * @param dto - Logout options (optional sub for validation, optional forgetMe flag)
      * @returns Success status
-     * @throws {NAuthException} If session ID is not available in request context
+     * @throws {NAuthException} SESSION_NOT_FOUND if session ID not found in request context
+     *
+     * @example
+     * ```typescript
+     * @UseGuards(AuthGuard)
+     * @Get('logout')
+     * async logout(@CurrentUser() user: IUser, @Query('forgetMe') forgetMe?: string) {
+     *   const dto = new LogoutDTO();
+     *   dto.sub = user.sub; // Optional validation
+     *   dto.forgetMe = forgetMe === 'true';
+     *   return this.authService.logout(dto);
+     * }
+     * ```
      */
     async logout(dto) {
         // Ensure DTO is validated (supports direct usage without framework validation)
@@ -3388,44 +2255,50 @@ class AuthService {
         // ============================================================================
         const response = this.clientInfoService.getResponse();
         if (response && this.config.tokenDelivery?.method !== 'json') {
-            this.clearAuthCookies(response, dto.forgetMe ?? false);
+            this.helpers.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
-     */
-    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);
-        }
-    }
     /**
      * Global signout (revoke all user sessions)
-     * @param sub - External user identifier (sub/UUID)
+     *
+     * Revokes all active sessions for a user across all devices.
+     * Optionally revokes all trusted devices if forgetDevices flag is set.
+     *
+     * Usage Patterns:
+     * - **User-initiated**: User logs out from all their own sessions (protected endpoint, user provides their own sub)
+     * - **Admin-initiated**: Admin force-logs out any user (admin-protected endpoint, admin provides target user's sub)
+     *
+     * Security:
+     * - Requires explicit sub parameter
+     * - NO built-in authentication - endpoint MUST be protected by guards
+     * - For user endpoints: Extract sub from authenticated user context (@CurrentUser)
+     * - For admin endpoints: Accept sub from route parameter and protect with admin guards
+     *
+     * @param dto - User sub and optional forgetDevices flag
      * @returns Number of sessions revoked
+     * @throws {NAuthException} NOT_FOUND if user not found
+     *
+     * @example User-initiated (user context)
+     * ```typescript
+     * // Controller extracts sub from authenticated user
+     * @UseGuards(AuthGuard)
+     * @Post('logout/all')
+     * async logoutAll(@CurrentUser() user: IUser, @Body() body: { forgetDevices?: boolean }) {
+     *   return this.authService.logoutAll({ sub: user.sub, forgetDevices: body.forgetDevices });
+     * }
+     * ```
+     *
+     * @example Admin-initiated (admin manages any user)
+     * ```typescript
+     * // Admin provides target user's sub
+     * @UseGuards(AuthGuard, AdminGuard)
+     * @Post('admin/users/:sub/logout-all')
+     * async adminLogoutAll(@Param('sub') sub: string, @Body() body: { forgetDevices?: boolean }) {
+     *   return this.authService.logoutAll({ sub, forgetDevices: body.forgetDevices });
+     * }
+     * ```
      */
     async logoutAll(dto) {
         // Ensure DTO is validated (supports direct usage without framework validation)
@@ -3534,888 +2407,332 @@ class AuthService {
         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.helpers.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.
+     * Get all active sessions for a 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.
+     * Returns session details including authentication method (password, social, admin).
+     * For social logins, check session metadata for the specific OAuth provider.
+     * Current session (if called from authenticated context) is marked with isCurrent=true.
      *
-     * @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.
+     * Usage Patterns:
+     * - **User viewing own sessions**: User views their active sessions (protected endpoint, user provides their own sub)
+     * - **Admin viewing any user's sessions**: Admin views any user's sessions (admin-protected endpoint, admin provides target user's sub)
      *
-     * @example
-     * ```typescript
-     * await authService.changePassword('user-uuid', {
-     *   oldPassword: 'currentPass123!',
-     *   newPassword: 'newStr0ngPass!@#',
-     * });
-     * ```
-     */
-    async changePassword(dto) {
-        // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(change_password_request_dto_1.ChangePasswordRequestDTO, dto);
-        // Get user by sub
-        const user = (await this.userRepository.findOne({ where: { sub: dto.sub } }));
-        if (!user || !user.passwordHash) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
-        }
-        // ============================================================================
-        // Lifecycle Hook: beforePasswordChange (TODO: Implement provider-based hook)
-        // ============================================================================
-        // TODO: Implement provider-based hook for beforePasswordChange
-        // const allowed = await this.hookRegistry.executeBeforePasswordChange(dto.sub, dto.oldPassword);
-        // if (!allowed) {
-        //   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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.PASSWORD_INCORRECT, 'Current password is incorrect');
-        }
-        // ============================================================================
-        // Lifecycle Hook: afterPasswordChange (TODO: Implement provider-based hook)
-        // ============================================================================
-        // TODO: Implement provider-based hook for afterPasswordChange
-        // await this.hookRegistry.executeAfterPasswordChange(dto.sub);
-        await this.updateUserPassword({
-            user,
-            newPassword: dto.newPassword,
-            mustChangePassword: false,
-            revokeSessions: true,
-            revokeReason: 'Password changed',
-            audit: {
-                eventType: auth_audit_event_type_enum_1.AuthAuditEventType.PASSWORD_CHANGED,
-                eventStatus: 'SUCCESS',
-            },
-        });
-        return { success: true };
-    }
-    /**
-     * Update user profile attributes.
+     * Security:
+     * - Requires explicit sub parameter
+     * - NO built-in authentication - endpoint MUST be protected by guards
+     * - For user endpoints: Extract sub from authenticated user context (@CurrentUser)
+     * - For admin endpoints: Accept sub from route parameter and protect with admin guards
      *
-     * Updates user fields (name, email, phone, username, metadata) and enforces unique constraints and verification rules.
+     * @param dto - Contains user sub
+     * @returns Array of sessions with device info, auth method, and isCurrent flag
+     * @throws {NAuthException} NOT_FOUND if user not found
      *
-     * @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 User viewing own sessions
+     * ```typescript
+     * @UseGuards(AuthGuard)
+     * @Get('sessions')
+     * async getSessions(@CurrentUser() user: IUser) {
+     *   return this.authService.getUserSessions({ sub: user.sub });
+     * }
+     * ```
      *
-     * @example
-     * await authService.updateUserAttributes(sub, { email: 'test@example.com' });
+     * @example Admin viewing any user's sessions
+     * ```typescript
+     * @UseGuards(AuthGuard, AdminGuard)
+     * @Get('admin/users/:sub/sessions')
+     * async adminGetSessions(@Param('sub') sub: string) {
+     *   return this.authService.getUserSessions({ sub });
+     * }
+     * ```
      */
-    async updateUserAttributes(dto) {
+    async getUserSessions(dto) {
         // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(update_user_attributes_request_dto_1.UpdateUserAttributesRequestDTO, dto);
-        // Find user by sub (external identifier)
+        dto = await (0, dto_validator_1.ensureValidatedDto)(get_user_sessions_dto_1.GetUserSessionsDTO, dto);
+        // Get user by sub to get internal id
         const user = (await this.userRepository.findOne({ where: { sub: dto.sub } }));
         if (!user) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
         }
-        // Check for uniqueness constraints - use internal id
-        await this.validateUniquenessConstraints(user.id, dto);
-        // Prepare update object
-        const updateFields = {};
-        // 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: mfa_method_enum_1.MFAMethod.EMAIL,
-                                isActive: true,
-                            },
-                        }));
-                        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.id;
-                                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: auth_audit_event_type_enum_1.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: mfa_method_enum_1.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,
-                                },
-                            }));
-                            // 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) {
-                        // 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: mfa_method_enum_1.MFAMethod.SMS,
-                                isActive: true,
-                            },
-                        }));
-                        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.id;
-                                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: auth_audit_event_type_enum_1.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: mfa_method_enum_1.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,
-                                },
-                            }));
-                            // 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) {
-                        // 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;
-        }
-        // 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);
-        // Fetch updated user - use internal id
-        const updatedUser = (await this.userRepository.findOne({ where: { id: user.id } }));
-        if (!updatedUser) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 = {};
-            // 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 = {};
-                // 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: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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: auth_audit_event_type_enum_1.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,
-            });
-        }
-        // ============================================================================
-        // Hook: Execute user profile updated hooks
-        // ============================================================================
-        try {
-            // Build changed fields array with old/new values
-            const changedFields = [];
-            // Track all fields that were in updateFields
-            for (const fieldName of Object.keys(updateFields)) {
-                changedFields.push({
-                    fieldName,
-                    oldValue: user[fieldName],
-                    newValue: updateFields[fieldName],
-                });
-            }
-            // Get client info from ClientInfoService
-            const clientInfo = this.clientInfoService.get();
-            // Execute hooks (non-blocking)
-            await this.hookRegistry.executeUserProfileUpdated({
-                user: updatedUser,
-                changedFields,
-                updateSource: 'user_request',
-                clientInfo: {
-                    ipAddress: clientInfo.ipAddress,
-                    userAgent: clientInfo.userAgent,
-                    ipCountry: clientInfo.ipCountry,
-                    ipCity: clientInfo.ipCity,
-                },
-            });
-        }
-        catch (hookError) {
-            // Non-blocking: Log but continue
-            const errorMessage = hookError instanceof Error ? hookError.message : 'Unknown error';
-            this.logger?.error?.(`Failed to execute userProfileUpdated hooks: ${errorMessage}`, {
-                error: hookError,
-                userId: user.id,
-            });
-        }
-        // Return user response DTO
-        return user_response_dto_1.UserResponseDto.fromEntity(updatedUser);
+        // Get current session ID from context (if available)
+        const clientInfo = this.clientInfoService.get();
+        const currentSessionId = clientInfo.sessionId ? String(clientInfo.sessionId) : null;
+        // Get all active sessions for user
+        const sessions = await this.sessionService.findUserSessions(user.id);
+        // Map sessions to response format
+        const sessionInfos = sessions.map((session) => {
+            // Determine auth method and provider
+            let authMethod = session.authMethod || null;
+            let authProvider = null;
+            // If authMethod is 'social' or starts with 'admin-', extract provider from metadata
+            if (authMethod === 'social' || authMethod?.startsWith('admin-')) {
+                // Check metadata for provider information
+                const metadata = session.metadata || {};
+                authProvider = metadata.authProvider || metadata.provider || null;
+                // If no provider in metadata but authMethod contains it (e.g., 'google', 'facebook')
+                if (!authProvider && authMethod && authMethod !== 'social' && !authMethod.startsWith('admin-')) {
+                    authProvider = authMethod;
+                    authMethod = 'social';
+                }
+            }
+            // Determine if this is the current session
+            const isCurrent = currentSessionId !== null && String(session.id) === currentSessionId;
+            return {
+                sessionId: String(session.id),
+                deviceId: session.deviceId,
+                deviceName: session.deviceName,
+                deviceType: session.deviceType,
+                platform: session.platform,
+                browser: session.browser,
+                ipAddress: session.ipAddress,
+                ipCountry: session.ipCountry,
+                ipCity: session.ipCity,
+                lastActivityAt: session.lastActivityAt || session.createdAt,
+                createdAt: session.createdAt,
+                expiresAt: session.expiresAt,
+                isRemembered: session.isRemembered,
+                isCurrent,
+                authMethod,
+                authProvider,
+            };
+        });
+        return { sessions: sessionInfos };
     }
     /**
-     * Update email and/or phone verification status.
-     *
-     * Intended for admin use cases such as migration or offline validation.
-     * Updates verification status without requiring actual verification codes.
-     *
-     * Validation:
-     * - Cannot set verified=true if email/phone doesn't exist
-     * - Can set verified=false even if email/phone doesn't exist (default state)
-     * - Only updates provided fields (partial update)
-     *
-     * Audit:
-     * - Records EMAIL_VERIFIED or PHONE_VERIFIED audit events
-     * - Includes performedBy from authenticated admin context
+     * Logout a specific session by ID
      *
-     * @param dto - Request DTO containing sub and verification status flags
-     * @returns Updated user object
-     * @throws {NAuthException} If user not found or trying to verify non-existent email/phone
+     * Revokes a specific session for a user. Validates session belongs to requesting user.
+     * Automatically clears cookies if logging out the current session.
+     * Useful for "sign out from device" functionality in user dashboards.
      *
-     * @example
-     * ```typescript
-     * // Update email verification only
-     * await authService.updateVerifiedStatus({
-     *   sub: 'user-uuid',
-     *   isEmailVerified: true
-     * });
+     * Usage Patterns:
+     * - **User logging out own session**: User revokes specific session (protected endpoint, user provides their own sub)
+     * - **Admin revoking any user's session**: Admin revokes specific session for any user (admin-protected endpoint, admin provides target user's sub)
      *
-     * // Update both email and phone verification
-     * await authService.updateVerifiedStatus({
-     *   sub: 'user-uuid',
-     *   isEmailVerified: true,
-     *   isPhoneVerified: false
-     * });
+     * Security:
+     * - Requires explicit sub parameter
+     * - Validates session belongs to user (prevents unauthorized session revocation)
+     * - NO built-in authentication - endpoint MUST be protected by guards
+     * - For user endpoints: Extract sub from authenticated user context (@CurrentUser)
+     * - For admin endpoints: Accept sub from route parameter and protect with admin guards
+     *
+     * @param dto - Contains sessionId and user sub
+     * @returns Success status and whether it was the current session
+     * @throws {NAuthException} NOT_FOUND if user not found
+     * @throws {NAuthException} SESSION_NOT_FOUND if session not found
+     * @throws {NAuthException} FORBIDDEN if session doesn't belong to user
+     *
+     * @example User logging out own session
+     * ```typescript
+     * @UseGuards(AuthGuard)
+     * @Delete('sessions/:sessionId')
+     * async logoutSession(@CurrentUser() user: IUser, @Param('sessionId') sessionId: string) {
+     *   return this.authService.logoutSession({ sub: user.sub, sessionId });
+     * }
+     * ```
+     *
+     * @example Admin revoking any user's session (if needed)
+     * ```typescript
+     * @UseGuards(AuthGuard, AdminGuard)
+     * @Delete('admin/users/:sub/sessions/:sessionId')
+     * async adminRevokeSession(@Param('sub') sub: string, @Param('sessionId') sessionId: string) {
+     *   return this.authService.logoutSession({ sub, sessionId });
+     * }
      * ```
      */
-    async updateVerifiedStatus(dto) {
+    async logoutSession(dto) {
         // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(update_verified_status_request_dto_1.UpdateVerifiedStatusRequestDTO, dto);
-        // Find user by sub (external identifier)
+        dto = await (0, dto_validator_1.ensureValidatedDto)(logout_session_dto_1.LogoutSessionDTO, dto);
+        // Get user by sub to get internal id
         const user = (await this.userRepository.findOne({ where: { sub: dto.sub } }));
         if (!user) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
         }
-        // Validate that email exists if trying to set isEmailVerified to true
-        if (dto.isEmailVerified === true && !user.email) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Cannot set email verification to true: user does not have an email address');
+        // Parse session ID (can be string or number)
+        const sessionId = typeof dto.sessionId === 'string' ? parseInt(dto.sessionId, 10) : dto.sessionId;
+        if (isNaN(sessionId)) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Invalid session ID');
         }
-        // Validate that phone exists if trying to set isPhoneVerified to true
-        if (dto.isPhoneVerified === true && !user.phone) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Cannot set phone verification to true: user does not have a phone number');
-        }
-        // Prepare update object - only include fields that were provided
-        const updateFields = {};
-        if (dto.isEmailVerified !== undefined) {
-            updateFields.isEmailVerified = dto.isEmailVerified;
-        }
-        if (dto.isPhoneVerified !== undefined) {
-            updateFields.isPhoneVerified = dto.isPhoneVerified;
-        }
-        // If no fields to update, return current user
-        if (Object.keys(updateFields).length === 0) {
-            return user_response_dto_1.UserResponseDto.fromEntity(user);
+        // Get session to verify ownership
+        const session = await this.sessionService.findById(sessionId);
+        if (!session) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.SESSION_NOT_FOUND, 'Session not found');
         }
-        // Update user - use internal id for database update
-        await this.userRepository.update(user.id, updateFields);
-        // Reload user to get updated values
-        const updatedUser = (await this.userRepository.findOne({ where: { id: user.id } }));
-        if (!updatedUser) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'Failed to reload user after update');
+        // Verify session belongs to user
+        if (session.userId !== user.id) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.FORBIDDEN, 'Session does not belong to user');
         }
-        // ============================================================================
-        // Audit: Record verification status changes
-        // ============================================================================
-        if (this.auditService) {
-            // Record email verification change if provided
-            if (dto.isEmailVerified !== undefined) {
-                try {
-                    await this.auditService.recordEvent({
-                        userId: user.id,
-                        eventType: auth_audit_event_type_enum_1.AuthAuditEventType.EMAIL_VERIFIED,
-                        eventStatus: dto.isEmailVerified ? 'SUCCESS' : 'INFO',
-                        description: dto.isEmailVerified
-                            ? 'Email verification status set to verified (admin action)'
-                            : 'Email verification status set to unverified (admin action)',
-                        reason: 'admin_verification_update',
-                        metadata: {
-                            previousStatus: user.isEmailVerified,
-                            newStatus: dto.isEmailVerified,
-                            updateMethod: 'admin_direct',
-                            // Client info automatically included from context (performedBy auto-populated)
-                        },
-                    });
-                }
-                catch (auditError) {
-                    // Non-blocking: Log but continue
-                    const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                    this.logger?.error?.(`Failed to record EMAIL_VERIFIED audit event: ${errorMessage}`, {
-                        error: auditError,
-                        userId: user.id,
-                    });
-                }
-            }
-            // Record phone verification change if provided
-            if (dto.isPhoneVerified !== undefined) {
-                try {
-                    await this.auditService.recordEvent({
-                        userId: user.id,
-                        eventType: auth_audit_event_type_enum_1.AuthAuditEventType.PHONE_VERIFIED,
-                        eventStatus: dto.isPhoneVerified ? 'SUCCESS' : 'INFO',
-                        description: dto.isPhoneVerified
-                            ? 'Phone verification status set to verified (admin action)'
-                            : 'Phone verification status set to unverified (admin action)',
-                        reason: 'admin_verification_update',
-                        metadata: {
-                            previousStatus: user.isPhoneVerified,
-                            newStatus: dto.isPhoneVerified,
-                            updateMethod: 'admin_direct',
-                            // Client info automatically included from context (performedBy auto-populated)
-                        },
-                    });
-                }
-                catch (auditError) {
-                    // Non-blocking: Log but continue
-                    const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                    this.logger?.error?.(`Failed to record PHONE_VERIFIED audit event: ${errorMessage}`, {
-                        error: auditError,
-                        userId: user.id,
-                    });
-                }
+        // Check if this is the current session
+        const clientInfo = this.clientInfoService.get();
+        const currentSessionId = clientInfo.sessionId ? parseInt(String(clientInfo.sessionId), 10) : null;
+        const wasCurrentSession = currentSessionId !== null && sessionId === currentSessionId;
+        // Revoke the session
+        await this.sessionService.revokeSession(sessionId, 'User requested logout', {
+            requestedBy: dto.sub,
+            wasCurrentSession,
+        });
+        // Clear cookies if this was the current session
+        if (wasCurrentSession) {
+            const response = this.clientInfoService.getResponse();
+            if (response && this.config.tokenDelivery?.method !== 'json') {
+                this.helpers.clearAuthCookies(response, false);
+                this.logger?.debug?.('Auth cookies cleared automatically on session logout');
             }
         }
-        // ============================================================================
-        // Hook: Execute user profile updated hooks
-        // ============================================================================
-        try {
-            // Build changed fields array with old/new values
-            const changedFields = [];
-            if (dto.isEmailVerified !== undefined) {
-                changedFields.push({
-                    fieldName: 'isEmailVerified',
-                    oldValue: user.isEmailVerified,
-                    newValue: dto.isEmailVerified,
+        // Record audit event
+        if (this.auditService) {
+            try {
+                await this.auditService.recordEvent({
+                    userId: user.id,
+                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.SESSION_REVOKED,
+                    eventStatus: 'INFO',
+                    reason: 'user_requested',
+                    description: `Session revoked by user request${wasCurrentSession ? ' (current session)' : ''}`,
+                    metadata: {
+                        sessionId,
+                        wasCurrentSession,
+                    },
                 });
             }
-            if (dto.isPhoneVerified !== undefined) {
-                changedFields.push({
-                    fieldName: 'isPhoneVerified',
-                    oldValue: user.isPhoneVerified,
-                    newValue: dto.isPhoneVerified,
+            catch (auditError) {
+                // Non-blocking: Log but continue
+                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                this.logger?.error?.(`Failed to record SESSION_REVOKED audit event: ${errorMessage}`, {
+                    error: auditError,
+                    userId: user.id,
                 });
             }
-            // Get client info from ClientInfoService
-            const clientInfo = this.clientInfoService.get();
-            // Execute hooks (non-blocking)
-            await this.hookRegistry.executeUserProfileUpdated({
-                user: updatedUser,
-                changedFields,
-                updateSource: 'admin_action',
-                clientInfo: {
-                    ipAddress: clientInfo.ipAddress,
-                    userAgent: clientInfo.userAgent,
-                    ipCountry: clientInfo.ipCountry,
-                    ipCity: clientInfo.ipCity,
-                },
-            });
-        }
-        catch (hookError) {
-            // Non-blocking: Log but continue
-            const errorMessage = hookError instanceof Error ? hookError.message : 'Unknown error';
-            this.logger?.error?.(`Failed to execute userProfileUpdated hooks: ${errorMessage}`, {
-                error: hookError,
-                userId: user.id,
-            });
         }
-        // Return user response DTO
-        return user_response_dto_1.UserResponseDto.fromEntity(updatedUser);
+        return {
+            success: true,
+            wasCurrentSession,
+        };
     }
+    // ============================================================================
+    // Password Management
+    // ============================================================================
     /**
-     * Ensures email, phone, and username are unique for other users before update.
+     * Change the password for an existing user.
      *
-     * Throws if another user already has the specified email, phone, or username.
+     * 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 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
+     * @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.validateUniquenessConstraints(1, { email: "test@example.com" });
+     * await authService.changePassword('user-uuid', {
+     *   oldPassword: 'currentPass123!',
+     *   newPassword: 'newStr0ngPass!@#',
+     * });
      * ```
      */
-    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');
-            }
+    async changePassword(dto) {
+        // Ensure DTO is validated (supports direct usage without framework validation)
+        dto = await (0, dto_validator_1.ensureValidatedDto)(change_password_request_dto_1.ChangePasswordRequestDTO, dto);
+        // Get user by sub
+        const user = (await this.userRepository.findOne({ where: { sub: dto.sub } }));
+        if (!user || !user.passwordHash) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
         }
-        if (conflicts.length > 0) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, conflicts.join(', '), {
-                conflicts,
-            });
+        // ============================================================================
+        // Lifecycle Hook: beforePasswordChange (TODO: Implement provider-based hook)
+        // ============================================================================
+        // TODO: Implement provider-based hook for beforePasswordChange
+        // const allowed = await this.hookRegistry.executeBeforePasswordChange(dto.sub, dto.oldPassword);
+        // if (!allowed) {
+        //   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 nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.PASSWORD_INCORRECT, 'Current password is incorrect');
         }
+        // ============================================================================
+        // Lifecycle Hook: afterPasswordChange (TODO: Implement provider-based hook)
+        // ============================================================================
+        // TODO: Implement provider-based hook for afterPasswordChange
+        // await this.hookRegistry.executeAfterPasswordChange(dto.sub);
+        await this.helpers.updateUserPassword({
+            user,
+            newPassword: dto.newPassword,
+            mustChangePassword: false,
+            revokeSessions: true,
+            revokeReason: 'Password changed',
+            audit: {
+                eventType: auth_audit_event_type_enum_1.AuthAuditEventType.PASSWORD_CHANGED,
+                eventStatus: 'SUCCESS',
+            },
+        }, this.passwordService, this.auditService);
+        return { success: true };
     }
-    // ============================================================================
-    // Helper Methods
-    // ============================================================================
     /**
-     * Checks if the login identifier matches the specified allowed type.
+     * Update user profile attributes.
      *
-     * Determines if the given identifier is a valid email, username, phone, or allowed hybrid,
-     * according to the configured identifier type restriction.
+     * Updates user fields (name, email, phone, username, metadata) and enforces unique constraints and verification rules.
      *
-     * @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
+     * @param dto - UpdateUserAttributesRequestDTO containing sub and fields to update
+     * @returns Updated user object
+     * @throws {NAuthException} If user not found or unique constraint violated
      *
      * @example
-     * ```typescript
-     * // Email check
-     * const valid = this.validateIdentifierType('user@example.com', 'email'); // true
-     *
-     * // Username check
-     * const valid = this.validateIdentifierType('johndoe', 'username'); // true
-     * ```
+     * await authService.updateUserAttributes({ sub: 'user-uuid', email: 'test@example.com' });
      */
-    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
-        }
+    async updateUserAttributes(dto) {
+        return await this.userService.updateUserAttributes(dto);
     }
     /**
-     * Retrieves a user entity by login identifier.
+     * Update email and/or phone verification status.
      *
-     * 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.
+     * Intended for admin use cases such as migration or offline validation.
+     * Updates verification status without requiring actual verification codes.
      *
-     * @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
+     * Validation:
+     * - Cannot set verified=true if email/phone doesn't exist
+     * - Can set verified=false even if email/phone doesn't exist (default state)
+     * - Only updates provided fields (partial update)
      *
-     * @example
-     * ```typescript
-     * const user = await this.findUserByIdentifier('user@example.com');
-     * const user2 = await this.findUserByIdentifier('johndoe', 'username');
-     * ```
-     */
-    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());
-    }
-    /**
-     * Handles a failed login by recording the attempt, applying IP-based lockout policy,
-     * and invoking relevant hooks.
+     * Audit:
+     * - Records EMAIL_VERIFIED or PHONE_VERIFIED audit events
+     * - Includes performedBy from authenticated admin context
      *
-     * @param identifier - User identifier (email/username/phone)
-     * @param reason - Optional reason for failure
-     * @returns Promise<void>
+     * @param dto - Request DTO containing sub and verification status flags
+     * @returns Updated user object
+     * @throws {NAuthException} If user not found or trying to verify non-existent email/phone
      *
      * @example
      * ```typescript
-     * await authService.handleFailedLogin('user@example.com', 'invalid_credentials');
-     * ```
-     */
-    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');
-                // // Execute hook with IP address
-                // if (this.config.hooks?.afterAccountLock) {
-                //   await this.config.hooks.afterAccountLock(identifier, 'Too many failed attempts from IP', clientInfo);
-                // }
-            }
-        }
-        // ============================================================================
-        // Lifecycle Hook: afterLoginFailed (TODO: Implement provider-based hook)
-        // ============================================================================
-        // TODO: Implement provider-based hook for afterLoginFailed
-        // await this.hookRegistry.executeAfterLoginFailed(identifier, reason || 'unknown');
-    }
-    /**
-     * Records a login attempt with client context.
+     * // Update email verification only
+     * await authService.updateVerifiedStatus({
+     *   sub: 'user-uuid',
+     *   isEmailVerified: true
+     * });
      *
-     * @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>
+     * // Update both email and phone verification
+     * await authService.updateVerifiedStatus({
+     *   sub: 'user-uuid',
+     *   isEmailVerified: true,
+     *   isPhoneVerified: false
+     * });
+     * ```
      */
-    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);
+    async updateVerifiedStatus(dto) {
+        return await this.userService.updateVerifiedStatus(dto);
     }
+    // ============================================================================
+    // Helper Methods
+    // ============================================================================
+    // NOTE: Private helper methods have been moved to AuthServiceInternalHelpers
+    // Use this.helpers.methodName() to access them
     /**
      * Get user for authentication context
      *
@@ -4437,90 +2754,53 @@ class AuthService {
      * ```
      */
     async getUserForAuthContext(sub) {
-        // Load user with all fields including passwordHash (needed to compute hasPasswordHash)
-        // NOTE: We need to load passwordHash before @AfterLoad hook deletes it
-        // The hook computes hasPasswordHash but deletes passwordHash, so we check it first
-        const user = await this.userRepository.findOne({
-            where: { sub },
-        });
-        if (!user) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
-        }
-        if (!user.isActive) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.ACCOUNT_INACTIVE, 'Account is not active');
-        }
-        // CRITICAL: The @AfterLoad hook computes hasPasswordHash but doesn't delete passwordHash anymore
-        // Use the computed value from the hook, or compute it from passwordHash if hook didn't run
-        const userWithPassword = user;
-        const hasPasswordHash = user.hasPasswordHash !== undefined ? user.hasPasswordHash : Boolean(userWithPassword.passwordHash);
-        // Create safe user object without sensitive fields
-        const safeUser = {
-            ...user,
-            hasPasswordHash,
-        };
-        // Remove sensitive fields (passwordHash may already be deleted by @AfterLoad hook, but ensure it's gone)
-        delete safeUser.passwordHash;
-        delete safeUser.totpSecret;
-        delete safeUser.backupCodes;
-        delete safeUser.passwordHistory;
-        return safeUser;
+        return await this.userService.getUserForAuthContext(sub);
     }
+    /**
+     * Get user by external identifier (sub/UUID).
+     *
+     * @param dto - GetUserByIdDTO containing sub
+     * @returns User response DTO or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await authService.getUserById({ sub: 'user-uuid' });
+     * ```
+     */
     async getUserById(dto) {
-        // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(get_user_by_id_dto_1.GetUserByIdDTO, dto);
-        const user = (await this.userRepository.findOne({ where: { sub: dto.sub } }));
-        return user ? user_response_dto_1.UserResponseDto.fromEntity(user) : null;
+        return await this.userService.getUserById(dto);
     }
     /**
      * 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
+     * @param dto - GetUserByEmailDTO containing email and optional requireEmailVerified
+     * @returns User response DTO or null if not found
      * @internal - For use by social auth providers
      *
      * @example
      * ```typescript
-     * const user = await authService.getUserByEmail('user@example.com', true);
+     * const user = await authService.getUserByEmail({ email: 'user@example.com', requireEmailVerified: true });
      * ```
      */
     async getUserByEmail(dto) {
-        // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(get_user_by_email_dto_1.GetUserByEmailDTO, dto);
-        const where = dto.requireEmailVerified
-            ? { email: dto.email, isEmailVerified: true }
-            : { email: dto.email };
-        const user = (await this.userRepository.findOne({ where }));
-        return user ? user_response_dto_1.UserResponseDto.fromEntity(user) : null;
+        return await this.userService.getUserByEmail(dto);
     }
     /**
      * 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
+     * @param dto - SetMustChangePasswordDTO containing userId (sub)
+     * @returns Success response
      * @throws {NAuthException} If user is not found or cannot change password
      *
      * @example
-     * await authService.setMustChangePassword('user-uuid-123');
+     * ```typescript
+     * await authService.setMustChangePassword({ userId: 'user-uuid-123' });
+     * ```
      */
     async setMustChangePassword(dto) {
-        // Ensure DTO is validated (supports direct usage without framework validation)
-        dto = await (0, dto_validator_1.ensureValidatedDto)(set_must_change_password_dto_1.SetMustChangePasswordDTO, dto);
-        const user = await this.userRepository.findOne({ where: { sub: dto.userId } });
-        if (!user) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.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 nauth_exception_1.NAuthException(error_codes_enum_1.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 };
+        return await this.userService.setMustChangePassword(dto);
     }
     /**
      * Admin-only: Reset a user's password by identifier.
@@ -4573,7 +2853,7 @@ class AuthService {
         // If not found by sub, try by identifier (email, username, phone)
         if (!user) {
             this.logger?.debug?.(`Searching by identifier (email/username/phone): ${dto.identifier}`);
-            user = await this.findUserByIdentifier(dto.identifier);
+            user = await this.helpers.findUserByIdentifier(dto.identifier);
         }
         if (!user) {
             this.logger?.warn?.(`Password reset failed - user not found: ${dto.identifier}`);
@@ -4582,7 +2862,7 @@ class AuthService {
         const mustChangePassword = dto.mustChangePassword ?? true; // Default to true for security
         const revokeSessions = dto.revokeSessions !== false;
         const wasSocialOnly = !user.passwordHash;
-        const { sessionsRevoked } = await this.updateUserPassword({
+        const { sessionsRevoked } = await this.helpers.updateUserPassword({
             user,
             newPassword: dto.newPassword,
             mustChangePassword,
@@ -4601,7 +2881,7 @@ class AuthService {
                     wasSocialOnly,
                 },
             },
-        });
+        }, this.passwordService, this.auditService);
         // ============================================================================
         // Return Response
         // ============================================================================
@@ -4641,11 +2921,11 @@ class AuthService {
         }
         // Respect identifier type restrictions (if configured)
         if (this.config.login?.identifierType &&
-            !this.validateIdentifierType(dto.identifier, this.config.login.identifierType)) {
+            !this.helpers.validateIdentifierType(dto.identifier, this.config.login.identifierType)) {
             // Non-enumerating: return success without sending
             return response;
         }
-        const user = await this.findUserByIdentifier(dto.identifier, this.config.login?.identifierType);
+        const user = await this.helpers.findUserByIdentifier(dto.identifier, this.config.login?.identifierType);
         if (!user) {
             return response; // Non-enumerating
         }
@@ -4720,12 +3000,12 @@ class AuthService {
         if (!this.passwordResetService) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.SERVICE_UNAVAILABLE, 'Password reset is not available');
         }
-        const user = await this.findUserByIdentifier(dto.identifier, this.config.login?.identifierType);
+        const user = await this.helpers.findUserByIdentifier(dto.identifier, this.config.login?.identifierType);
         if (!user) {
             // Non-enumerating: treat as invalid code
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.PASSWORD_RESET_CODE_INVALID, 'Invalid password reset code');
         }
-        const { sessionsRevoked: _sessionsRevoked } = await this.updateUserPassword({
+        const { sessionsRevoked: _sessionsRevoked } = await this.helpers.updateUserPassword({
             user,
             newPassword: dto.newPassword,
             mustChangePassword: false,
@@ -4742,111 +3022,9 @@ class AuthService {
                 description: 'Password reset completed by user',
                 reason: 'forgot_password',
             },
-        });
+        }, this.passwordService, this.auditService);
         return { success: true, mustChangePassword: false };
     }
-    // ============================================================================
-    // Internal Password Update Orchestration (Single Source of Truth)
-    // ============================================================================
-    /**
-     * 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
-     * @returns Sessions revoked count (0 when not revoked)
-     * @throws {NAuthException} WEAK_PASSWORD | PASSWORD_REUSED | NOT_FOUND
-     */
-    async updateUserPassword(params) {
-        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 this.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 this.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 this.passwordService.hashPassword(newPassword);
-        const newHistory = userEntity.passwordHash
-            ? this.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 this.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 };
-    }
 }
 exports.AuthService = AuthService;
 //# sourceMappingURL=auth.service.js.map