@nauth-toolkit/core 0.1.14 → 0.1.18

package/dist/services/mfa.service.js

@@ -6,6 +6,35 @@ const error_codes_enum_1 = require("../enums/error-codes.enum");
 const mfa_method_enum_1 = require("../enums/mfa-method.enum");
 const auth_challenge_dto_1 = require("../dto/auth-challenge.dto");
 const auth_audit_event_type_enum_1 = require("../enums/auth-audit-event-type.enum");
+/**
+ * MFA Service Registry
+ *
+ * Central registry for managing MFA provider services.
+ * Routes requests to the appropriate provider based on method name.
+ *
+ * Provider services (TOTP, SMS, Passkey) automatically register themselves
+ * when their modules are imported via OnModuleInit.
+ *
+ * **Key Features:**
+ * - Provider registration and lookup
+ * - Unified interface for MFA operations
+ * - Routing verification requests to correct provider
+ * - Device management operations
+ *
+ * @example
+ * ```typescript
+ * @Controller('auth')
+ * export class AuthController {
+ *   constructor(private readonly mfaService: MFAService) {}
+ *
+ *   @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);
+ *   }
+ * }
+ * ```
+ */
 class MFAService {
     mfaDeviceRepository;
     userRepository;
@@ -24,6 +53,21 @@ class MFAService {
         this.auditService = auditService;
         this.clientInfoService = clientInfoService;
     }
+    /**
+     * Register an MFA provider
+     *
+     * Called automatically by provider modules during initialization.
+     * Provider method names must be unique.
+     *
+     * @param provider - Provider service instance (must have methodName property)
+     * @throws {NAuthException} If provider is already registered
+     *
+     * @example
+     * ```typescript
+     * // In provider module's OnModuleInit
+     * this.mfaService.registerProvider(this.totpProvider);
+     * ```
+     */
     registerProvider(provider) {
         const name = provider.methodName;
         if (this.providers.has(name)) {
@@ -31,6 +75,19 @@ class MFAService {
         }
         this.providers.set(name, provider);
     }
+    /**
+     * Get a provider by method name
+     *
+     * @param methodName - Method name (e.g., 'totp', 'sms', 'passkey')
+     * @returns Provider service instance
+     * @throws {NAuthException} If provider is not registered
+     *
+     * @example
+     * ```typescript
+     * const totpProvider = this.mfaService.getProvider('totp');
+     * const setupData = await totpProvider.setup(user);
+     * ```
+     */
     getProvider(methodName) {
         const provider = this.providers.get(methodName);
         if (!provider) {
@@ -38,39 +95,115 @@ class MFAService {
         }
         return provider;
     }
+    /**
+     * Check if a provider is registered
+     *
+     * @param dto - Request DTO with method name
+     * @returns Response DTO with hasProvider flag
+     *
+     * @example
+     * ```typescript
+     * const result = await this.mfaService.hasProvider({ methodName: 'totp' });
+     * if (result.hasProvider) {
+     *   // TOTP is available
+     * }
+     * ```
+     */
     hasProvider(dto) {
         return {
             hasProvider: this.providers.has(dto.methodName),
         };
     }
+    /**
+     * Get all registered provider method names
+     *
+     * @returns Response DTO with array of method names
+     *
+     * @example
+     * ```typescript
+     * const result = this.mfaService.listProviders(); // { providers: ['totp', 'sms', 'passkey'] }
+     * ```
+     */
     listProviders() {
         return {
             providers: Array.from(this.providers.keys()),
         };
     }
+    /**
+     * Get available MFA methods for a user
+     *
+     * Returns list of methods that are:
+     * - Registered as providers
+     * - Allowed by configuration
+     *
+     * This returns ALL methods that can be set up, not just ones the user has configured.
+     * Use getUserDevices() to check which methods the user has actually set up.
+     *
+     * @param dto - Request DTO with user sub
+     * @returns Response DTO with array of available method names
+     *
+     * @example
+     * ```typescript
+     * const result = await this.mfaService.getAvailableMethods({ sub: user.sub });
+     * // Returns: { availableMethods: ['totp', 'sms', 'passkey'] }
+     * ```
+     */
     async getAvailableMethods(dto) {
+        // Look up user by sub to validate user exists
         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 available = [];
         for (const [methodName, provider] of this.providers.entries()) {
+            // Check if method is allowed by configuration
             if (!provider.isMethodAllowed()) {
                 continue;
             }
+            // Return all allowed methods (whether user has set them up or not)
             available.push(methodName);
         }
         return {
             availableMethods: available,
         };
     }
+    /**
+     * Verify MFA code using appropriate provider
+     *
+     * Routes the verification request to the correct provider based on method name.
+     *
+     * @param dto - Request DTO with user sub, method name, code, and optional device ID
+     * @returns Response DTO with verification result
+     * @throws {NAuthException} If method is not available or verification fails
+     *
+     * @example
+     * ```typescript
+     * // Verify TOTP code
+     * const result = await this.mfaService.verifyCode({
+     *   sub: user.sub,
+     *   methodName: 'totp',
+     *   code: '123456'
+     * });
+     *
+     * // Verify backup code
+     * const result = await this.mfaService.verifyCode({
+     *   sub: user.sub,
+     *   methodName: 'backup',
+     *   code: 'ABC12345'
+     * });
+     * ```
+     */
     async verifyCode(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;
+        // Handle backup codes specially (not a provider, uses base class helper)
         if (dto.methodName === mfa_method_enum_1.MFAMethod.BACKUP) {
+            // Get any provider to access backup code verification
+            // All providers extend BaseMFAProviderService which has verifyBackupCode
             const firstProvider = Array.from(this.providers.values())[0];
             if (firstProvider && 'verifyBackupCode' in firstProvider) {
                 const providerWithBackup = firstProvider;
@@ -79,11 +212,28 @@ class MFAService {
             }
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Backup code verification not available');
         }
+        // Get provider and verify
         const provider = this.getProvider(dto.methodName);
         const isValid = await provider.verify(user, dto.code, dto.deviceId);
         return { valid: isValid };
     }
+    /**
+     * Setup MFA device using appropriate provider
+     *
+     * @param dto - Request DTO with user sub, method name, and optional setup data
+     * @returns Response DTO with provider-specific setup data
+     *
+     * @example
+     * ```typescript
+     * const result = await this.mfaService.setup({
+     *   sub: user.sub,
+     *   methodName: 'totp'
+     * });
+     * // Returns: { setupData: { secret, qrCode, manualEntryKey } }
+     * ```
+     */
     async setup(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');
@@ -95,11 +245,25 @@ class MFAService {
             setupData: setupData,
         };
     }
+    /**
+     * Get user's MFA devices
+     *
+     * @param dto - Request DTO with user sub
+     * @returns Response DTO with array of MFA devices
+     *
+     * @example
+     * ```typescript
+     * const result = await this.mfaService.getUserDevices({ sub: user.sub });
+     * // Returns: { devices: [...] }
+     * ```
+     */
     async getUserDevices(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' },
@@ -108,7 +272,33 @@ class MFAService {
             devices: devices,
         };
     }
+    /**
+     * Get comprehensive MFA status for a user
+     *
+     * 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
+     *
+     * @example
+     * ```typescript
+     * @Get('mfa/status')
+     * async getMFAStatus(@CurrentUser() user: IUser) {
+     *   return await this.mfaService.getMFAStatus({ sub: user.sub });
+     * }
+     * ```
+     */
     async getMFAStatus(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',
@@ -125,18 +315,23 @@ class MFAService {
             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,
@@ -150,12 +345,43 @@ class MFAService {
             mfaExemptGrantedAt: userEntity.mfaExemptGrantedAt || null,
         };
     }
+    /**
+     * 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())
+     * - Validates method type
+     * - Removes all active devices of the specified method type
+     * - Updates user's preferred method if the removed method was preferred
+     * - Updates device primary flags
+     * - Disables MFA if this was the last device
+     * - Creates MFA_SETUP_REQUIRED challenge if MFA enforcement requires it
+     *
+     * 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
+     * @returns Response DTO with deletedCount and whether MFA was disabled
+     * @throws {NAuthException} If user not found, invalid method type, or no devices found
+     *
+     * @example
+     * ```typescript
+     * // 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 });
+     *   return { message: 'MFA method removed successfully', ...result };
+     * }
+     * ```
+     */
     async removeDevices(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');
@@ -164,29 +390,38 @@ class MFAService {
         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({
@@ -195,6 +430,7 @@ class MFAService {
                         eventStatus: 'INFO',
                         reason: 'all_devices_removed',
                         description: 'MFA disabled - all devices removed',
+                        // Client info automatically included from context
                         metadata: {
                             removedMethod: normalizedMethod,
                             deletedCount,
@@ -202,6 +438,7 @@ class MFAService {
                     });
                 }
                 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,
@@ -209,11 +446,13 @@ class MFAService {
                     });
                 }
             }
+            // 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,
@@ -221,21 +460,26 @@ class MFAService {
                         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 });
@@ -244,9 +488,13 @@ class MFAService {
                 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;
@@ -260,9 +508,11 @@ class MFAService {
                         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,
@@ -273,12 +523,36 @@ class MFAService {
         }
         return { deletedCount, mfaDisabled };
     }
+    /**
+     * Set preferred MFA method for a user
+     *
+     * 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.
+     *
+     * 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
+     * @returns Response DTO with success message
+     * @throws {NAuthException} If user not found, invalid method type, or method not configured
+     *
+     * @example
+     * ```typescript
+     * // 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 });
+     * }
+     * ```
+     */
     async setPreferredMethod(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 not found');
@@ -287,20 +561,28 @@ class MFAService {
         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;
@@ -309,6 +591,7 @@ class MFAService {
                     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,
@@ -316,6 +599,7 @@ class MFAService {
                 });
             }
             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,
@@ -328,22 +612,57 @@ class MFAService {
             message: 'Preferred method updated',
         };
     }
+    /**
+     * Grant or revoke a user's exemption from multi-factor authentication (MFA) requirements.
+     *
+     * 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 user sub, exempt flag, reason, and grantedBy
+     * @returns Response DTO with updated exemption fields
+     * @throws {NAuthException} If the user is not found
+     *
+     * @example
+     * ```typescript
+     * // Grant MFA exemption
+     * await mfaService.setMFAExemption({
+     *   userSub: 'user-uuid',
+     *   exempt: true,
+     *   reason: 'Business partner requires MFA bypass',
+     *   grantedBy: 'admin@example.com'
+     * });
+     *
+     * // Revoke MFA exemption
+     * await mfaService.setMFAExemption({
+     *   userSub: 'user-uuid',
+     *   exempt: false,
+     *   reason: 'MFA now mandatory for this user',
+     *   grantedBy: 'admin@example.com'
+     * });
+     * ```
+     */
     async setMFAExemption(dto) {
+        // Find user by sub (external identifier)
         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 user = userEntity;
+        // Prepare update
         const updateFields = {
             mfaExempt: dto.exempt,
             mfaExemptReason: dto.reason || null,
             mfaExemptGrantedAt: dto.exempt ? new Date() : null,
             mfaExemptGrantedBy: dto.exempt ? dto.grantedBy || null : null,
         };
+        // If revoking exemption and MFA is required, check if user needs to set up MFA
+        // Note: This is just for logging - actual MFA setup requirement is checked by state machine on next login
         if (!dto.exempt && userEntity.mfaExempt === true && !userEntity.mfaEnabled) {
             this.logger?.warn?.(`MFA exemption revoked for user ${dto.userSub} - MFA setup will be required on next login`);
         }
+        // Update user in database
         await this.userRepository.update(userEntity.id, updateFields);
+        // Log the exemption change for audit trail
         this.logger?.log?.(`MFA exemption ${dto.exempt ? 'granted' : 'revoked'} for user ${dto.userSub}`, {
             userSub: dto.userSub,
             exempt: dto.exempt,
@@ -351,6 +670,9 @@ class MFAService {
             grantedBy: dto.grantedBy || 'System',
             timestamp: new Date().toISOString(),
         });
+        // ============================================================================
+        // Audit: Record MFA exemption grant/revoke
+        // ============================================================================
         if (this.auditService && this.clientInfoService) {
             try {
                 await this.auditService.recordEvent({
@@ -358,6 +680,7 @@ class MFAService {
                     eventType: dto.exempt ? auth_audit_event_type_enum_1.AuthAuditEventType.MFA_EXEMPTION_GRANTED : auth_audit_event_type_enum_1.AuthAuditEventType.MFA_EXEMPTION_REVOKED,
                     eventStatus: 'INFO',
                     performedBy: dto.grantedBy || null,
+                    // Client info automatically included from context
                     reason: dto.reason || null,
                     metadata: {
                         previousExemptStatus: userEntity.mfaExempt,
@@ -366,6 +689,7 @@ class MFAService {
                 });
             }
             catch (auditError) {
+                // Non-blocking: Log but continue
                 const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
                 this.logger?.error?.(`Failed to record MFA exemption audit event: ${errorMessage}`, {
                     error: auditError,
@@ -373,6 +697,7 @@ class MFAService {
                 });
             }
         }
+        // Fetch updated user to return exemption fields
         const exemptionData = await this.userRepository.findOne({
             where: { id: userEntity.id },
             select: ['mfaExempt', 'mfaExemptReason', 'mfaExemptGrantedAt'],
@@ -386,19 +711,51 @@ class MFAService {
             mfaExemptGrantedAt: exemptionData.mfaExemptGrantedAt || null,
         };
     }
+    /**
+     * Get MFA setup data during MFA_SETUP_REQUIRED challenge
+     *
+     * Returns provider-specific setup data:
+     * - TOTP: { secret, qrCode, manualEntryKey }
+     * - SMS: { maskedPhone } or error if phone required
+     * - Passkey: WebAuthn registration options
+     *
+     * @param dto - Request DTO with session token, method, and optional setup data
+     * @returns Response DTO with provider-specific setup data
+     * @throws {NAuthException} INVALID_CHALLENGE_SESSION | VALIDATION_FAILED | PHONE_REQUIRED
+     *
+     * @example
+     * ```typescript
+     * const result = await mfaService.getSetupData({
+     *   session: 'session-token',
+     *   method: 'totp'
+     * });
+     * // Returns: { setupData: { secret: '...', qrCode: '...', manualEntryKey: '...' } }
+     *
+     * const result = await mfaService.getSetupData({
+     *   session: 'session-token',
+     *   method: 'sms',
+     *   setupData: { phoneNumber: '+1234567890' }
+     * });
+     * // Returns: { setupData: { maskedPhone: '***-***-7890' } }
+     * ```
+     */
     async getSetupData(dto) {
         if (!this.challengeService) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'Challenge service is not available');
         }
         this.logger?.debug?.(`Getting MFA setup data: session=${dto.session}, method=${dto.method}`);
+        // Validate session and ensure it's MFA_SETUP_REQUIRED
         const challengeSession = await this.challengeService.validateSession(dto.session);
         if (challengeSession.challengeName !== auth_challenge_dto_1.AuthChallenge.MFA_SETUP_REQUIRED) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Cannot get setup data: expected MFA_SETUP_REQUIRED challenge, got ${challengeSession.challengeName}`);
         }
+        // Get user from session
         const user = challengeSession.user;
         if (!user) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Challenge session has no associated user');
         }
+        // Get provider and call setup
+        // Pass challenge session ID in setupData so provider can link verification tokens
         const setupDataWithSession = {
             ...(dto.setupData || {}),
             challengeSessionId: challengeSession.id,
@@ -411,24 +768,47 @@ class MFAService {
             setupData: result,
         };
     }
+    /**
+     * Get MFA challenge data during MFA_REQUIRED challenge
+     *
+     * Currently only used for passkey authentication to get WebAuthn options.
+     * SMS/TOTP codes are sent automatically when the challenge is created.
+     *
+     * @param dto - Request DTO with session token and method
+     * @returns Response DTO with provider-specific challenge data
+     * @throws {NAuthException} INVALID_CHALLENGE_SESSION | VALIDATION_FAILED
+     *
+     * @example
+     * ```typescript
+     * const result = await mfaService.getChallengeData({
+     *   session: 'session-token',
+     *   method: 'passkey'
+     * });
+     * // Returns: { challengeData: { challenge: '...', allowCredentials: [...], ... } }
+     * ```
+     */
     async getChallengeData(dto) {
         if (!this.challengeService) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'Challenge service is not available');
         }
         this.logger?.debug?.(`Getting MFA challenge data: session=${dto.session}, method=${dto.method}`);
+        // Validate session and ensure it's MFA_REQUIRED
         const challengeSession = await this.challengeService.validateSession(dto.session);
         if (challengeSession.challengeName !== auth_challenge_dto_1.AuthChallenge.MFA_REQUIRED) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, `Cannot get challenge data: expected MFA_REQUIRED challenge, got ${challengeSession.challengeName}`);
         }
+        // Get user from session
         const user = challengeSession.user;
         if (!user) {
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.VALIDATION_FAILED, 'Challenge session has no associated user');
         }
+        // Get provider and send challenge
         const provider = this.getProvider(dto.method);
         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);
+        // For passkey, store the challenge in session metadata for verification
         if (dto.method === 'passkey') {
             const passkeyOptions = challengeData;
             const passkeyChallenge = passkeyOptions.options?.challenge;