@nauth-toolkit/core 0.1.87 → 0.1.89

package/dist/services/mfa.service.js

@@ -8,6 +8,7 @@ const auth_challenge_dto_1 = require("../dto/auth-challenge.dto");
 const auth_audit_event_type_enum_1 = require("../enums/auth-audit-event-type.enum");
 const dto_validator_1 = require("../utils/dto-validator");
 const class_validator_1 = require("class-validator");
+const context_storage_1 = require("../utils/context-storage");
 const dto_1 = require("../dto");
 /**
  * MFA Service Registry
@@ -33,7 +34,7 @@ const dto_1 = require("../dto");
  *   @Post('mfa/verify')
  *   async verifyMFA(@Body() dto: { method: string; code: string }) {
  *     const provider = this.mfaService.getProvider(dto.method);
- *     return await provider.verify(user, dto.code);
+ *     return await provider.verify(dto.code);
  *   }
  * }
  * ```
@@ -48,6 +49,323 @@ class MFAService {
     clientInfoService;
     hookRegistry;
     providers = new Map();
+    // ============================================================================
+    // MFA Status (User + Admin)
+    // ============================================================================
+    /**
+     * Shared implementation for retrieving MFA status by target user sub.
+     *
+     * @param sub - Target user sub (UUID v4)
+     * @returns Comprehensive MFA status
+     */
+    async getMfaStatusBySub(sub) {
+        // Get user entity with MFA-related fields
+        // Note: mfaExemptGrantedBy is intentionally excluded as it's sensitive admin information
+        const userEntity = await this.userRepository.findOne({
+            select: [
+                'id',
+                'mfaEnabled',
+                'backupCodes',
+                'preferredMfaMethod',
+                'mfaExempt',
+                'mfaExemptReason',
+                'mfaExemptGrantedAt',
+            ],
+            where: { sub },
+        });
+        if (!userEntity) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
+        }
+        const enabled = userEntity.mfaEnabled || false;
+        // Get available methods (all registered & allowed methods)
+        const availableMethodsResult = await this.getAvailableMethods({ sub });
+        // Add 'backup' to available methods if backup codes are enabled in config
+        const finalAvailableMethods = [...availableMethodsResult.availableMethods];
+        if (this.config?.mfa?.backup?.enabled) {
+            if (!finalAvailableMethods.includes(mfa_method_enum_1.MFAMethod.BACKUP)) {
+                finalAvailableMethods.push(mfa_method_enum_1.MFAMethod.BACKUP);
+            }
+        }
+        // Get user's configured devices for the target user
+        const devicesResult = await this.mfaDeviceRepository.find({
+            where: { userId: userEntity.id, isActive: true },
+            order: { createdAt: 'DESC' },
+        });
+        const configuredMethods = [
+            ...new Set(devicesResult.filter((d) => d.isActive).map((d) => d.type)),
+        ];
+        // Determine if MFA is required based on config and user state
+        const required = enabled && configuredMethods.length > 0;
+        // Check backup codes
+        const hasBackupCodes = !!userEntity.backupCodes?.length;
+        return {
+            enabled,
+            required,
+            configuredMethods,
+            availableMethods: finalAvailableMethods,
+            hasBackupCodes,
+            preferredMethod: userEntity.preferredMfaMethod,
+            mfaExempt: userEntity.mfaExempt || false,
+            mfaExemptReason: (userEntity.mfaExemptReason ?? null),
+            mfaExemptGrantedAt: (userEntity.mfaExemptGrantedAt ??
+                null),
+        };
+    }
+    // ============================================================================
+    // Internal helpers (shared by user + admin APIs)
+    // ============================================================================
+    /**
+     * Fetch active MFA devices for a given internal user ID.
+     *
+     * @param userId - Internal DB user ID
+     * @returns Active MFA devices
+     */
+    async getActiveDevicesForUserId(userId) {
+        const devices = await this.mfaDeviceRepository.find({
+            where: { userId, isActive: true },
+            order: { createdAt: 'DESC' },
+        });
+        return devices;
+    }
+    /**
+     * Resolve a target user by `sub` (admin-style targeting).
+     *
+     * @param sub - Target user sub (UUID v4)
+     * @returns User entity
+     * @throws {NAuthException} NOT_FOUND when user is not found
+     */
+    async getUserBySubOrThrow(sub) {
+        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');
+        }
+        return user;
+    }
+    /**
+     * Shared implementation for removing MFA devices.
+     *
+     * @param targetUser - Target user (self-service or admin target)
+     * @param methodType - MFA method to remove (normalized)
+     * @param removedBy - Actor performing the removal
+     */
+    async removeDevicesInternal(targetUser, methodType, removedBy) {
+        const userId = targetUser.id;
+        const preferredMethod = targetUser.preferredMfaMethod;
+        const isPreferredMethod = preferredMethod === methodType;
+        // Get all active devices for this user
+        const activeDevices = await this.getActiveDevicesForUserId(userId);
+        // Get devices of the method type to remove
+        const devicesToRemove = activeDevices.filter((d) => d.type.toLowerCase() === methodType);
+        if (devicesToRemove.length === 0) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `No active ${methodType} MFA devices found for this user`);
+        }
+        // Delete all devices of this method type
+        let deletedCount = 0;
+        for (const device of devicesToRemove) {
+            const result = await this.mfaDeviceRepository.delete(device.id);
+            deletedCount += result.affected || 0;
+        }
+        // Check if any devices remain after removal
+        const remainingActiveDevices = await this.getActiveDevicesForUserId(userId);
+        let mfaDisabled = false;
+        // If no active devices remain, disable MFA for user
+        if (remainingActiveDevices.length === 0) {
+            await this.userRepository.update({ id: userId }, {
+                mfaEnabled: false,
+                mfaMethods: [],
+                preferredMfaMethod: null,
+            });
+            mfaDisabled = true;
+            // ============================================================================
+            // Audit: Record MFA disabled (all devices removed)
+            // ============================================================================
+            if (this.auditService && this.clientInfoService) {
+                try {
+                    await this.auditService?.recordEvent({
+                        userId,
+                        eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_DISABLED,
+                        eventStatus: 'INFO',
+                        reason: removedBy === 'admin' ? 'admin_action' : 'all_devices_removed',
+                        description: removedBy === 'admin'
+                            ? 'MFA disabled by admin - all devices removed'
+                            : 'MFA disabled - all devices removed',
+                        // Client info automatically included from context
+                        metadata: {
+                            removedMethod: methodType,
+                            deletedCount,
+                            removedBy,
+                        },
+                    });
+                }
+                catch (auditError) {
+                    const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                    this.logger?.error?.(`Failed to record MFA_DISABLED audit event: ${errorMessage}`, {
+                        error: auditError,
+                        userId,
+                    });
+                }
+            }
+            // Automatically create MFA_SETUP_REQUIRED challenge if MFA enforcement requires it
+            if (this.challengeService && this.config?.mfa?.enabled) {
+                const enforcement = this.config.mfa.enforcement || 'OPTIONAL';
+                if (enforcement === 'REQUIRED' || enforcement === 'ADAPTIVE') {
+                    try {
+                        await this.challengeService.createChallengeSession(targetUser, auth_challenge_dto_1.AuthChallenge.MFA_SETUP_REQUIRED, {
+                            allowedMethods: this.config.mfa.allowedMethods || [],
+                            requiresSetup: true,
+                        });
+                        this.logger?.log?.(`Created MFA_SETUP_REQUIRED challenge for user ${targetUser.sub} after MFA removal`);
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                        this.logger?.warn?.(`Failed to create MFA_SETUP_REQUIRED challenge after MFA removal: ${errorMessage}`);
+                    }
+                }
+            }
+        }
+        else {
+            // Update mfaMethods array with remaining methods
+            const remainingMethods = [...new Set(remainingActiveDevices.map((d) => d.type))];
+            // If the removed method was preferred, update preferred method and device primary flags
+            if (isPreferredMethod) {
+                const newPreferredMethod = remainingActiveDevices[0].type;
+                await this.userRepository.update({ id: userId }, {
+                    mfaMethods: remainingMethods,
+                    preferredMfaMethod: newPreferredMethod,
+                });
+                // Update device primary flags - set first remaining device as primary
+                if (remainingActiveDevices[0].id) {
+                    await this.mfaDeviceRepository.update({ id: remainingActiveDevices[0].id }, { isPrimary: true });
+                }
+                // Unset primary flag on other devices
+                for (let i = 1; i < remainingActiveDevices.length; i++) {
+                    if (remainingActiveDevices[i].id) {
+                        await this.mfaDeviceRepository.update({ id: remainingActiveDevices[i].id }, { isPrimary: false });
+                    }
+                }
+                this.logger?.log?.(`Updated preferred MFA method to ${newPreferredMethod} after removing ${methodType}`);
+            }
+            else {
+                // No preferred method change needed, just update mfaMethods
+                await this.userRepository.update({ id: userId }, {
+                    mfaMethods: remainingMethods,
+                });
+            }
+        }
+        // ============================================================================
+        // Audit: Record MFA device removal
+        // ============================================================================
+        if (deletedCount > 0 && this.auditService && this.clientInfoService) {
+            try {
+                await this.auditService?.recordEvent({
+                    userId,
+                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_DEVICE_REMOVED,
+                    eventStatus: 'INFO',
+                    metadata: {
+                        method: methodType,
+                        deletedCount,
+                        remainingDevices: remainingActiveDevices.length,
+                        mfaDisabled,
+                        removedBy,
+                    },
+                    // Client info automatically included from context
+                });
+            }
+            catch (auditError) {
+                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                this.logger?.error?.(`Failed to record MFA_DEVICE_REMOVED audit event: ${errorMessage}`, {
+                    error: auditError,
+                    userId,
+                    method: methodType,
+                });
+            }
+        }
+        // ============================================================================
+        // Lifecycle Hook: MFA Device Removed
+        // ============================================================================
+        if (deletedCount > 0 && this.hookRegistry && this.clientInfoService) {
+            try {
+                const clientInfo = this.clientInfoService.get();
+                await this.hookRegistry.executeMFADeviceRemoved({
+                    user: targetUser,
+                    deviceType: methodType,
+                    removedBy,
+                    remainingDeviceCount: remainingActiveDevices.length,
+                    clientInfo: {
+                        ipAddress: clientInfo.ipAddress,
+                        userAgent: clientInfo.userAgent,
+                        ipCountry: clientInfo.ipCountry,
+                        ipCity: clientInfo.ipCity,
+                    },
+                });
+            }
+            catch (hookError) {
+                const errorMessage = hookError instanceof Error ? hookError.message : 'Unknown error';
+                this.logger?.error?.(`Failed to execute mfaDeviceRemoved hooks: ${errorMessage}`, {
+                    error: hookError,
+                    userId,
+                    method: methodType,
+                });
+            }
+        }
+        return { deletedCount, mfaDisabled };
+    }
+    /**
+     * Shared implementation for setting preferred MFA method.
+     *
+     * @param targetUser - Target user (self-service or admin target)
+     * @param methodType - Preferred method (normalized)
+     * @param updatedBy - Actor performing the update
+     */
+    async setPreferredMethodInternal(targetUser, methodType, updatedBy) {
+        // Verify user has this method configured
+        const activeDevices = await this.getActiveDevicesForUserId(targetUser.id);
+        const preferredDevice = activeDevices.find((d) => d.type.toLowerCase() === methodType && d.isActive);
+        if (!preferredDevice) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `MFA method '${methodType}' is not configured for this user`);
+        }
+        // Update user's preferred method
+        await this.userRepository.update({ id: targetUser.id }, {
+            preferredMfaMethod: methodType,
+        });
+        // Update device isPrimary flags: set preferred device as primary, unset others
+        for (const device of activeDevices) {
+            await this.mfaDeviceRepository.update({ id: device.id }, { isPrimary: device.id === preferredDevice.id });
+        }
+        this.logger?.log?.(`Device ${preferredDevice.id} set as primary for user ${targetUser.sub} (by ${updatedBy})`);
+        // ============================================================================
+        // Audit: Record preferred MFA method update
+        // ============================================================================
+        if (this.auditService && this.clientInfoService) {
+            try {
+                const previousMethod = targetUser.preferredMfaMethod;
+                await this.auditService?.recordEvent({
+                    userId: targetUser.id,
+                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_PREFERRED_METHOD_UPDATED,
+                    eventStatus: 'INFO',
+                    metadata: {
+                        previousMethod: previousMethod || null,
+                        newMethod: methodType,
+                        deviceId: preferredDevice.id,
+                        updatedBy,
+                    },
+                });
+            }
+            catch (auditError) {
+                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+                this.logger?.error?.(`Failed to record MFA_PREFERRED_METHOD_UPDATED audit event: ${errorMessage}`, {
+                    error: auditError,
+                    userId: targetUser.id,
+                    method: methodType,
+                });
+            }
+        }
+        return {
+            message: 'Preferred method updated',
+        };
+    }
     /**
      * Resolve a user entity by flexible identifier.
      *
@@ -98,6 +416,51 @@ class MFAService {
         this.clientInfoService = clientInfoService;
         this.hookRegistry = hookRegistry;
     }
+    /**
+     * Get current user from authenticated context
+     *
+     * @returns Current authenticated user
+     * @throws {NAuthException} If user not found in context
+     */
+    getCurrentUserOrThrow() {
+        const currentUser = context_storage_1.ContextStorage.get('CURRENT_USER');
+        if (!currentUser) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.FORBIDDEN, 'Authentication required');
+        }
+        return currentUser;
+    }
+    /**
+     * Execute a callback with a specific user bound into CURRENT_USER context.
+     *
+     * This is required for flows where the user is resolved outside of request auth context
+     * (e.g., challenge sessions) but providers must still derive the user from context.
+     *
+     * @param user - User to bind into context
+     * @param callback - Callback to execute
+     * @returns Callback result
+     */
+    async withUserContext(user, callback) {
+        const store = context_storage_1.ContextStorage.getStore();
+        if (!store) {
+            return await context_storage_1.ContextStorage.run(async () => {
+                context_storage_1.ContextStorage.set('CURRENT_USER', user);
+                return await callback();
+            });
+        }
+        const previousUser = context_storage_1.ContextStorage.get('CURRENT_USER');
+        context_storage_1.ContextStorage.set('CURRENT_USER', user);
+        try {
+            return await callback();
+        }
+        finally {
+            if (previousUser) {
+                context_storage_1.ContextStorage.set('CURRENT_USER', previousUser);
+            }
+            else {
+                context_storage_1.ContextStorage.delete('CURRENT_USER');
+            }
+        }
+    }
     /**
      * Register an MFA provider
      *
@@ -260,9 +623,11 @@ class MFAService {
             }
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Backup code verification not available');
         }
-        // Get provider and verify
+        // Get provider and verify (provider derives user from context)
         const provider = this.getProvider(dto.methodName);
-        const isValid = await provider.verify(user, dto.code, dto.deviceId);
+        const isValid = await this.withUserContext(user, async () => {
+            return await provider.verify(dto.code, dto.deviceId);
+        });
         return { valid: isValid };
     }
     /**
@@ -282,14 +647,9 @@ class MFAService {
      */
     async setup(dto) {
         dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.SetupMFADTO, dto);
-        // Look up user by sub
-        const userEntity = await this.userRepository.findOne({ where: { sub: dto.sub } });
-        if (!userEntity) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
-        }
-        const user = userEntity;
+        // Get user from authenticated context (already has all fields)
         const provider = this.getProvider(dto.methodName);
-        const setupData = await provider.setup(user, dto.setupData);
+        const setupData = await provider.setup(dto.setupData);
         return {
             setupData: setupData,
         };
@@ -297,110 +657,49 @@ class MFAService {
     /**
      * Get user's MFA devices
      *
-     * @param dto - Request DTO with user sub
+     * User self-service method: current user is derived from authenticated context.
+     *
+     * @param _dto - Optional (empty) DTO for validation consistency
      * @returns Response DTO with array of MFA devices
      *
      * @example
      * ```typescript
-     * const result = await this.mfaService.getUserDevices({ sub: user.sub });
+     * const result = await this.mfaService.getUserDevices();
      * // Returns: { devices: [...] }
      * ```
      */
-    async getUserDevices(dto) {
-        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.GetUserDevicesDTO, dto);
-        // Look up user by sub to get internal ID
-        const userEntity = await this.userRepository.findOne({ where: { sub: dto.sub } });
-        if (!userEntity) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
-        }
-        // Only fetch active devices (inactive devices are soft-deleted)
-        const devices = await this.mfaDeviceRepository.find({
-            where: { userId: userEntity.id, isActive: true },
-            order: { createdAt: 'DESC' },
-        });
+    async getUserDevices(_dto = {}) {
+        await (0, dto_validator_1.ensureValidatedDto)(dto_1.GetUserDevicesDTO, _dto);
+        // Get user from authenticated context (already has id and sub)
+        const currentUser = this.getCurrentUserOrThrow();
         return {
-            devices: devices,
+            devices: await this.getActiveDevicesForUserId(currentUser.id),
         };
     }
     /**
-     * Get comprehensive MFA status for a user
+     * Get comprehensive MFA status for the current authenticated user (self-service).
      *
-     * Returns complete MFA configuration status including:
-     * - Whether MFA is enabled/required
-     * - Configured and available methods
-     * - Preferred method
-     * - Backup codes status
-     * - MFA exemption information
-     *
-     * This method encapsulates all business logic for MFA status,
-     * ensuring consumer apps don't need to query databases or build responses manually.
-     *
-     * @param dto - Request DTO with user sub
      * @returns Response DTO with complete MFA status
+     */
+    async getMfaStatus() {
+        const currentUser = this.getCurrentUserOrThrow();
+        return await this.getMfaStatusBySub(currentUser.sub);
+    }
+    /**
+     * Get comprehensive MFA status for a target user (admin-only).
      *
-     * @example
-     * ```typescript
-     * @Get('mfa/status')
-     * async getMFAStatus(@CurrentUser() user: IUser) {
-     *   return await this.mfaService.getMFAStatus({ sub: user.sub });
-     * }
-     * ```
+     * @param dto - Admin request DTO with target user sub
+     * @returns Response DTO with complete MFA status
      */
-    async getMFAStatus(dto) {
-        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.GetMFAStatusDTO, dto);
-        // Get user entity with MFA-related fields
-        // Note: mfaExemptGrantedBy is intentionally excluded as it's sensitive admin information
-        const userEntity = await this.userRepository.findOne({
-            select: [
-                'id',
-                'mfaEnabled',
-                'backupCodes',
-                'preferredMfaMethod',
-                'mfaExempt',
-                'mfaExemptReason',
-                'mfaExemptGrantedAt',
-            ],
-            where: { sub: dto.sub },
-        });
-        if (!userEntity) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
-        }
-        const enabled = userEntity.mfaEnabled || false;
-        // Get available methods (all registered & allowed methods)
-        const availableMethodsResult = await this.getAvailableMethods({ sub: dto.sub });
-        // Add 'backup' to available methods if backup codes are enabled in config
-        const finalAvailableMethods = [...availableMethodsResult.availableMethods];
-        if (this.config?.mfa?.backup?.enabled) {
-            if (!finalAvailableMethods.includes(mfa_method_enum_1.MFAMethod.BACKUP)) {
-                finalAvailableMethods.push(mfa_method_enum_1.MFAMethod.BACKUP);
-            }
-        }
-        // Get user's configured devices
-        const devicesResult = await this.getUserDevices({ sub: dto.sub });
-        const configuredMethods = [
-            ...new Set(devicesResult.devices.filter((d) => d.isActive).map((d) => d.type)),
-        ];
-        // Determine if MFA is required based on config and user state
-        const required = enabled && configuredMethods.length > 0;
-        // Check backup codes
-        const hasBackupCodes = !!userEntity.backupCodes && userEntity.backupCodes.length > 0;
-        return {
-            enabled,
-            required,
-            configuredMethods,
-            availableMethods: finalAvailableMethods,
-            hasBackupCodes,
-            preferredMethod: userEntity.preferredMfaMethod,
-            mfaExempt: userEntity.mfaExempt || false,
-            mfaExemptReason: userEntity.mfaExemptReason || null,
-            mfaExemptGrantedAt: userEntity.mfaExemptGrantedAt || null,
-        };
+    async adminGetMfaStatus(dto) {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.AdminGetMFAStatusDTO, dto);
+        return await this.getMfaStatusBySub(dto.sub);
     }
     /**
      * Remove MFA devices by method type
      *
      * Comprehensive method that handles all aspects of MFA device removal:
-     * - Looks up user by sub (consumer apps should pass user.sub from @CurrentUser())
+     * - Uses the authenticated user context (self-service)
      * - Validates method type
      * - Removes all active devices of the specified method type
      * - Updates user's preferred method if the removed method was preferred
@@ -411,7 +710,7 @@ class MFAService {
      * This method encapsulates all database operations related to MFA device removal,
      * ensuring the consumer app doesn't need to directly manipulate nauth_* tables.
      *
-     * @param dto - Request DTO with user sub and method type
+     * @param dto - Request DTO with method type
      * @returns Response DTO with deletedCount and whether MFA was disabled
      * @throws {NAuthException} If user not found, invalid method type, or no devices found
      *
@@ -420,189 +719,43 @@ class MFAService {
      * // Consumer app controller
      * @Delete('mfa/devices/:method')
      * async removeMFAMethod(@CurrentUser() user: IUser, @Param('method') method: string) {
-     *   const result = await this.mfaService.removeDevices({ userSub: user.sub, methodType: method });
+     *   const result = await this.mfaService.removeDevices({ methodType: method });
      *   return { message: 'MFA method removed successfully', ...result };
      * }
      * ```
      */
     async removeDevices(dto) {
         dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.RemoveDevicesDTO, dto);
-        // Validate method type
         const validMethods = [mfa_method_enum_1.MFAMethod.TOTP, mfa_method_enum_1.MFAMethod.SMS, mfa_method_enum_1.MFAMethod.EMAIL, mfa_method_enum_1.MFAMethod.PASSKEY];
         const normalizedMethod = dto.methodType.toLowerCase();
         if (!validMethods.includes(normalizedMethod)) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Invalid MFA method: ${dto.methodType}. Valid methods are: ${validMethods.join(', ')}`);
         }
-        // Look up user by sub using repository directly (no AuthService dependency needed)
-        const userEntity = await this.userRepository.findOne({ where: { sub: dto.userSub } });
-        if (!userEntity) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User entity not found');
-        }
-        const userId = userEntity.id;
-        if (!userId) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'User entity missing internal ID');
-        }
-        // Cast to IUser for type safety
-        const user = userEntity;
-        const preferredMethod = userEntity.preferredMfaMethod;
-        const isPreferredMethod = preferredMethod === normalizedMethod;
-        // Get all active devices for this user
-        const devicesResult = await this.getUserDevices({ sub: dto.userSub });
-        const activeDevices = devicesResult.devices.filter((d) => d.isActive);
-        // Get devices of the method type to remove
-        const devicesToRemove = activeDevices.filter((d) => d.type.toLowerCase() === normalizedMethod);
-        if (devicesToRemove.length === 0) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `No active ${normalizedMethod} MFA devices found for this user`);
-        }
-        // Delete all devices of this method type
-        let deletedCount = 0;
-        for (const device of devicesToRemove) {
-            const result = await this.mfaDeviceRepository.delete(device.id);
-            deletedCount += result.affected || 0;
-        }
-        // Check if any devices remain after removal
-        const remainingDevicesResult = await this.getUserDevices({ sub: dto.userSub });
-        const remainingActiveDevices = remainingDevicesResult.devices.filter((d) => d.isActive);
-        let mfaDisabled = false;
-        // If no active devices remain, disable MFA for user
-        if (remainingActiveDevices.length === 0) {
-            userEntity.mfaEnabled = false;
-            userEntity.mfaMethods = [];
-            userEntity.preferredMfaMethod = null;
-            await this.userRepository.save(userEntity);
-            mfaDisabled = true;
-            // ============================================================================
-            // Audit: Record MFA disabled (all devices removed)
-            // ============================================================================
-            if (this.auditService && this.clientInfoService) {
-                try {
-                    await this.auditService?.recordEvent({
-                        userId: user.id,
-                        eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_DISABLED,
-                        eventStatus: 'INFO',
-                        reason: 'all_devices_removed',
-                        description: 'MFA disabled - all devices removed',
-                        // Client info automatically included from context
-                        metadata: {
-                            removedMethod: normalizedMethod,
-                            deletedCount,
-                        },
-                    });
-                }
-                catch (auditError) {
-                    // Non-blocking: Log but continue
-                    const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                    this.logger?.error?.(`Failed to record MFA_DISABLED audit event: ${errorMessage}`, {
-                        error: auditError,
-                        userId: user.id,
-                    });
-                }
-            }
-            // Automatically create MFA_SETUP_REQUIRED challenge if MFA enforcement requires it
-            if (this.challengeService && this.config?.mfa?.enabled) {
-                const enforcement = this.config.mfa.enforcement || 'OPTIONAL';
-                if (enforcement === 'REQUIRED' || enforcement === 'ADAPTIVE') {
-                    const user = userEntity;
-                    try {
-                        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-                        await this.challengeService.createChallengeSession(user, auth_challenge_dto_1.AuthChallenge.MFA_SETUP_REQUIRED, {
-                            allowedMethods: this.config.mfa.allowedMethods || [],
-                            requiresSetup: true,
-                        });
-                        this.logger?.log?.(`Created MFA_SETUP_REQUIRED challenge for user ${user.sub} after MFA removal`);
-                    }
-                    catch (error) {
-                        // Log but don't fail the removal if challenge creation fails
-                        this.logger?.warn?.(`Failed to create MFA_SETUP_REQUIRED challenge after MFA removal: ${error}`);
-                    }
-                }
-            }
-        }
-        else {
-            // Update mfaMethods array with remaining methods
-            const remainingMethods = [...new Set(remainingActiveDevices.map((d) => d.type))];
-            userEntity.mfaMethods = remainingMethods;
-            // If the removed method was preferred, update preferred method and device primary flags
-            if (isPreferredMethod) {
-                const newPreferredMethod = remainingActiveDevices[0].type;
-                userEntity.preferredMfaMethod = newPreferredMethod;
-                await this.userRepository.save(userEntity);
-                // Update device primary flags - set first remaining device as primary
-                if (remainingActiveDevices[0].id) {
-                    await this.mfaDeviceRepository.update({ id: remainingActiveDevices[0].id }, { isPrimary: true });
-                }
-                // Unset primary flag on other devices
-                for (let i = 1; i < remainingActiveDevices.length; i++) {
-                    if (remainingActiveDevices[i].id) {
-                        await this.mfaDeviceRepository.update({ id: remainingActiveDevices[i].id }, { isPrimary: false });
-                    }
-                }
-                this.logger?.log?.(`Updated preferred MFA method to ${newPreferredMethod} after removing ${normalizedMethod}`);
-            }
-            else {
-                // No preferred method change needed, just update mfaMethods
-                await this.userRepository.save(userEntity);
-            }
-        }
-        // ============================================================================
-        // Audit: Record MFA device removal
-        // ============================================================================
-        if (deletedCount > 0 && this.auditService && this.clientInfoService) {
-            try {
-                const user = userEntity;
-                await this.auditService?.recordEvent({
-                    userId: user.id,
-                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_DEVICE_REMOVED,
-                    eventStatus: 'INFO',
-                    metadata: {
-                        method: normalizedMethod,
-                        deletedCount,
-                        remainingDevices: remainingActiveDevices.length,
-                        mfaDisabled,
-                    },
-                    // Client info automatically included from context
-                });
-            }
-            catch (auditError) {
-                // Non-blocking: Log but continue
-                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                this.logger?.error?.(`Failed to record MFA_DEVICE_REMOVED audit event: ${errorMessage}`, {
-                    error: auditError,
-                    userId: user.id,
-                    method: normalizedMethod,
-                });
-            }
-        }
-        // ============================================================================
-        // Lifecycle Hook: MFA Device Removed
-        // ============================================================================
-        if (deletedCount > 0 && this.hookRegistry && this.clientInfoService) {
-            try {
-                const clientInfo = this.clientInfoService.get();
-                await this.hookRegistry.executeMFADeviceRemoved({
-                    user,
-                    deviceType: normalizedMethod,
-                    removedBy: 'user',
-                    remainingDeviceCount: remainingActiveDevices.length,
-                    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 mfaDeviceRemoved hooks: ${errorMessage}`, {
-                    error: hookError,
-                    userId: user.id,
-                    method: normalizedMethod,
-                });
-            }
+        const currentUser = this.getCurrentUserOrThrow();
+        return await this.removeDevicesInternal(currentUser, normalizedMethod, 'user');
+    }
+    /**
+     * Admin: Remove MFA devices for a specific user by `sub`.
+     *
+     * @param dto - Admin DTO containing target `sub` and method type
+     * @returns Removal result
+     * @throws {NAuthException} NOT_FOUND when user is not found
+     * @throws {NAuthException} VALIDATION_FAILED on invalid method type
+     *
+     * @example
+     * ```typescript
+     * await mfaService.adminRemoveDevices({ sub: 'user-uuid', methodType: 'totp' });
+     * ```
+     */
+    async adminRemoveDevices(dto) {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.AdminRemoveDevicesDTO, dto);
+        const validMethods = [mfa_method_enum_1.MFAMethod.TOTP, mfa_method_enum_1.MFAMethod.SMS, mfa_method_enum_1.MFAMethod.EMAIL, mfa_method_enum_1.MFAMethod.PASSKEY];
+        const normalizedMethod = dto.methodType.toLowerCase();
+        if (!validMethods.includes(normalizedMethod)) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Invalid MFA method: ${dto.methodType}. Valid methods are: ${validMethods.join(', ')}`);
         }
-        return { deletedCount, mfaDisabled };
+        const targetUser = await this.getUserBySubOrThrow(dto.sub);
+        return await this.removeDevicesInternal(targetUser, normalizedMethod, 'admin');
     }
     /**
      * Set preferred MFA method for a user
@@ -613,7 +766,7 @@ class MFAService {
      * This method encapsulates all database operations related to preferred method updates,
      * ensuring the consumer app doesn't need to directly manipulate nauth_* tables.
      *
-     * @param dto - Request DTO with user sub and method type
+     * @param dto - Request DTO with method type
      * @returns Response DTO with success message
      * @throws {NAuthException} If user not found, invalid method type, or method not configured
      *
@@ -622,7 +775,7 @@ class MFAService {
      * // Consumer app controller
      * @Put('mfa/preferred')
      * async setPreferredMFAMethod(@CurrentUser() user: IUser, @Body() body: { method: string }) {
-     *   return await this.mfaService.setPreferredMethod({ userSub: user.sub, methodType: body.method });
+     *   return await this.mfaService.setPreferredMethod({ methodType: body.method });
      * }
      * ```
      */
@@ -634,65 +787,31 @@ class MFAService {
         if (!validMethods.includes(normalizedMethod)) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Invalid MFA method: ${dto.methodType}. Valid methods are: ${validMethods.join(', ')}`);
         }
-        // Look up user by sub using repository directly (no AuthService dependency needed)
-        const userEntity = await this.userRepository.findOne({ where: { sub: dto.userSub } });
-        if (!userEntity) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
-        }
-        const userId = userEntity.id;
-        if (!userId) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'User entity missing internal ID');
-        }
-        // Cast to IUser for type safety
-        const user = userEntity;
-        // Verify user has this method configured
-        const devicesResult = await this.getUserDevices({ sub: dto.userSub });
-        // Normalize device types for comparison (database might store in different case)
-        const preferredDevice = devicesResult.devices.find((d) => d.type.toLowerCase() === normalizedMethod && d.isActive);
-        if (!preferredDevice) {
-            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `MFA method '${normalizedMethod}' is not configured for this user`);
-        }
-        // Update user's preferred method directly via repository
-        await this.userRepository.update({ id: userId }, {
-            preferredMfaMethod: normalizedMethod,
-        });
-        // Update device isPrimary flags: set preferred device as primary, unset others
-        const activeDevices = devicesResult.devices.filter((d) => d.isActive);
-        for (const device of activeDevices) {
-            await this.mfaDeviceRepository.update({ id: device.id }, { isPrimary: device.id === preferredDevice.id });
-        }
-        this.logger?.log?.(`Device ${preferredDevice.id} set as primary for user ${dto.userSub}`);
-        // ============================================================================
-        // Audit: Record preferred MFA method update
-        // ============================================================================
-        if (this.auditService && this.clientInfoService) {
-            try {
-                const previousMethod = userEntity.preferredMfaMethod;
-                await this.auditService?.recordEvent({
-                    userId: user.id,
-                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_PREFERRED_METHOD_UPDATED,
-                    eventStatus: 'INFO',
-                    metadata: {
-                        // Client info automatically included from context
-                        previousMethod: previousMethod || null,
-                        newMethod: normalizedMethod,
-                        deviceId: preferredDevice.id,
-                    },
-                });
-            }
-            catch (auditError) {
-                // Non-blocking: Log but continue
-                const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-                this.logger?.error?.(`Failed to record MFA_PREFERRED_METHOD_UPDATED audit event: ${errorMessage}`, {
-                    error: auditError,
-                    userId: user.id,
-                    method: normalizedMethod,
-                });
-            }
+        const currentUser = this.getCurrentUserOrThrow();
+        return await this.setPreferredMethodInternal(currentUser, normalizedMethod, 'user');
+    }
+    /**
+     * Admin: Set preferred MFA method for a specific user by `sub`.
+     *
+     * @param dto - Admin DTO containing target `sub` and method type
+     * @returns Success response
+     * @throws {NAuthException} NOT_FOUND when user is not found
+     * @throws {NAuthException} VALIDATION_FAILED when method is invalid or not configured
+     *
+     * @example
+     * ```typescript
+     * await mfaService.adminSetPreferredMethod({ sub: 'user-uuid', methodType: 'sms' });
+     * ```
+     */
+    async adminSetPreferredMethod(dto) {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.AdminSetPreferredMethodDTO, dto);
+        const validMethods = [mfa_method_enum_1.MFAMethod.TOTP, mfa_method_enum_1.MFAMethod.SMS, mfa_method_enum_1.MFAMethod.EMAIL, mfa_method_enum_1.MFAMethod.PASSKEY];
+        const normalizedMethod = dto.methodType.toLowerCase();
+        if (!validMethods.includes(normalizedMethod)) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Invalid MFA method: ${dto.methodType}. Valid methods are: ${validMethods.join(', ')}`);
         }
-        return {
-            message: 'Preferred method updated',
-        };
+        const targetUser = await this.getUserBySubOrThrow(dto.sub);
+        return await this.setPreferredMethodInternal(targetUser, normalizedMethod, 'admin');
     }
     /**
      * Grant or revoke a user's exemption from multi-factor authentication (MFA) requirements.
@@ -700,7 +819,7 @@ class MFAService {
      * SECURITY: This admin-only operation updates the user's MFA exemption status, logs the action,
      * and records an audit event. MFA exemption bypasses MFA at login, but all other security controls remain enforced.
      *
-     * @param dto - Request DTO with identifier, exempt flag, reason, and grantedBy
+     * @param dto - Request DTO with sub, exempt flag, reason, and grantedBy
      * @returns Response DTO with updated exemption fields
      * @throws {NAuthException} If the user is not found
      *
@@ -708,7 +827,7 @@ class MFAService {
      * ```typescript
      * // Grant MFA exemption
      * await mfaService.setMFAExemption({
-     *   identifier: 'user@example.com',
+     *   sub: 'a21b654c-2746-4168-acee-c175083a65cd',
      *   exempt: true,
      *   reason: 'Business partner requires MFA bypass',
      *   grantedBy: 'admin@example.com'
@@ -716,7 +835,7 @@ class MFAService {
      *
      * // Revoke MFA exemption
      * await mfaService.setMFAExemption({
-     *   identifier: 'user@example.com',
+     *   sub: 'a21b654c-2746-4168-acee-c175083a65cd',
      *   exempt: false,
      *   reason: 'MFA now mandatory for this user',
      *   grantedBy: 'admin@example.com'
@@ -728,8 +847,8 @@ class MFAService {
         // ============================================================================
         // SECURITY: Resolve the TARGET user from the DTO (admin-only API)
         // ============================================================================
-        // Use `identifier` (email/username/phone/sub).
-        const userEntity = await this.findUserByIdentifier(dto.identifier);
+        // Use `sub` (UUID v4) per ADMIN_USER_API_SEPARATION_PLAN.md
+        const userEntity = await this.userRepository.findOne({ where: { sub: dto.sub } });
         if (!userEntity) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
         }
@@ -850,7 +969,9 @@ class MFAService {
         };
         this.logger?.debug?.(`Passing challengeSessionId=${challengeSession.id} to ${dto.method} provider for MFA setup`);
         const provider = this.getProvider(dto.method);
-        const result = await provider.setup(user, setupDataWithSession);
+        const result = await this.withUserContext(user, async () => {
+            return await provider.setup(setupDataWithSession);
+        });
         this.logger?.debug?.(`MFA setup data generated: method=${dto.method}, user=${user.sub}`);
         return {
             setupData: result,
@@ -916,7 +1037,9 @@ class MFAService {
         if (!provider.sendChallenge) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `MFA method '${dto.method}' does not support challenge data generation`);
         }
-        const challengeData = await provider.sendChallenge(user);
+        const challengeData = await this.withUserContext(user, async () => {
+            return await provider.sendChallenge?.();
+        });
         // For passkey, store the challenge in session metadata for verification
         if (dto.method === 'passkey') {
             const passkeyOptions = challengeData;