@nauth-toolkit/core 0.1.39 → 0.1.41

package/dist/services/user.service.js

@@ -0,0 +1,1327 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserService = void 0;
+const client_info_service_1 = require("./client-info.service");
+const auth_audit_event_type_enum_1 = require("../enums/auth-audit-event-type.enum");
+const mfa_method_enum_1 = require("../enums/mfa-method.enum");
+const nauth_exception_1 = require("../exceptions/nauth.exception");
+const error_codes_enum_1 = require("../enums/error-codes.enum");
+const get_users_dto_1 = require("../dto/get-users.dto");
+const get_user_by_id_dto_1 = require("../dto/get-user-by-id.dto");
+const get_user_by_email_dto_1 = require("../dto/get-user-by-email.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 delete_user_dto_1 = require("../dto/delete-user.dto");
+const disable_user_dto_1 = require("../dto/disable-user.dto");
+const enable_user_dto_1 = require("../dto/enable-user.dto");
+const set_must_change_password_dto_1 = require("../dto/set-must-change-password.dto");
+const user_response_dto_1 = require("../dto/user-response.dto");
+const dto_validator_1 = require("../utils/dto-validator");
+const auth_service_internal_helpers_1 = require("./auth-service-internal-helpers");
+/**
+ * Internal user data management service
+ *
+ * Handles all user storage, query, and lifecycle operations.
+ * This class is NOT exported from the package and should only be used
+ * internally by AuthService.
+ *
+ * INTERNAL USE ONLY - DO NOT IMPORT DIRECTLY
+ *
+ * @internal
+ */
+class UserService {
+    userRepository;
+    loginAttemptRepository;
+    sessionService;
+    config;
+    logger;
+    mfaDeviceRepository;
+    auditService;
+    hookRegistry;
+    clientInfoService;
+    sessionRepository;
+    verificationTokenRepository;
+    socialAccountRepository;
+    challengeSessionRepository;
+    authAuditRepository;
+    trustedDeviceRepository;
+    helpers;
+    constructor(userRepository, loginAttemptRepository, sessionService, config, logger, mfaDeviceRepository, auditService, hookRegistry, clientInfoService = new client_info_service_1.ClientInfoService(), 
+    // Optional repositories for cascade deletion
+    sessionRepository, verificationTokenRepository, socialAccountRepository, challengeSessionRepository, authAuditRepository, trustedDeviceRepository, 
+    // Dependencies for helpers (needed for validateUniquenessConstraints)
+    helpers) {
+        this.userRepository = userRepository;
+        this.loginAttemptRepository = loginAttemptRepository;
+        this.sessionService = sessionService;
+        this.config = config;
+        this.logger = logger;
+        this.mfaDeviceRepository = mfaDeviceRepository;
+        this.auditService = auditService;
+        this.hookRegistry = hookRegistry;
+        this.clientInfoService = clientInfoService;
+        this.sessionRepository = sessionRepository;
+        this.verificationTokenRepository = verificationTokenRepository;
+        this.socialAccountRepository = socialAccountRepository;
+        this.challengeSessionRepository = challengeSessionRepository;
+        this.authAuditRepository = authAuditRepository;
+        this.trustedDeviceRepository = trustedDeviceRepository;
+        // Initialize helpers if provided, otherwise create a minimal one for validateUniquenessConstraints
+        if (helpers) {
+            this.helpers = helpers;
+        }
+        else {
+            // Create minimal helpers just for validateUniquenessConstraints
+            // This is a workaround - ideally we'd pass helpers from AuthService
+            // We use type assertions here because we're creating a minimal instance
+            // that only needs userRepository for validateUniquenessConstraints
+            this.helpers = new auth_service_internal_helpers_1.AuthServiceInternalHelpers(userRepository, loginAttemptRepository, undefined, // emailVerificationService - unused in validateUniquenessConstraints
+            undefined, // phoneVerificationService
+            undefined, // challengeService - unused in validateUniquenessConstraints
+            undefined, // challengeHelper - unused in validateUniquenessConstraints
+            clientInfoService, sessionService, undefined, // accountLockoutStorage - unused in validateUniquenessConstraints
+            config, logger);
+        }
+        this.logger?.log?.('UserService initialized');
+    }
+    // ============================================================================
+    // User Query Operations
+    // ============================================================================
+    /**
+     * Get paginated list of users with advanced filtering
+     *
+     * Supports pagination, boolean filters, exact match filters,
+     * date filters with operators (gt, gte, lt, lte, eq), and flexible sorting.
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Returns sanitized user data (no passwordHash, secrets)
+     *
+     * @param dto - Filters, pagination, sorting
+     * @returns Paginated user list with metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.getUsers({
+     *   page: 1,
+     *   limit: 20,
+     *   isEmailVerified: true,
+     *   hasSocialAuth: true,
+     *   createdAt: { operator: 'gte', value: new Date('2024-01-01') },
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    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),
+            },
+        };
+    }
+    /**
+     * 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 userService.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;
+    }
+    /**
+     * Get user by email address.
+     *
+     * @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 userService.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;
+    }
+    /**
+     * Get user for authentication context
+     *
+     * Loads user by sub (external identifier) with all fields needed for auth context.
+     * Computes hasPasswordHash from passwordHash, then removes passwordHash and other sensitive fields.
+     *
+     * This method is used by AuthHandler and AuthGuard to load authenticated users.
+     * It ensures consistent user object shape across platforms (core + NestJS).
+     *
+     * @param sub - External user identifier (UUID)
+     * @returns User object with hasPasswordHash flag, without sensitive fields
+     * @throws {NAuthException} If user not found or account is inactive
+     *
+     * @example
+     * ```typescript
+     * const user = await userService.getUserForAuthContext('user-uuid-123');
+     * // user.hasPasswordHash === true/false
+     * // user.passwordHash === undefined (removed)
+     * ```
+     */
+    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;
+    }
+    // ============================================================================
+    // User Update Operations
+    // ============================================================================
+    /**
+     * Update user profile attributes.
+     *
+     * Updates user fields (name, email, phone, username, metadata) and enforces unique constraints and verification rules.
+     *
+     * @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
+     * await userService.updateUserAttributes({ sub: 'user-uuid', email: 'test@example.com' });
+     * ```
+     */
+    async updateUserAttributes(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)
+        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.helpers.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);
+    }
+    /**
+     * 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
+     *
+     * @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
+     * // Update email verification only
+     * await userService.updateVerifiedStatus({
+     *   sub: 'user-uuid',
+     *   isEmailVerified: true
+     * });
+     *
+     * // Update both email and phone verification
+     * await userService.updateVerifiedStatus({
+     *   sub: 'user-uuid',
+     *   isEmailVerified: true,
+     *   isPhoneVerified: false
+     * });
+     * ```
+     */
+    async updateVerifiedStatus(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)
+        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');
+        }
+        // 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);
+        }
+        // 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');
+        }
+        // ============================================================================
+        // 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,
+                    });
+                }
+            }
+        }
+        // ============================================================================
+        // 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,
+                });
+            }
+            if (dto.isPhoneVerified !== undefined) {
+                changedFields.push({
+                    fieldName: 'isPhoneVerified',
+                    oldValue: user.isPhoneVerified,
+                    newValue: dto.isPhoneVerified,
+                });
+            }
+            // 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);
+    }
+    // ============================================================================
+    // User Lifecycle Operations
+    // ============================================================================
+    /**
+     * Delete a user and all associated data (cascade deletion).
+     *
+     * Permanently removes a user account and all related records:
+     * - Sessions
+     * - Verification tokens
+     * - MFA devices
+     * - Trusted devices
+     * - Social accounts
+     * - Login attempts
+     * - Challenge sessions
+     * - Audit logs (user-specific)
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Records ACCOUNT_DELETED audit event before deletion
+     * - Returns counts of deleted records for confirmation
+     *
+     * @param dto - DeleteUserDTO containing sub
+     * @returns Response with success status and deleted record counts
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.deleteUser({ sub: 'user-uuid-123' });
+     * console.log(`Deleted ${result.deletedRecords.sessions} sessions`);
+     * ```
+     */
+    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,
+            },
+        };
+    }
+    /**
+     * Administrative permanent account locking
+     *
+     * Sets permanent lock (lockedUntil=NULL) and immediately revokes all active sessions.
+     * Reuses existing rate-limit lock fields (isLocked, lockReason, lockedAt, lockedUntil).
+     *
+     * Permanent vs Temporary locks:
+     * - Rate limiting: lockedUntil = future date (temporary auto-unlock)
+     * - Admin disableUser: lockedUntil = NULL (permanent manual lock)
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Revokes all sessions immediately (forced logout)
+     * - Records ACCOUNT_DISABLED audit event with admin identifier
+     *
+     * @param dto - User sub and optional reason
+     * @returns User object with updated lock status and revoked session count
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.disableUser({
+     *   sub: 'user-uuid-123',
+     *   reason: 'Suspicious activity detected'
+     * });
+     * console.log(`Revoked ${result.revokedSessions} sessions`);
+     * ```
+     */
+    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,
+        };
+    }
+    /**
+     * Enable (unlock) user account
+     *
+     * Unlocks a previously locked user account by clearing all lock fields.
+     * This reverses the effect of disableUser() or rate-limit lockouts.
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Clears lock fields (isLocked, lockReason, lockedAt, lockedUntil)
+     * - Resets failed login attempts counter
+     * - Records ACCOUNT_ENABLED audit event with admin identifier
+     *
+     * @param dto - User sub to enable
+     * @returns User object with updated lock status
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.enableUser({
+     *   sub: 'user-uuid-123'
+     * });
+     * console.log(`User unlocked: ${result.user.email}`);
+     * ```
+     */
+    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,
+        };
+    }
+    /**
+     * Require user to change password at next login.
+     *
+     * Throws if user not found or has no password set (e.g. social login only).
+     *
+     * @param dto - SetMustChangePasswordDTO containing userId (sub)
+     * @returns Success response
+     * @throws {NAuthException} If user is not found or cannot change password
+     *
+     * @example
+     * ```typescript
+     * await userService.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 };
+    }
+}
+exports.UserService = UserService;
+//# sourceMappingURL=user.service.js.map