@nauth-toolkit/core 0.1.13 → 0.1.17

package/dist/services/auth-challenge-helper.service.js

@@ -41,6 +41,22 @@ const nauth_exception_1 = require("../exceptions/nauth.exception");
 const error_codes_enum_1 = require("../enums/error-codes.enum");
 const mfa_method_enum_1 = require("../enums/mfa-method.enum");
 const auth_flow_state_machine_types_1 = require("./auth-flow-state-machine.types");
+/**
+ * Helper service for challenge-response authentication flows
+ *
+ * This service determines if a user needs to complete challenges
+ * before full authentication can be granted, and generates appropriate
+ * responses including MFA challenges.
+ *
+ * @example
+ * ```typescript
+ * const response = await challengeHelper.determineAuthResponse(
+ *   user,
+ *   'login',
+ *   { ipAddress: '1.2.3.4' }
+ * );
+ * ```
+ */
 class AuthChallengeHelperService {
     challengeService;
     jwtService;
@@ -64,20 +80,68 @@ class AuthChallengeHelperService {
         this.emailVerificationService = emailVerificationService;
         this.phoneVerificationService = phoneVerificationService;
     }
+    // ============================================================================
+    // OLD METHODS DELETED - Replaced by state machine
+    // ============================================================================
+    // determinePendingChallenges() - DELETED (replaced by state machine)
+    // isMFASetupRequired() - DELETED (replaced by state machine)
+    // checkMFARequirement() - DELETED (replaced by state machine)
+    // All challenge determination is now handled by determineAuthResponse() using state machine
+    /**
+     * Create challenge response for authentication
+     *
+     * Generates a challenge session and returns challenge details to client.
+     * Sends verification codes when challenges are created to ensure sequential flow.
+     *
+     * @param user - User who needs to complete challenges
+     * @param challengeName - Type of challenge
+     * @param config - Auth configuration
+     * @param authMethod - Authentication method ('password' or 'social')
+     * @param authProvider - Provider name for social auth (e.g., 'google', 'facebook')
+     * @returns Challenge response DTO
+     *
+     * @example
+     * ```typescript
+     * const response = await challengeHelper.createChallengeResponse(
+     *   user,
+     *   AuthChallenge.VERIFY_EMAIL,
+     *   config,
+     *   'social',
+     *   'google'
+     * );
+     * ```
+     */
     async createChallengeResponse(user, challengeName, config, authMethod = 'password', authProvider, skipAutoSend) {
+        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
+        // Note: ClientInfoService is used transparently by ChallengeService and AuditService
+        // ============================================================================
+        // STEP 1: Create challenge session FIRST (before sending codes)
+        // ============================================================================
+        // This ensures the session exists before any verification codes are sent.
+        // Creating the session first is critical for proper audit trail and session tracking.
         this.logger?.debug?.(`Creating challenge with authMethod=${authMethod}, authProvider=${authProvider || 'none'} for user ${user.sub}`);
+        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
         const challengeSession = await this.challengeService.createChallengeSession(user, challengeName, {
             email: user.email,
             phone: user.phone,
-            authMethod,
-            authProvider,
+            authMethod, // Store auth method for challenge completion flow
+            authProvider, // Store provider for social auth (e.g., 'google', 'facebook')
         });
+        // ============================================================================
+        // STEP 2: Send verification codes AFTER session is created
+        // ============================================================================
+        // This ensures codes are sent at the right time:
+        // - Email code sent when VERIFY_EMAIL challenge is created
+        // - Phone code sent when VERIFY_PHONE challenge is created (after email is verified)
+        // This prevents sending both codes at once, avoiding user confusion.
+        // Challenges are sequential: first VERIFY_EMAIL, then VERIFY_PHONE
         if (challengeName === auth_challenge_dto_1.AuthChallenge.VERIFY_EMAIL && this.emailVerificationService) {
             this.logger?.log?.(`Sending verification email to: ${user.email}`);
+            // Fire and forget - don't block challenge response
             const emailDto = Object.assign(new verify_email_dto_1.SendVerificationEmailDTO(), {
                 sub: user.sub,
                 baseUrl: undefined,
-                challengeSessionId: challengeSession.id,
+                challengeSessionId: challengeSession.id, // Link verification token to this challenge session
             });
             this.emailVerificationService
                 .sendVerificationEmail(emailDto)
@@ -89,12 +153,14 @@ class AuthChallengeHelperService {
                 this.logger?.error?.(`Failed to send verification email to ${user.email}: ${errorMessage}`);
             });
         }
+        // Skip auto-send if SMS was already sent (e.g., during phone collection)
         if (!skipAutoSend && challengeName === auth_challenge_dto_1.AuthChallenge.VERIFY_PHONE && this.phoneVerificationService && user.phone) {
             this.logger?.log?.(`Sending verification SMS to: ${user.phone}`);
+            // Fire and forget - don't block challenge response
             const smsDto = Object.assign(new verify_phone_dto_1.SendVerificationSMSDTO(), {
                 sub: user.sub,
-                skipAlreadyVerifiedCheck: false,
-                challengeSessionId: challengeSession.id,
+                skipAlreadyVerifiedCheck: false, // Explicitly set to false for phone verification (not MFA)
+                challengeSessionId: challengeSession.id, // Link verification token to this challenge session
             });
             this.phoneVerificationService
                 .sendVerificationSMS(smsDto)
@@ -106,6 +172,17 @@ class AuthChallengeHelperService {
                 this.logger?.error?.(`Failed to send verification SMS to ${user.phone}: ${errorMessage}`);
             });
         }
+        // ============================================================================
+        // STEP 3: Send MFA challenge code for MFA_REQUIRED (if SMS is preferred method)
+        // ============================================================================
+        // When user logs in and MFA verification is required, automatically send SMS code
+        // if SMS is their preferred MFA method. This provides better UX by not requiring
+        // a separate API call to trigger code sending.
+        //
+        // Note: MFA_REQUIRED challenges are handled by createMFAChallengeResponse()
+        // which includes auto-send SMS logic
+        // Build challenge parameters
+        // Note: Type is Record<string, unknown> to allow arrays (e.g., allowedMethods for MFA)
         const challengeParameters = {};
         switch (challengeName) {
             case auth_challenge_dto_1.AuthChallenge.VERIFY_EMAIL:
@@ -117,6 +194,7 @@ class AuthChallengeHelperService {
                 challengeParameters.codeDeliveryDestination = user.phone
                     ? this.challengeService.maskPhone(user.phone)
                     : undefined;
+                // If no phone, indicate user must provide it first
                 if (!user.phone) {
                     challengeParameters.requiresPhoneCollection = 'true';
                     challengeParameters.instructions = 'You must add a phone number and verify it to continue';
@@ -124,9 +202,11 @@ class AuthChallengeHelperService {
                 break;
             case auth_challenge_dto_1.AuthChallenge.MFA_REQUIRED:
                 challengeParameters.instructions = 'Multi-factor authentication is required';
+                // Include masked phone if SMS is preferred method
                 if (user.preferredMfaMethod === 'sms' && user.phone) {
                     challengeParameters.codeDeliveryDestination = this.challengeService.maskPhone(user.phone);
                 }
+                // Include masked email if Email is preferred method
                 if (user.preferredMfaMethod === 'email' && user.email) {
                     challengeParameters.codeDeliveryDestination = this.challengeService.maskEmail(user.email);
                 }
@@ -149,17 +229,50 @@ class AuthChallengeHelperService {
         };
         return response;
     }
+    // ============================================================================
+    // MFA Challenge Support
+    // ============================================================================
+    // checkMFARequirement() - DELETED (replaced by state machine)
+    // All MFA requirement checking is now handled by state machine in determineAuthResponse()
+    /**
+     * Create MFA setup challenge response
+     *
+     * Generates challenge session for MFA setup requirement.
+     * User must set up MFA before being allowed to login.
+     *
+     * @param user - User requiring MFA setup
+     * @param config - Auth configuration
+     * @param authMethod - Authentication method ('password' or 'social')
+     * @param authProvider - Provider name for social auth (e.g., 'google', 'facebook')
+     * @returns MFA setup challenge response
+     *
+     * @example
+     * ```typescript
+     * const response = await challengeHelper.createMFASetupChallengeResponse(
+     *   user,
+     *   config,
+     *   'social',
+     *   'google'
+     * );
+     * // Returns: { challengeName: 'MFA_SETUP_REQUIRED', session: '...', challengeParameters: {...} }
+     * ```
+     */
     async createMFASetupChallengeResponse(user, config, authMethod = 'password', authProvider) {
+        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
+        // Note: ClientInfoService is used transparently by ChallengeService and AuditService
         this.logger?.log?.(`Creating MFA setup challenge for user: ${user.sub}`);
         const allowedMethods = config.mfa?.allowedMethods || [...mfa_method_enum_1.MFADeviceMethods];
+        // Create challenge session with auth context
         this.logger?.debug?.(`Creating MFA setup challenge with authMethod=${authMethod}, authProvider=${authProvider || 'none'} for user ${user.sub}`);
+        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
         const challengeSession = await this.challengeService.createChallengeSession(user, auth_challenge_dto_1.AuthChallenge.MFA_SETUP_REQUIRED, {
             allowedMethods,
             requiresSetup: true,
-            authMethod,
-            authProvider,
+            authMethod, // Store auth method for challenge completion flow
+            authProvider, // Store provider for social auth
         });
         this.logger?.log?.(`MFA setup challenge created for user: ${user.sub}`);
+        // Return challenge response
         return {
             challengeName: auth_challenge_dto_1.AuthChallenge.MFA_SETUP_REQUIRED,
             session: challengeSession.sessionToken,
@@ -170,49 +283,87 @@ class AuthChallengeHelperService {
             userSub: user.sub,
         };
     }
+    /**
+     * Create MFA challenge response
+     *
+     * Generates challenge session for MFA verification.
+     * Returns available MFA methods and challenge parameters.
+     *
+     * @param user - User requiring MFA
+     * @returns MFA challenge response
+     * @remarks Client info (ipAddress, userAgent) is automatically extracted from ClientInfoService context
+     *
+     * @example
+     * ```typescript
+     * const response = await challengeHelper.createMFAChallengeResponse(
+     *   user,
+     *   '1.2.3.4',
+     *   'Mozilla/5.0...'
+     * );
+     * // Returns: { challengeName: 'MFA_REQUIRED', session: '...', challengeParameters: {...} }
+     * ```
+     */
     async createMFAChallengeResponse(user) {
+        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
+        // Note: ClientInfoService is used transparently by ChallengeService and AuditService
         this.logger?.log?.(`Creating MFA challenge for user: ${user.sub}`);
+        // Get user's active MFA devices
         const devices = (await this.mfaDeviceRepository.find({
             where: { userId: user.id, isActive: true },
             order: { isPrimary: 'DESC', lastUsedAt: 'DESC' },
         }));
         if (devices.length === 0) {
             this.logger?.warn?.(`User has MFA enabled but no active devices: ${user.sub}`);
+            // User has MFA enabled but no devices - should not happen
+            // Allow login and let them set up MFA
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'MFA enabled but no devices configured');
         }
+        // Get available methods (device types only - no backup)
         const deviceMethods = [...new Set(devices.map((d) => d.type))];
+        // Build full available methods list (including backup if available)
         const availableMethods = [...deviceMethods];
         if (user.backupCodes && user.backupCodes.length > 0) {
             availableMethods.push(mfa_method_enum_1.MFAMethod.BACKUP);
         }
+        // Debug logging for troubleshooting
         this.logger?.debug?.(`MFA challenge for user ${user.sub}: preferredMfaMethod=${user.preferredMfaMethod}, deviceMethods=[${deviceMethods.join(', ')}], devices=[${devices.map((d) => `${d.type}${d.isPrimary ? '(primary)' : ''}`).join(', ')}]`);
+        // Determine preferred method - prioritize user.preferredMfaMethod over primaryDevice
+        // This ensures that when user explicitly sets a preferred method, it's respected
         let preferredMethod;
+        // Normalize preferred method to lowercase for comparison (database might store in different case)
         const normalizedPreferredMethod = user.preferredMfaMethod?.toLowerCase();
+        // Check if user has a preferred method and it's available
         if (normalizedPreferredMethod &&
             (normalizedPreferredMethod === mfa_method_enum_1.MFAMethod.TOTP ||
                 normalizedPreferredMethod === mfa_method_enum_1.MFAMethod.SMS ||
                 normalizedPreferredMethod === mfa_method_enum_1.MFAMethod.EMAIL ||
                 normalizedPreferredMethod === mfa_method_enum_1.MFAMethod.PASSKEY) &&
             deviceMethods.some((m) => m.toLowerCase() === normalizedPreferredMethod)) {
+            // User has explicitly set a preferred method and it's available
+            // Find the actual method from deviceMethods to ensure case consistency
             preferredMethod =
                 deviceMethods.find((m) => m.toLowerCase() === normalizedPreferredMethod) || normalizedPreferredMethod;
             this.logger?.debug?.(`Using user preferred MFA method: ${preferredMethod} (from user.preferredMfaMethod: ${user.preferredMfaMethod})`);
         }
         else {
+            // Fallback to primary device or first available method
             const primaryDevice = devices.find((d) => d.isPrimary);
             preferredMethod = primaryDevice?.type || deviceMethods[0];
             this.logger?.debug?.(`Using fallback MFA method: ${preferredMethod} (preferred: ${user.preferredMfaMethod}, available: ${deviceMethods.join(', ')})`);
         }
+        // Get masked phone if SMS is available
         let maskedPhone;
         const smsDevice = devices.find((d) => d.type === mfa_method_enum_1.MFAMethod.SMS && d.phoneNumber);
         if (smsDevice?.phoneNumber) {
             const digits = smsDevice.phoneNumber.replace(/\D/g, '');
             maskedPhone = digits.length >= 4 ? `***-***-${digits.slice(-4)}` : smsDevice.phoneNumber;
         }
+        // Get masked email if Email is available
         let maskedEmail;
         const emailDevice = devices.find((d) => d.type === mfa_method_enum_1.MFAMethod.EMAIL && d.email);
-        const emailToMask = emailDevice?.email || user.email;
+        const emailToMask = emailDevice?.email || user.email; // Fallback to user.email if device doesn't have it
         if (emailToMask) {
+            // Mask email: show first char and domain (e.g., u***r@example.com)
             const [localPart, domain] = emailToMask.split('@');
             if (localPart && domain) {
                 const firstChar = localPart[0];
@@ -223,22 +374,36 @@ class AuthChallengeHelperService {
                 maskedEmail = emailToMask;
             }
         }
+        // Create challenge session
+        // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
+        // Store preferred method in metadata for resend endpoint to know which method to use
         const challengeSession = await this.challengeService.createChallengeSession(user, auth_challenge_dto_1.AuthChallenge.MFA_REQUIRED, {
             availableMethods,
             preferredMethod,
             maskedPhone,
             maskedEmail,
-            method: preferredMethod,
+            method: preferredMethod, // Store method in metadata for resend endpoint
         });
         this.logger?.log?.(`MFA challenge created for user: ${user.sub}`);
+        // ============================================================================
+        // Auto-send SMS code if SMS is the preferred method
+        // ============================================================================
+        // Automatically send SMS code if:
+        // 1. SMS is user's preferred MFA method, OR
+        // 2. SMS is the ONLY MFA method they have setup
+        //
+        // This provides better UX by not requiring a separate API call to trigger code sending.
         const smsIsPreferred = preferredMethod.toLowerCase() === 'sms';
         const smsIsOnly = deviceMethods.length === 1 && deviceMethods[0].toLowerCase() === 'sms';
         if ((smsIsPreferred || smsIsOnly) && this.phoneVerificationService && user.phone) {
             this.logger?.log?.(`Auto-sending MFA SMS code to user ${user.sub} (preferred=${smsIsPreferred}, only=${smsIsOnly})`);
+            // Fire and forget - don't block challenge response
+            // Use PhoneVerificationService which handles SMS sending, rate limits, and token storage
+            // skipAlreadyVerifiedCheck=true because phone is already verified but we need MFA code
             const smsDto = Object.assign(new verify_phone_dto_1.SendVerificationSMSDTO(), {
                 sub: user.sub,
                 skipAlreadyVerifiedCheck: true,
-                challengeSessionId: challengeSession.id,
+                challengeSessionId: challengeSession.id, // Link MFA SMS code to this challenge session
             });
             this.phoneVerificationService
                 .sendVerificationSMS(smsDto)
@@ -259,15 +424,26 @@ class AuthChallengeHelperService {
                 `deviceMethods=[${deviceMethods.join(', ')}], ` +
                 `phone=${!!user.phone}`);
         }
+        // ============================================================================
+        // Auto-send Email code if Email is the preferred method
+        // ============================================================================
+        // Automatically send Email code if:
+        // 1. Email is user's preferred MFA method, OR
+        // 2. Email is the ONLY MFA method they have setup
+        //
+        // This provides better UX by not requiring a separate API call to trigger code sending.
         const emailIsPreferred = preferredMethod.toLowerCase() === 'email';
         const emailIsOnly = deviceMethods.length === 1 && deviceMethods[0].toLowerCase() === 'email';
         if ((emailIsPreferred || emailIsOnly) && this.emailVerificationService && user.email) {
             this.logger?.log?.(`Auto-sending MFA Email code to user ${user.sub} (preferred=${emailIsPreferred}, only=${emailIsOnly})`);
+            // Fire and forget - don't block challenge response
+            // Use EmailVerificationService which handles email sending, rate limits, and token storage
+            // skipAlreadyVerifiedCheck=true because email is already verified but we need MFA code
             const emailDto = Object.assign(new verify_email_dto_1.SendVerificationEmailDTO(), {
                 sub: user.sub,
                 baseUrl: undefined,
                 skipAlreadyVerifiedCheck: true,
-                challengeSessionId: challengeSession.id,
+                challengeSessionId: challengeSession.id, // Link MFA email code to this challenge session
             });
             this.emailVerificationService
                 .sendVerificationEmail(emailDto)
@@ -288,6 +464,8 @@ class AuthChallengeHelperService {
                 `deviceMethods=[${deviceMethods.join(', ')}], ` +
                 `email=${!!user.email}`);
         }
+        // Return challenge response
+        // Always include maskedEmail if email is preferred, even if undefined (frontend can use user.email)
         const challengeParams = {
             availableMethods,
             preferredMethod: preferredMethod,
@@ -296,6 +474,7 @@ class AuthChallengeHelperService {
             challengeParams.maskedPhone = maskedPhone;
         }
         if (maskedEmail || preferredMethod.toLowerCase() === 'email') {
+            // Include maskedEmail if available, or if email is preferred (frontend will handle display)
             challengeParams.maskedEmail = maskedEmail || user.email || '';
         }
         return {
@@ -304,37 +483,79 @@ class AuthChallengeHelperService {
             challengeParameters: challengeParams,
         };
     }
-    async createSuccessResponse(user, deviceToken, isTrusted, _isSocialLogin = false, _metadata) {
+    // ============================================================================
+    // Success Response
+    // ============================================================================
+    /**
+     * Create successful authentication response with tokens
+     *
+     * Generates tokens and session for fully authenticated user.
+     *
+     * @param user - Authenticated user
+     * @param deviceToken - Device token (optional)
+     * @param isTrusted - Whether device is trusted (optional)
+     * @param isSocialLogin - Whether this is a social login (optional)
+     * @param metadata - Response metadata (optional)
+     * @returns Auth response with tokens
+     *
+     * @example
+     * ```typescript
+     * const response = await challengeHelper.createSuccessResponse(
+     *   user,
+     *   'abc123',
+     *   true,
+     *   false
+     * );
+     * ```
+     */
+    async createSuccessResponse(user, deviceToken, isTrusted, _isSocialLogin = false, // Reserved for future use
+    _metadata) {
+        // Get client info from ClientInfoService (for deviceToken only - IP/userAgent come from context automatically)
         const clientInfo = this.clientInfoService.get();
         const finalDeviceToken = clientInfo.deviceToken || deviceToken;
+        // ============================================================================
+        // SECURITY: Defense-in-depth validation before token issuance
+        // ============================================================================
+        // Note: Challenge validation is now handled by state machine in determineAuthResponse
+        // This method is only called when state is AUTHENTICATED, so no additional check needed
+        // Generate token family for rotation tracking
         const tokenFamily = this.jwtService.generateTokenFamily();
+        // Generate temporary tokens first (session creation requires token hashes)
+        // Note: deviceId not included in token - session.deviceId is source of truth
         const tempTokens = await this.jwtService.generateTokenPair({
-            userId: user.sub,
+            userId: user.sub, // Use sub in JWT payload (external identifier)
             email: user.email,
-            sessionId: 'temp',
+            sessionId: 'temp', // Temporary - will be regenerated with real sessionId
             tokenFamily,
         });
+        // Generate deviceId if not provided
         let finalDeviceId = finalDeviceToken;
         if (!finalDeviceId) {
             const crypto = await Promise.resolve().then(() => __importStar(require('crypto')));
             finalDeviceId = crypto.randomUUID();
         }
+        // Create session
+        // Client info (ipAddress, ipCountry, ipCity, userAgent) automatically extracted from ClientInfoService
         const session = await this.sessionService.createSession({
-            userId: user.id,
+            userId: user.id, // Use internal id for foreign key
             accessTokenHash: this.jwtService.hashToken(tempTokens.accessToken),
             refreshTokenHash: this.jwtService.hashToken(tempTokens.refreshToken),
             tokenFamily,
             deviceId: finalDeviceId,
             expiresAt: this.sessionService.getSessionExpirationDate(),
-            authMethod: 'password',
+            authMethod: 'password', // Default to password for challenge flows (signup, verification completion)
         });
+        // Now regenerate tokens with the actual sessionId
+        // Note: deviceId not included in token - session.deviceId is source of truth
         const tokens = await this.jwtService.generateTokenPair({
             userId: user.sub,
             email: user.email,
             sessionId: session.id.toString(),
             tokenFamily,
         });
+        // Update session with new token hashes
         await this.sessionService.updateTokens(session.id, this.jwtService.hashToken(tokens.accessToken), this.jwtService.hashToken(tokens.refreshToken));
+        // Decode tokens to get expiry times
         const accessTokenValidation = await this.jwtService.validateAccessToken(tokens.accessToken);
         const refreshTokenValidation = await this.jwtService.validateRefreshToken(tokens.refreshToken);
         const response = {
@@ -343,6 +564,12 @@ class AuthChallengeHelperService {
             accessTokenExpiresAt: accessTokenValidation.payload?.exp || 0,
             refreshTokenExpiresAt: refreshTokenValidation.payload?.exp || 0,
             trusted: isTrusted,
+            // Expose deviceToken so that:
+            // - In cookies mode, CookieTokenInterceptor can set the httpOnly nauth_device_token cookie
+            // - In JSON mode, mobile clients can store it securely and send via header
+            // NOTE: finalDeviceToken is a logical device identifier derived from:
+            // - clientInfo.deviceToken (existing trusted device), OR
+            // - deviceToken parameter passed from AuthService / state machine
             deviceToken: finalDeviceToken,
             user: {
                 sub: user.sub,
@@ -359,9 +586,35 @@ class AuthChallengeHelperService {
         };
         return response;
     }
+    /**
+     * Determine and create appropriate auth response
+     *
+     * Main entry point that decides whether to return challenges or tokens.
+     * Uses state machine to evaluate authentication flow state.
+     *
+     * @param params - Authentication parameters
+     * @param params.user - User attempting authentication
+     * @param params.config - Auth configuration
+     * @param params.deviceToken - Device token (optional)
+     * @param params.isSocialLogin - Whether this is a social login (OAuth) authentication (optional)
+     * @param params.skipMFAVerification - Skip MFA verification flag (optional)
+     * @param params.authProvider - Social auth provider name (optional)
+     * @returns Auth response (either challenge or success)
+     *
+     * @example
+     * ```typescript
+     * const response = await challengeHelper.determineAuthResponse({
+     *   user,
+     *   config,
+     *   deviceToken: 'abc123',
+     *   isSocialLogin: false
+     * });
+     * ```
+     */
     async determineAuthResponse(params) {
         const { user, config, deviceToken, isSocialLogin = false, skipMFAVerification = false, authProvider } = params;
         this.logger?.debug?.(`[ChallengeHelper] determineAuthResponse called for user ${user.sub} (isSocialLogin=${isSocialLogin}, skipMFA=${skipMFAVerification}, deviceToken=${deviceToken ? 'present' : 'none'})`);
+        // Build context with pre-computed values
         const context = await this.contextBuilder.build({
             user,
             config,
@@ -370,33 +623,57 @@ class AuthChallengeHelperService {
             deviceToken,
             skipMFAVerification,
         });
+        // Evaluate state using state machine
         const state = await this.stateMachine.evaluateState(context);
+        // Get state definition
         const stateDefinition = this.stateMachine.getStateDefinition(state);
         if (!stateDefinition) {
             this.logger?.error?.(`No state definition found for state: ${state}`, { state, userId: user.id });
             throw new nauth_exception_1.NAuthException(error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR, 'Invalid authentication state');
         }
+        // Build metadata if available
         const metadata = this.stateMachine.buildMetadata(state, context);
+        // Convert state to response
         const response = await this.stateToResponse(state, stateDefinition, context, metadata);
         this.logger?.debug?.(`[ChallengeHelper] State ${state} → Challenge: ${response.challengeName || 'SUCCESS'} for user ${user.sub}`);
         return response;
     }
+    /**
+     * Convert state to authentication response
+     *
+     * Maps state to appropriate response (challenge or success).
+     * Merges state metadata into response.
+     *
+     * @param state - Authentication flow state
+     * @param stateDefinition - State definition
+     * @param context - Authentication flow context
+     * @param metadata - Response metadata (optional)
+     * @returns Authentication response
+     */
     async stateToResponse(state, stateDefinition, context, metadata) {
+        // Get client info from ClientInfoService
         const clientInfo = this.clientInfoService.get();
         const deviceToken = clientInfo.deviceToken || context.deviceToken;
         const authMethod = context.authMethod || 'password';
+        // Handle challenge states
         if (stateDefinition.challenge) {
+            // Handle MFA_SETUP_REQUIRED challenge specially
             if (stateDefinition.challenge === auth_challenge_dto_1.AuthChallenge.MFA_SETUP_REQUIRED) {
                 return this.createMFASetupChallengeResponse(context.user, context.config, authMethod, context.authProvider);
             }
+            // Handle MFA_REQUIRED challenge specially - needs preferred method logic
             if (stateDefinition.challenge === auth_challenge_dto_1.AuthChallenge.MFA_REQUIRED) {
                 return this.createMFAChallengeResponse(context.user);
             }
+            // Handle other challenges
             return this.createChallengeResponse(context.user, stateDefinition.challenge, context.config, authMethod, context.authProvider);
         }
+        // Handle special states
         if (state === auth_flow_state_machine_types_1.AuthFlowState.GRACE_PERIOD_ACTIVE) {
+            // Grace period active - return success with metadata
             const isTrusted = context.computed.isDeviceTrusted;
             const response = await this.createSuccessResponse(context.user, deviceToken, isTrusted, context.authMethod === 'social', metadata);
+            // Merge metadata
             if (metadata?.gracePeriodEndsAt) {
                 response.gracePeriodEndsAt = metadata.gracePeriodEndsAt;
             }
@@ -409,6 +686,7 @@ class AuthChallengeHelperService {
             return response;
         }
         if (state === auth_flow_state_machine_types_1.AuthFlowState.BLOCKED) {
+            // User is blocked - throw exception with metadata
             const errorCode = context.config.mfa?.adaptive?.blockedSignIn?.errorCode ||
                 error_codes_enum_1.AuthErrorCode.SIGNIN_BLOCKED_HIGH_RISK;
             const message = metadata?.reason ||
@@ -418,6 +696,7 @@ class AuthChallengeHelperService {
                 expiresAt: metadata?.blockedUntil,
             });
         }
+        // AUTHENTICATED state - return success
         const isTrusted = context.computed.isDeviceTrusted;
         return this.createSuccessResponse(context.user, deviceToken, isTrusted, context.authMethod === 'social', metadata);
     }