@nauth-toolkit/core 0.1.108 → 0.1.109

package/dist/services/mfa.service.js

@@ -150,24 +150,28 @@ class MFAService {
      * @param methodType - MFA method to remove (normalized)
      * @param removedBy - Actor performing the removal
      */
-    async removeDevicesInternal(targetUser, methodType, removedBy) {
+    /**
+     * Shared implementation for removing a single MFA device by device ID.
+     *
+     * @param targetUser - Target user (self-service or admin target)
+     * @param deviceId - MFA device ID to remove
+     * @param removedBy - Actor performing the removal
+     * @returns Removal result
+     * @throws {NAuthException} NOT_FOUND when device is not found for the user
+     */
+    async removeDeviceInternal(targetUser, deviceId, removedBy) {
         const userId = targetUser.id;
-        const preferredMethod = targetUser.preferredMfaMethod;
-        const isPreferredMethod = preferredMethod === methodType;
-        // Get all active devices for this user
+        // Get all active devices for this user and find the target device
         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;
+        const deviceToRemove = activeDevices.find((d) => d.id === deviceId);
+        if (!deviceToRemove) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'MFA device not found', { deviceId });
         }
-        // Check if any devices remain after removal
+        const removedMethod = deviceToRemove.type;
+        // Delete the specific device
+        const result = await this.mfaDeviceRepository.delete(deviceId);
+        const deletedCount = result.affected || 0;
+        // Re-load remaining devices after deletion
         const remainingActiveDevices = await this.getActiveDevicesForUserId(userId);
         let mfaDisabled = false;
         // If no active devices remain, disable MFA for user
@@ -179,23 +183,30 @@ class MFAService {
             });
             mfaDisabled = true;
             // ============================================================================
-            // Audit: Record MFA disabled (all devices removed)
+            // Audit: Record MFA disabled (last device removed)
             // ============================================================================
             if (this.auditService && this.clientInfoService) {
                 try {
+                    const actor = removedBy === 'admin' ? context_storage_1.ContextStorage.get('CURRENT_USER') : null;
+                    const actorNameCandidate = actor
+                        ? `${actor.firstName || ''} ${actor.lastName || ''}`.trim()
+                        : '';
+                    const performedByName = actorNameCandidate.length > 0 ? actorNameCandidate : actor?.email || undefined;
                     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',
+                        authMethod: removedBy === 'admin' ? 'admin' : undefined,
+                        performedBy: removedBy === 'admin' && actor ? actor.sub : undefined,
+                        reason: removedBy === 'admin' ? 'admin_action' : 'last_device_removed',
                         description: removedBy === 'admin'
-                            ? 'MFA disabled by admin - all devices removed'
-                            : 'MFA disabled - all devices removed',
-                        // Client info automatically included from context
+                            ? 'MFA disabled by admin - last device removed'
+                            : 'MFA disabled - last device removed',
                         metadata: {
-                            removedMethod: methodType,
-                            deletedCount,
+                            removedDeviceId: deviceId,
+                            removedMethod,
                             removedBy,
+                            ...(performedByName ? { performedByName } : {}),
                         },
                     });
                 }
@@ -216,11 +227,11 @@ class MFAService {
                             allowedMethods: this.config.mfa.allowedMethods || [],
                             requiresSetup: true,
                         });
-                        this.logger?.log?.(`Created MFA_SETUP_REQUIRED challenge for user ${targetUser.sub} after MFA removal`);
+                        this.logger?.log?.(`Created MFA_SETUP_REQUIRED challenge for user ${targetUser.sub} after device 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}`);
+                        this.logger?.warn?.(`Failed to create MFA_SETUP_REQUIRED challenge after device removal: ${errorMessage}`);
                     }
                 }
             }
@@ -228,30 +239,19 @@ class MFAService {
         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,
-                });
+            // Determine preferred method: keep if still configured, otherwise pick a new one.
+            const preferredMethod = targetUser.preferredMfaMethod;
+            const preferredStillConfigured = !!preferredMethod && remainingActiveDevices.some((d) => d.type === preferredMethod);
+            const finalPreferredMethod = preferredStillConfigured ? preferredMethod : remainingActiveDevices[0].type;
+            await this.userRepository.update({ id: userId }, {
+                mfaMethods: remainingMethods,
+                preferredMfaMethod: finalPreferredMethod,
+            });
+            // Normalize primary device flags: ensure exactly one active device is primary.
+            // Prefer a device of the preferred method (best UX).
+            const primaryDevice = remainingActiveDevices.find((d) => d.type === finalPreferredMethod) || remainingActiveDevices[0];
+            for (const device of remainingActiveDevices) {
+                await this.mfaDeviceRepository.update({ id: device.id }, { isPrimary: device.id === primaryDevice.id });
             }
         }
         // ============================================================================
@@ -259,18 +259,26 @@ class MFAService {
         // ============================================================================
         if (deletedCount > 0 && this.auditService && this.clientInfoService) {
             try {
+                const actor = removedBy === 'admin' ? context_storage_1.ContextStorage.get('CURRENT_USER') : null;
+                const actorNameCandidate = actor
+                    ? `${actor.firstName || ''} ${actor.lastName || ''}`.trim()
+                    : '';
+                const performedByName = actorNameCandidate.length > 0 ? actorNameCandidate : actor?.email || undefined;
                 await this.auditService?.recordEvent({
                     userId,
                     eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_DEVICE_REMOVED,
                     eventStatus: 'INFO',
+                    authMethod: removedBy === 'admin' ? 'admin' : undefined,
+                    performedBy: removedBy === 'admin' && actor ? actor.sub : undefined,
                     metadata: {
-                        method: methodType,
+                        removedDeviceId: deviceId,
+                        removedMethod,
                         deletedCount,
                         remainingDevices: remainingActiveDevices.length,
                         mfaDisabled,
                         removedBy,
+                        ...(performedByName ? { performedByName } : {}),
                     },
-                    // Client info automatically included from context
                 });
             }
             catch (auditError) {
@@ -278,7 +286,7 @@ class MFAService {
                 this.logger?.error?.(`Failed to record MFA_DEVICE_REMOVED audit event: ${errorMessage}`, {
                     error: auditError,
                     userId,
-                    method: methodType,
+                    removedDeviceId: deviceId,
                 });
             }
         }
@@ -290,7 +298,7 @@ class MFAService {
                 const clientInfo = this.clientInfoService.get();
                 await this.hookRegistry.executeMFADeviceRemoved({
                     user: targetUser,
-                    deviceType: methodType,
+                    deviceType: removedMethod,
                     removedBy,
                     remainingDeviceCount: remainingActiveDevices.length,
                     clientInfo: {
@@ -306,64 +314,14 @@ class MFAService {
                 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,
+                    removedDeviceId: deviceId,
                 });
             }
         }
         return {
-            message: 'Preferred method updated',
+            removedDeviceId: deviceId,
+            removedMethod,
+            mfaDisabled,
         };
     }
     /**
@@ -724,94 +682,179 @@ class MFAService {
      * }
      * ```
      */
-    async removeDevices(dto) {
-        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.RemoveDevicesDTO, 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(', ')}`);
-        }
+    /**
+     * Remove a single MFA device by device ID (self-service).
+     *
+     * WHY: Users can register multiple devices per method (e.g., multiple passkeys, multiple TOTP apps),
+     * so deleting by method alone is often too destructive.
+     *
+     * @param dto - Request DTO with deviceId
+     * @returns Removal response (removed device id/method and whether MFA was disabled)
+     * @throws {NAuthException} NOT_FOUND when device does not exist or does not belong to the user
+     *
+     * @example
+     * ```typescript
+     * const result = await mfaService.removeDevice({ deviceId: 123 });
+     * ```
+     */
+    async removeDevice(dto) {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.RemoveDeviceDTO, dto);
         const currentUser = this.getCurrentUserOrThrow();
-        return await this.removeDevicesInternal(currentUser, normalizedMethod, 'user');
+        return await this.removeDeviceInternal(currentUser, dto.deviceId, 'user');
     }
     /**
-     * Admin: Remove MFA devices for a specific user by `sub`.
+     * Admin: Remove a single MFA device by device ID.
      *
-     * @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
+     * Admin APIs are allowed to target any user's device. The owning user is resolved
+     * from the device record and the same internal removal logic is reused.
+     *
+     * @param dto - Admin request DTO with deviceId
+     * @returns Removal response
+     * @throws {NAuthException} NOT_FOUND when device or owning user is not found
      *
      * @example
      * ```typescript
-     * await mfaService.adminRemoveDevices({ sub: 'user-uuid', methodType: 'totp' });
+     * const result = await mfaService.adminRemoveDevice({ deviceId: 123 });
      * ```
      */
-    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(', ')}`);
+    async adminRemoveDevice(dto) {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.AdminRemoveDeviceDTO, dto);
+        const deviceEntity = await this.mfaDeviceRepository.findOne({
+            where: { id: dto.deviceId },
+        });
+        if (!deviceEntity) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'MFA device not found', { deviceId: dto.deviceId });
         }
-        const targetUser = await this.getUserBySubOrThrow(dto.sub);
-        return await this.removeDevicesInternal(targetUser, normalizedMethod, 'admin');
+        const device = deviceEntity;
+        const userEntity = await this.userRepository.findOne({
+            where: { id: device.userId },
+        });
+        if (!userEntity) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found', {
+                userId: device.userId,
+                deviceId: dto.deviceId,
+            });
+        }
+        const targetUser = userEntity;
+        return await this.removeDeviceInternal(targetUser, dto.deviceId, 'admin');
     }
     /**
-     * Set preferred MFA method for a user
+     * Admin: Set a user's preferred MFA device.
      *
-     * Updates the user's preferred MFA method and device primary flags.
-     * Validates that the method is configured for the user before setting it as preferred.
+     * Updates the preferred device for a specified user by device ID.
+     * This is an admin-only operation that allows administrators to manage
+     * user MFA preferences.
      *
-     * 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 method type
-     * @returns Response DTO with success message
-     * @throws {NAuthException} If user not found, invalid method type, or method not configured
+     * @param dto - DTO containing user sub and device ID
+     * @returns Success message
+     * @throws {NAuthException} NOT_FOUND | VALIDATION_FAILED
      *
      * @example
      * ```typescript
-     * // Consumer app controller
-     * @Put('mfa/preferred')
-     * async setPreferredMFAMethod(@CurrentUser() user: IUser, @Body() body: { method: string }) {
-     *   return await this.mfaService.setPreferredMethod({ methodType: body.method });
-     * }
+     * const result = await mfaService.adminSetPreferredDevice({
+     *   sub: 'user-uuid',
+     *   deviceId: 123
+     * });
+     * // Returns: { message: "Preferred MFA device updated" }
      * ```
      */
-    async setPreferredMethod(dto) {
-        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.SetPreferredMethodDTO, 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(', ')}`);
+    async adminSetPreferredDevice(dto) {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.AdminSetPreferredDeviceDTO, dto);
+        // Get target user
+        const user = await this.userRepository.findOne({ where: { sub: dto.sub } });
+        if (!user) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'User not found');
+        }
+        // Delegate to the regular setPreferredDevice logic
+        // but use SetPreferredDeviceDTO format
+        const deviceDto = Object.assign(new dto_1.SetPreferredDeviceDTO(), { deviceId: dto.deviceId });
+        // Temporarily set context user for the operation
+        // Keep admin user in context for audit trails
+        const originalUser = context_storage_1.ContextStorage.get('CURRENT_USER');
+        const adminUser = originalUser; // Admin user is already in context
+        // Set target user as current user for the operation
+        context_storage_1.ContextStorage.set('CURRENT_USER', user);
+        try {
+            // Pass 'admin' flag to setPreferredDevice for proper audit trails
+            const result = await this.setPreferredDevice(deviceDto, 'admin');
+            return { message: result.message };
+        }
+        finally {
+            // Restore original context (admin user)
+            if (originalUser) {
+                context_storage_1.ContextStorage.set('CURRENT_USER', originalUser);
+            }
+            else {
+                context_storage_1.ContextStorage.set('CURRENT_USER', undefined);
+            }
         }
-        const currentUser = this.getCurrentUserOrThrow();
-        return await this.setPreferredMethodInternal(currentUser, normalizedMethod, 'user');
     }
     /**
-     * Admin: Set preferred MFA method for a specific user by `sub`.
+     * Set a specific MFA device as the user's preferred device (self-service).
      *
-     * @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
+     * This updates:
+     * - The user's preferred MFA method (set to the device's method)
+     * - Device `isPrimary` flags (exactly one active device becomes primary/preferred)
+     *
+     * @param dto - Request DTO with deviceId
+     * @returns Success message
+     * @throws {NAuthException} NOT_FOUND when device does not exist or does not belong to the user
      *
      * @example
      * ```typescript
-     * await mfaService.adminSetPreferredMethod({ sub: 'user-uuid', methodType: 'sms' });
+     * await mfaService.setPreferredDevice({ deviceId: 123 });
      * ```
      */
-    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(', ')}`);
+    async setPreferredDevice(dto, updatedBy = 'user') {
+        dto = await (0, dto_validator_1.ensureValidatedDto)(dto_1.SetPreferredDeviceDTO, dto);
+        const currentUser = this.getCurrentUserOrThrow();
+        const activeDevices = await this.getActiveDevicesForUserId(currentUser.id);
+        const targetDevice = activeDevices.find((d) => d.id === dto.deviceId);
+        if (!targetDevice) {
+            throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.NOT_FOUND, 'MFA device not found', { deviceId: dto.deviceId });
+        }
+        // Update user's preferred method to match the preferred device's method.
+        await this.userRepository.update({ id: currentUser.id }, {
+            preferredMfaMethod: targetDevice.type,
+        });
+        // Ensure exactly one active device is primary (marks it as preferred).
+        for (const device of activeDevices) {
+            await this.mfaDeviceRepository.update({ id: device.id }, { isPrimary: device.id === targetDevice.id });
+        }
+        // ============================================================================
+        // Audit: Record preferred MFA device update
+        // ============================================================================
+        if (this.auditService && this.clientInfoService) {
+            try {
+                const actor = updatedBy === 'admin' ? context_storage_1.ContextStorage.get('CURRENT_USER') : currentUser;
+                const actorNameCandidate = actor && updatedBy === 'admin'
+                    ? `${actor.firstName || ''} ${actor.lastName || ''}`.trim()
+                    : '';
+                const performedByName = actorNameCandidate.length > 0 ? actorNameCandidate : actor?.email || undefined;
+                await this.auditService?.recordEvent({
+                    userId: currentUser.id,
+                    eventType: auth_audit_event_type_enum_1.AuthAuditEventType.MFA_PREFERRED_METHOD_UPDATED,
+                    eventStatus: 'INFO',
+                    authMethod: updatedBy === 'admin' ? 'admin' : undefined,
+                    performedBy: updatedBy === 'admin' && actor && actor.sub !== currentUser.sub ? actor.sub : undefined,
+                    metadata: {
+                        newMethod: targetDevice.type,
+                        deviceId: targetDevice.id,
+                        updatedBy,
+                        ...(performedByName && updatedBy === 'admin' ? { performedByName } : {}),
+                    },
+                });
+            }
+            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: currentUser.id,
+                    deviceId: targetDevice.id,
+                });
+            }
         }
-        const targetUser = await this.getUserBySubOrThrow(dto.sub);
-        return await this.setPreferredMethodInternal(targetUser, normalizedMethod, 'admin');
+        return { message: 'Preferred MFA device updated' };
     }
     /**
      * Grant or revoke a user's exemption from multi-factor authentication (MFA) requirements.
@@ -879,9 +922,13 @@ class MFAService {
         // ============================================================================
         // Audit: Record MFA exemption grant/revoke
         // ============================================================================
-        // Note: performedByName is automatically enriched by audit service from context
+        // Note: We also attach performedByName when possible so downstream systems
+        // have a stable snapshot even if admin profile changes later.
         if (this.auditService && this.clientInfoService) {
             try {
+                const actor = context_storage_1.ContextStorage.get('CURRENT_USER');
+                const actorNameCandidate = `${actor?.firstName || ''} ${actor?.lastName || ''}`.trim();
+                const performedByName = actorNameCandidate.length > 0 ? actorNameCandidate : actor?.email || undefined;
                 await this.auditService.recordEvent({
                     userId: user.id,
                     eventType: dto.exempt ? auth_audit_event_type_enum_1.AuthAuditEventType.MFA_EXEMPTION_GRANTED : auth_audit_event_type_enum_1.AuthAuditEventType.MFA_EXEMPTION_REVOKED,
@@ -892,7 +939,7 @@ class MFAService {
                     metadata: {
                         previousExemptStatus: userEntity.mfaExempt,
                         newExemptStatus: dto.exempt,
-                        // performedByName will be automatically enriched by audit service from context
+                        ...(performedByName ? { performedByName } : {}),
                     },
                 });
             }