@nauth-toolkit/core 0.1.32 → 0.1.33

package/dist/services/auth.service.js

@@ -39,6 +39,11 @@ const risk_factor_enum_1 = require("../enums/risk-factor.enum");
 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");
@@ -93,12 +98,26 @@ class AuthService {
     mfaDeviceRepository;
     trustedDeviceService;
     passwordResetService;
+    socialAuthService;
+    sessionRepository;
+    verificationTokenRepository;
+    socialAccountRepository;
+    challengeSessionRepository;
+    authAuditRepository;
+    trustedDeviceRepository;
     constructor(userRepository, loginAttemptRepository, passwordService, jwtService, sessionService, challengeService, challengeHelper, emailVerificationService, clientInfoService, accountLockoutStorage, config, logger, 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
     mfaDeviceRepository, // Optional - available when MFA modules are imported
     trustedDeviceService, // Optional - only available when rememberDevices is not 'never'
-    passwordResetService) {
+    passwordResetService, // Optional - only available when configured by framework adapter
+    socialAuthService, // Optional - only available when social auth is configured
+    sessionRepository, // Optional - for cascade deletion
+    verificationTokenRepository, // Optional - for cascade deletion
+    socialAccountRepository, // Optional - for cascade deletion
+    challengeSessionRepository, // Optional - for cascade deletion
+    authAuditRepository, // Optional - for cascade deletion
+    trustedDeviceRepository) {
         this.userRepository = userRepository;
         this.loginAttemptRepository = loginAttemptRepository;
         this.passwordService = passwordService;
@@ -117,6 +136,13 @@ class AuthService {
         this.mfaDeviceRepository = mfaDeviceRepository;
         this.trustedDeviceService = trustedDeviceService;
         this.passwordResetService = passwordResetService;
+        this.socialAuthService = socialAuthService;
+        this.sessionRepository = sessionRepository;
+        this.verificationTokenRepository = verificationTokenRepository;
+        this.socialAccountRepository = socialAccountRepository;
+        this.challengeSessionRepository = challengeSessionRepository;
+        this.authAuditRepository = authAuditRepository;
+        this.trustedDeviceRepository = trustedDeviceRepository;
         this.logger?.log?.('AuthService initialized');
     }
     // ============================================================================
@@ -504,6 +530,748 @@ class AuthService {
         };
     }
     // ============================================================================
+    // Admin Social Signup
+    // ============================================================================
+    /**
+     * Administrative social user import with override capabilities
+     *
+     * Allows administrators to import existing social users from external platforms
+     * (e.g., Cognito, Auth0) into nauth with:
+     * - Bypass email/phone verification requirements
+     * - Optional password for hybrid social+password accounts
+     * - Social account linkage (provider + providerId)
+     * - Automatic user flag updates (hasSocialAuth)
+     *
+     * Use case: Migrating users from external authentication platforms while
+     * preserving their social login connections for transparent future logins.
+     *
+     * Security:
+     * - No built-in authentication - endpoint must be protected by framework adapter
+     * - All duplicate checks enforced (email, username, phone, provider+providerId)
+     * - Password policy enforced if password provided
+     * - Audit trail records admin-imported social accounts
+     *
+     * @param dto - Admin social signup DTO with social account details
+     * @returns User object and social account confirmation
+     * @throws {NAuthException} EMAIL_EXISTS | USERNAME_EXISTS | PHONE_EXISTS | SOCIAL_ACCOUNT_EXISTS | WEAK_PASSWORD
+     *
+     * @example
+     * ```typescript
+     * // Import social-only user from Cognito
+     * // Note: Email is automatically verified for social imports (like normal social signup)
+     * const result = await authService.adminSignupSocial({
+     *   email: 'user@example.com',
+     *   provider: 'google',
+     *   providerId: 'google_12345',
+     *   providerEmail: 'user@gmail.com',
+     *   socialMetadata: { sub: 'google_12345', given_name: 'John' },
+     * });
+     *
+     * // Import hybrid user with password + social
+     * const result = await authService.adminSignupSocial({
+     *   email: 'user@example.com',
+     *   password: 'SecurePass123!',
+     *   provider: 'apple',
+     *   providerId: 'apple_67890',
+     * });
+     * ```
+     */
+    async adminSignupSocial(dto) {
+        // Ensure DTO is validated (supports direct usage without framework validation)
+        dto = await (0, dto_validator_1.ensureValidatedDto)(admin_signup_social_dto_1.AdminSignupSocialDTO, dto);
+        // Get client info from request context (transparent!)
+        const clientInfo = this.clientInfoService.get();
+        this.logger?.log?.(`Admin social signup attempt for email: ${dto.email}, provider: ${dto.provider}`);
+        this.logger?.debug?.(`Admin social signup details: { email: ${dto.email}, username: ${dto.username || 'none'}, provider: ${dto.provider}, providerId: ${dto.providerId}, ip: ${clientInfo.ipAddress} }`);
+        // Skip signup.enabled check (admin bypass)
+        // Check if user already exists (email and username)
+        this.logger?.debug?.(`Checking if user exists: ${dto.email}`);
+        const existingUserByEmail = await this.userRepository.findOne({
+            where: { email: dto.email },
+        });
+        if (existingUserByEmail) {
+            this.logger?.warn?.(`Admin social signup failed - user already exists: ${dto.email}`);
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.EMAIL_EXISTS, 'User with this email already exists');
+        }
+        // Check for duplicate username if provided
+        if (dto.username) {
+            this.logger?.debug?.(`Checking if username exists: ${dto.username}`);
+            const existingUserByUsername = await this.userRepository.findOne({
+                where: { username: dto.username },
+            });
+            if (existingUserByUsername) {
+                this.logger?.warn?.(`Admin social signup failed - username already exists: ${dto.username}`);
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USERNAME_EXISTS, 'Username is already taken');
+            }
+        }
+        // Check for duplicate phone if provided and duplicates not allowed
+        if (dto.phone && !this.config.signup?.allowDuplicatePhones) {
+            this.logger?.debug?.(`Checking if phone exists: ${dto.phone}`);
+            const existingUserByPhone = await this.userRepository.findOne({
+                where: { phone: dto.phone },
+            });
+            if (existingUserByPhone) {
+                this.logger?.warn?.(`Admin social signup failed - phone already exists: ${dto.phone}`);
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.PHONE_EXISTS, 'Phone number is already registered');
+            }
+        }
+        // Check for duplicate provider+providerId
+        if (!this.socialAuthService) {
+            this.logger?.error?.('SocialAuthService not available - cannot import social user');
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.SOCIAL_CONFIG_MISSING, 'Social authentication is not configured');
+        }
+        this.logger?.debug?.(`Checking if social account exists: ${dto.provider}:${dto.providerId}`);
+        const existingSocialAccount = await this.socialAuthService.findSocialAccountByProvider(dto.provider, dto.providerId);
+        if (existingSocialAccount) {
+            this.logger?.warn?.(`Admin social signup failed - social account already exists: ${dto.provider}:${dto.providerId}`);
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.SOCIAL_ACCOUNT_EXISTS, 'This social account is already registered');
+        }
+        // Handle password (optional for hybrid accounts)
+        let passwordHash;
+        if (dto.password) {
+            // Validate password policy
+            this.logger?.debug?.('Validating password against policy');
+            const passwordValidation = await this.passwordService.validatePassword(dto.password, {
+                email: dto.email,
+                username: dto.username,
+            });
+            if (!passwordValidation.valid) {
+                this.logger?.warn?.(`Password validation failed for ${dto.email}: ${passwordValidation.errors.join(', ')}`);
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.WEAK_PASSWORD, passwordValidation.errors.join(', '), {
+                    errors: passwordValidation.errors,
+                });
+            }
+            // Hash password
+            passwordHash = await this.passwordService.hashPassword(dto.password);
+        }
+        else {
+            // Social-only user: no password (NULL in database)
+            passwordHash = null;
+        }
+        // Create user with override flags
+        // Note: Email is always verified for social imports (like normal social signup)
+        this.logger?.debug?.(`Creating admin social user record for: ${dto.email} || ${dto.username} || ${dto.phone} (isEmailVerified: true [auto-verified for social], isPhoneVerified: ${dto.isPhoneVerified || false})`);
+        const user = this.userRepository.create({
+            email: dto.email,
+            username: dto.username,
+            firstName: dto.firstName,
+            lastName: dto.lastName,
+            phone: dto.phone,
+            passwordHash, // null for social-only, hashed string for hybrid accounts
+            passwordChangedAt: dto.password ? new Date() : null, // Only set if password provided
+            isEmailVerified: true, // Always verified for social imports (like normal social signup)
+            isPhoneVerified: dto.isPhoneVerified ?? false, // Use DTO value or default to false
+            mustChangePassword: dto.mustChangePassword ?? false, // Use DTO value or default to false
+            isActive: true, // Always active
+            metadata: dto.metadata,
+            // hasSocialAuth and socialProviders will be updated by SocialAuthService.createOrUpdateSocialAccount()
+        });
+        let savedUser;
+        try {
+            savedUser = (await this.userRepository.save(user));
+            this.logger?.log?.(`Admin social user created successfully: ${dto.email} (sub: ${savedUser.sub}, provider: ${dto.provider})`);
+            // Create social account linkage
+            this.logger?.debug?.(`Creating social account linkage: ${dto.provider}:${dto.providerId}`);
+            await this.socialAuthService.createOrUpdateSocialAccount(savedUser.id, dto.provider, dto.providerId, dto.providerEmail || null, dto.socialMetadata);
+            this.logger?.log?.(`Social account linked successfully: ${dto.provider}:${dto.providerId}`);
+            // ============================================================================
+            // Audit: Record account creation by admin (social import)
+            // ============================================================================
+            try {
+                await this.auditService?.recordEvent({
+                    userId: savedUser.id,
+                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.ACCOUNT_CREATED,
+                    eventStatus: 'INFO',
+                    authMethod: 'admin-social',
+                    // Client info automatically included from context
+                    metadata: {
+                        email: savedUser.email,
+                        username: savedUser.username || null,
+                        createdByAdmin: true,
+                        adminIdentifier: clientInfo.ipAddress || 'unknown',
+                        isEmailVerified: savedUser.isEmailVerified,
+                        isPhoneVerified: savedUser.isPhoneVerified,
+                        mustChangePassword: savedUser.mustChangePassword,
+                        provider: dto.provider,
+                        providerId: dto.providerId,
+                        hasPassword: !!dto.password,
+                        socialImport: true,
+                    },
+                });
+            }
+            catch (auditError) {
+                // Non-blocking: Log but continue
+                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                this.logger?.error?.(`Failed to record ACCOUNT_CREATED audit event: ${errorMessage}`, {
+                    error: auditError,
+                    userId: savedUser.id,
+                });
+            }
+        }
+        catch (error) {
+            // Handle database constraint violations gracefully
+            if (error && typeof error === 'object' && 'code' in error && error.code === '23505') {
+                // PostgreSQL unique constraint violation
+                const dbError = error;
+                if (dbError.detail?.includes('email')) {
+                    this.logger?.warn?.(`Admin social signup failed - email constraint violation: ${dto.email}`);
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.EMAIL_EXISTS, 'User with this email already exists');
+                }
+                else if (dbError.detail?.includes('username')) {
+                    this.logger?.warn?.(`Admin social signup failed - username constraint violation: ${dto.username}`);
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.USERNAME_EXISTS, 'Username is already taken');
+                }
+                else if (dbError.detail?.includes('phone')) {
+                    this.logger?.warn?.(`Admin social signup failed - phone constraint violation: ${dto.phone}`);
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.PHONE_EXISTS, 'Phone number is already registered');
+                }
+                else if (dbError.detail?.includes('provider') && dbError.detail?.includes('providerId')) {
+                    this.logger?.warn?.(`Admin social signup failed - social account constraint violation: ${dto.provider}:${dto.providerId}`);
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.SOCIAL_ACCOUNT_EXISTS, 'This social account is already registered');
+                }
+                else {
+                    this.logger?.error?.(`Admin social signup failed - database constraint violation: ${dbError.message}`);
+                    throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.EMAIL_EXISTS, 'User with this information already exists', {
+                        conflictType: 'unknown',
+                    });
+                }
+            }
+            // Re-throw other database errors
+            const errorMessage = error instanceof Error ? error.message : 'Unknown database error';
+            this.logger?.error?.(`Admin social signup failed - database error: ${errorMessage}`);
+            throw error;
+        }
+        // No tokens, no challenge system, no verification emails - pure user creation with social linkage
+        // Return sanitized user object and social account confirmation
+        const userDto = user_response_dto_1.UserResponseDto.fromEntity(savedUser);
+        return {
+            user: userDto,
+            socialAccount: {
+                provider: dto.provider,
+                providerId: dto.providerId,
+                providerEmail: dto.providerEmail || null,
+            },
+        };
+    }
+    // ============================================================================
+    // Admin User Management
+    // ============================================================================
+    /**
+     * Administrative user deletion with complete cascade cleanup
+     *
+     * HARD DELETE - Permanently removes user and ALL associated data including:
+     * - Sessions, verification tokens, MFA devices, trusted devices
+     * - Social accounts, login attempts, challenge sessions, audit logs
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Records admin action in separate audit log (not deleted with user)
+     * - Irreversible operation - all data permanently removed
+     *
+     * @param dto - User sub to delete
+     * @returns Deletion confirmation with cascade counts
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await authService.deleteUser({ sub: 'user-uuid-123' });
+     * console.log(`Deleted user: ${result.deletedUserId}`);
+     * 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,
+            },
+        };
+    }
+    /**
+     * 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 authService.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),
+            },
+        };
+    }
+    /**
+     * 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 authService.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 authService.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,
+        };
+    }
+    // ============================================================================
     // User Login
     // ============================================================================
     /**
@@ -665,6 +1433,89 @@ class AuthService {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INVALID_CREDENTIALS, 'Invalid credentials');
         }
         // ============================================================================
+        // Account Lock Check (Admin Disabled / Rate Limit Lockout)
+        // ============================================================================
+        // Check if account is permanently locked (lockedUntil = NULL) or temporarily locked (lockedUntil > now)
+        if (user.isLocked) {
+            const now = new Date();
+            const isPermanentlyLocked = user.lockedUntil === null;
+            const isTemporarilyLocked = user.lockedUntil && new Date(user.lockedUntil) > now;
+            if (isPermanentlyLocked || isTemporarilyLocked) {
+                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');
+                // ============================================================================
+                // Audit: Record blocked login (account locked)
+                // ============================================================================
+                if (fireAndForget) {
+                    this.auditService
+                        ?.recordEvent({
+                        userId: user.id,
+                        eventType: auth_audit_event_type_enum_1.AuthAuditEventType.LOGIN_BLOCKED,
+                        eventStatus: 'FAILURE',
+                        authMethod: 'password',
+                        reason: 'account_locked',
+                        description: `Login blocked - account locked: ${lockReason}`,
+                        metadata: {
+                            lockReason: user.lockReason,
+                            lockedAt: user.lockedAt,
+                            lockedUntil: user.lockedUntil,
+                            isPermanent: isPermanentlyLocked,
+                        },
+                    })
+                        .catch((err) => {
+                        const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+                        this.logger?.error?.(`Failed to record LOGIN_BLOCKED audit event (fire-and-forget): ${errorMessage}`, {
+                            error: err,
+                            userId: user.id,
+                            userSub: user.sub,
+                        });
+                    });
+                }
+                else {
+                    try {
+                        await this.auditService?.recordEvent({
+                            userId: user.id,
+                            eventType: auth_audit_event_type_enum_1.AuthAuditEventType.LOGIN_BLOCKED,
+                            eventStatus: 'FAILURE',
+                            authMethod: 'password',
+                            reason: 'account_locked',
+                            description: `Login blocked - account locked: ${lockReason}`,
+                            metadata: {
+                                lockReason: user.lockReason,
+                                lockedAt: user.lockedAt,
+                                lockedUntil: user.lockedUntil,
+                                isPermanent: isPermanentlyLocked,
+                            },
+                        });
+                    }
+                    catch (auditError) {
+                        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                        this.logger?.error?.(`Failed to record LOGIN_BLOCKED audit event (account locked): ${errorMessage}`, {
+                            error: auditError,
+                            userId: user.id,
+                        });
+                    }
+                }
+                throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.ACCOUNT_LOCKED, lockReason, {
+                    lockReason: user.lockReason,
+                    lockedAt: user.lockedAt,
+                    lockedUntil: user.lockedUntil,
+                    isPermanent: isPermanentlyLocked,
+                });
+            }
+            else {
+                // Account was temporarily locked but lock has expired - unlock it
+                this.logger?.debug?.(`Account lock expired for user: ${user.email} (sub: ${user.sub}), unlocking account`);
+                user.isLocked = false;
+                user.lockReason = null;
+                user.lockedAt = null;
+                user.lockedUntil = null;
+                await this.userRepository.save(user);
+            }
+        }
+        // ============================================================================
         // Password Expiry Check
         // ============================================================================
         const expiryDays = this.config.password?.expiryDays;
@@ -1910,7 +2761,11 @@ class AuthService {
         switch (challengeSession.challengeName) {
             case auth_challenge_dto_1.AuthChallenge.VERIFY_EMAIL: {
                 // Resend email verification
-                const resendDto = Object.assign(new verify_email_dto_1.ResendVerificationEmailDTO(), { sub: user.sub });
+                // 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}`);
@@ -3220,6 +4075,11 @@ class AuthService {
             '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',