@nauth-toolkit/core 0.1.13 → 0.1.17

package/dist/services/auth-challenge-helper.service.d.ts

@@ -13,6 +13,22 @@ import { NAuthConfig } from '../interfaces/config.interface';
 import { NAuthLogger } from '../utils/nauth-logger';
 import { AuthFlowStateMachineService } from './auth-flow-state-machine.service';
 import { AuthFlowContextBuilder } from './auth-flow-context-builder.service';
+/**
+ * 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' }
+ * );
+ * ```
+ */
 export declare class AuthChallengeHelperService {
     private readonly challengeService;
     private readonly jwtService;
@@ -25,16 +41,131 @@ export declare class AuthChallengeHelperService {
     private readonly emailVerificationService?;
     private readonly phoneVerificationService?;
     constructor(challengeService: ChallengeService, jwtService: JwtService, sessionService: SessionService, mfaDeviceRepository: Repository<BaseMFADevice>, logger: NAuthLogger, stateMachine: AuthFlowStateMachineService, contextBuilder: AuthFlowContextBuilder, clientInfoService: ClientInfoService, emailVerificationService?: EmailVerificationService | undefined, phoneVerificationService?: PhoneVerificationService | undefined);
+    /**
+     * 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'
+     * );
+     * ```
+     */
     createChallengeResponse(user: IUser, challengeName: AuthChallenge, config: NAuthConfig, authMethod?: 'password' | 'social', authProvider?: string, skipAutoSend?: boolean): Promise<AuthResponseDTO>;
+    /**
+     * 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: {...} }
+     * ```
+     */
     createMFASetupChallengeResponse(user: IUser, config: NAuthConfig, authMethod?: 'password' | 'social', authProvider?: string): Promise<AuthResponseDTO>;
+    /**
+     * 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: {...} }
+     * ```
+     */
     createMFAChallengeResponse(user: IUser): Promise<AuthResponseDTO>;
-    createSuccessResponse(user: IUser, deviceToken?: string, isTrusted?: boolean, _isSocialLogin?: boolean, _metadata?: {
+    /**
+     * 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
+     * );
+     * ```
+     */
+    createSuccessResponse(user: IUser, deviceToken?: string, isTrusted?: boolean, _isSocialLogin?: boolean, // Reserved for future use
+    _metadata?: {
         gracePeriodEndsAt?: Date;
         riskScore?: number;
         riskLevel?: 'low' | 'medium' | 'high';
         blockedUntil?: Date;
         reason?: string;
     }): Promise<AuthResponseDTO>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     determineAuthResponse(params: {
         user: IUser;
         config: NAuthConfig;
@@ -43,6 +174,18 @@ export declare class AuthChallengeHelperService {
         skipMFAVerification?: boolean;
         authProvider?: string;
     }): Promise<AuthResponseDTO>;
+    /**
+     * 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
+     */
     private stateToResponse;
 }
 //# sourceMappingURL=auth-challenge-helper.service.d.ts.map

package/dist/services/auth-challenge-helper.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-challenge-helper.service.d.ts","sourceRoot":"","sources":["../../src/services/auth-challenge-helper.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-challenge-helper.service.d.ts","sourceRoot":"","sources":["../../src/services/auth-challenge-helper.service.ts"],"names":[],"mappings":"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"}