@nauth-toolkit/core 0.1.14 → 0.1.17

package/dist/services/challenge.service.d.ts

@@ -6,27 +6,281 @@ import { NAuthLogger } from '../utils/nauth-logger';
 import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
 import { ClientInfoService } from './client-info.service';
 import { NAuthConfig } from '../interfaces/config.interface';
+/**
+ * Challenge Session Service
+ *
+ * Manages authentication challenge sessions for the challenge-response flow.
+ * Challenge sessions are temporary, short-lived sessions (typically 15 minutes)
+ * that track pending authentication challenges similar to AWS Cognito.
+ *
+ * Handles:
+ * - Challenge session creation and validation
+ * - Session expiration and cleanup
+ * - Attempt tracking and rate limiting
+ * - Secure session token generation
+ *
+ * @example
+ * ```typescript
+ * // Create a challenge session
+ * const session = await challengeService.createChallengeSession(
+ *   user,
+ *   AuthChallenge.VERIFY_EMAIL,
+ *   { email: user.email }
+ * );
+ *
+ * // Validate and consume a challenge session
+ * const validSession = await challengeService.validateAndConsumeSession(
+ *   sessionToken,
+ *   AuthChallenge.VERIFY_EMAIL
+ * );
+ * ```
+ */
 export declare class ChallengeService {
     private readonly challengeSessionRepository;
     private readonly clientInfoService;
     private readonly logger;
     private readonly auditService?;
     private readonly config?;
+    /**
+     * Default challenge session expiration time (15 minutes)
+     */
     private readonly DEFAULT_EXPIRATION_MINUTES;
+    /**
+     * Default maximum attempts per challenge session
+     */
     private readonly DEFAULT_MAX_ATTEMPTS;
-    constructor(challengeSessionRepository: Repository<BaseChallengeSession>, clientInfoService: ClientInfoService, logger: NAuthLogger, auditService?: AuthAuditService | undefined, config?: NAuthConfig | undefined);
+    constructor(challengeSessionRepository: Repository<BaseChallengeSession>, clientInfoService: ClientInfoService, logger: NAuthLogger, auditService?: AuthAuditService | undefined, // Optional - audit trail service (enabled via config.auditLogs.enabled)
+    config?: NAuthConfig | undefined);
+    /**
+     * Per-user cleanup throttle map to avoid frequent cleanup writes
+     */
     private readonly lastCleanupByUserId;
+    /**
+     * Create a new challenge session
+     *
+     * Generates a unique session token and stores challenge metadata.
+     * The session token is returned to the client and must be submitted
+     * when responding to the challenge.
+     *
+     * **Deduplication:**
+     * If an active (non-completed, non-expired) session already exists for the same user
+     * and challenge type, this method returns the existing session instead of creating
+     * a duplicate. This prevents:
+     * - Excessive `CHALLENGE_CREATED` audit events
+     * - Database bloat from duplicate sessions
+     * - User confusion from multiple active sessions for the same challenge
+     *
+     * @param user - User the challenge session belongs to
+     * @param challengeName - Type of challenge (VERIFY_EMAIL, VERIFY_PHONE, etc.)
+     * @param metadata - Challenge-specific data
+     * @returns Challenge session with session token (new or existing)
+     * @remarks Client info (ipAddress, userAgent) is automatically extracted from ClientInfoService context
+     *
+     * @example
+     * ```typescript
+     * const session = await challengeService.createChallengeSession(
+     *   user,
+     *   AuthChallenge.VERIFY_EMAIL,
+     *   { email: user.email, verificationTokenId: tokenId }
+     * );
+     * // Returns: { sessionToken: 'uuid-here', expiresAt: Date, ... }
+     * // If called again before completion, returns same session (no duplicate audit event)
+     * ```
+     */
     createChallengeSession(user: IUser, challengeName: AuthChallenge, metadata?: Record<string, unknown>): Promise<IChallengeSession>;
+    /**
+     * Validate a challenge session token for code requests
+     *
+     * Validates session for requesting new verification codes (SMS, email, etc.).
+     * Skips max attempts check since requesting a new code is not a verification attempt.
+     * This method is used internally by nauth when sending verification codes.
+     *
+     * @param sessionToken - Session token to validate
+     * @param expectedChallenge - Expected challenge type (optional, for additional verification)
+     * @returns Valid challenge session
+     * @throws {UnauthorizedException} If session is invalid, expired, or already completed
+     *
+     * @example
+     * ```typescript
+     * // Used internally by nauth when sending verification codes
+     * const session = await challengeService.validateSessionForCodeRequest(
+     *   'session-token-123',
+     *   AuthChallenge.MFA_REQUIRED
+     * );
+     * ```
+     */
     validateSessionForCodeRequest(sessionToken: string, expectedChallenge?: AuthChallenge): Promise<IChallengeSession>;
+    /**
+     * Validate a challenge session token
+     *
+     * Checks if the session token is valid, not expired, not completed,
+     * and matches the expected challenge type. Does NOT consume the session.
+     * Enforces max attempts check for verification attempts.
+     *
+     * @param sessionToken - Session token to validate
+     * @param expectedChallenge - Expected challenge type (optional, for additional verification)
+     * @returns Valid challenge session
+     * @throws {UnauthorizedException} If session is invalid, expired, or already completed
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const session = await challengeService.validateSession(
+     *     'session-token-123',
+     *     AuthChallenge.VERIFY_EMAIL
+     *   );
+     *   // Session is valid, proceed with verification
+     * } catch (error) {
+     *   // Session is invalid
+     * }
+     * ```
+     */
     validateSession(sessionToken: string, expectedChallenge?: AuthChallenge): Promise<IChallengeSession>;
+    /**
+     * Internal method to validate challenge session
+     *
+     * @param sessionToken - Session token to validate
+     * @param expectedChallenge - Expected challenge type (optional)
+     * @param skipMaxAttemptsCheck - If true, skip max attempts check (for code requests)
+     * @returns Valid challenge session
+     * @private
+     */
     private validateSessionInternal;
+    /**
+     * Increment attempt counter for a challenge session
+     *
+     * Tracks failed attempts to complete a challenge.
+     * Used to prevent brute-force attacks on verification codes.
+     *
+     * @param session - Challenge session to increment
+     * @returns Updated session
+     *
+     * @example
+     * ```typescript
+     * await challengeService.incrementAttempts(session);
+     * ```
+     */
     incrementAttempts(session: IChallengeSession): Promise<IChallengeSession>;
+    /**
+     * Validate and consume a challenge session
+     *
+     * Validates the session and marks it as completed if validation succeeds.
+     * This method should be called only after successful challenge completion.
+     *
+     * @param sessionToken - Session token to validate and consume
+     * @param expectedChallenge - Expected challenge type
+     * @returns Valid, completed challenge session with user
+     * @throws {UnauthorizedException} If session is invalid
+     *
+     * @example
+     * ```typescript
+     * const session = await challengeService.validateAndConsumeSession(
+     *   'session-token-123',
+     *   AuthChallenge.VERIFY_EMAIL
+     * );
+     * // Session is now marked complete and cannot be reused
+     * ```
+     */
     validateAndConsumeSession(sessionToken: string, expectedChallenge: AuthChallenge): Promise<IChallengeSession>;
+    /**
+     * Update challenge session metadata
+     *
+     * Updates the metadata field of an existing challenge session.
+     * Used to store additional challenge-specific data (e.g., passkey challenge).
+     *
+     * @param sessionToken - Session token to update
+     * @param metadata - Metadata to merge into existing metadata
+     * @returns Updated challenge session
+     * @throws {NAuthException} If session not found or invalid
+     *
+     * @example
+     * ```typescript
+     * await challengeService.updateMetadata('session-token-123', {
+     *   passkeyChallenge: 'base64-challenge-string'
+     * });
+     * ```
+     */
     updateMetadata(sessionToken: string, metadata: Record<string, unknown>): Promise<IChallengeSession>;
+    /**
+     * Clean up expired or completed challenge sessions for a user
+     *
+     * Removes old sessions to prevent database bloat.
+     * Called automatically when creating new challenge sessions.
+     *
+     * @param userId - User ID to clean up sessions for
+     *
+     * @example
+     * ```typescript
+     * await challengeService.cleanupExpiredSessions(user.id);
+     * ```
+     */
     cleanupExpiredSessions(userId: number): Promise<void>;
+    /**
+     * Clean up all expired challenge sessions (for all users)
+     *
+     * Should be called periodically (e.g., via cron job) to maintain
+     * database health.
+     *
+     * @returns Number of sessions deleted
+     *
+     * @example
+     * ```typescript
+     * // In a scheduled job
+     * const deleted = await challengeService.cleanupAllExpiredSessions();
+     * logger.log(`Cleaned up ${deleted} expired challenge sessions`);
+     * ```
+     */
     cleanupAllExpiredSessions(): Promise<number>;
+    /**
+     * Delete challenge sessions by challenge name for a user
+     *
+     * Removes all active (not completed, not expired) challenge sessions
+     * of the specified type for a user. Used to clean up phantom challenges
+     * when user completes the requirement (e.g., sets up MFA).
+     *
+     * @param userId - Internal user ID
+     * @param challengeName - Challenge type to delete
+     * @returns Number of sessions deleted
+     *
+     * @example
+     * ```typescript
+     * // Clear MFA_SETUP_REQUIRED challenge when user sets up MFA
+     * const deleted = await challengeService.deleteUserChallengeSessions(
+     *   user.id,
+     *   AuthChallenge.MFA_SETUP_REQUIRED
+     * );
+     * ```
+     */
     deleteUserChallengeSessions(userId: number, challengeName: AuthChallenge): Promise<number>;
+    /**
+     * Mask email address for display in challenge parameters
+     *
+     * Shows first character and domain, hides the rest.
+     *
+     * @param email - Email to mask
+     * @returns Masked email
+     *
+     * @example
+     * ```typescript
+     * maskEmail('john.doe@example.com')
+     * // Returns: 'j***@example.com'
+     * ```
+     */
     maskEmail(email: string): string;
+    /**
+     * Mask phone number for display in challenge parameters
+     *
+     * Shows last 4 digits, hides the rest.
+     *
+     * @param phone - Phone to mask
+     * @returns Masked phone
+     *
+     * @example
+     * ```typescript
+     * maskPhone('+1234567890')
+     * // Returns: '***-***-7890'
+     * ```
+     */
     maskPhone(phone: string): string;
 }
 //# sourceMappingURL=challenge.service.d.ts.map

package/dist/services/challenge.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"challenge.service.d.ts","sourceRoot":"","sources":["../../src/services/challenge.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAY,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,wBAAwB,IAAI,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAIpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AA+B7D,qBAAa,gBAAgB;IAYzB,OAAO,CAAC,QAAQ,CAAC,0BAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAZ1B,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAM;IAKjD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAK;gBAGvB,0BAA0B,EAAE,UAAU,CAAC,oBAAoB,CAAC,EAC5D,iBAAiB,EAAE,iBAAiB,EACpC,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,gBAAgB,YAAA,EAC/B,MAAM,CAAC,EAAE,WAAW,YAAA;IAMvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IAsChE,sBAAsB,CAC1B,IAAI,EAAE,KAAK,EACX,aAAa,EAAE,aAAa,EAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,iBAAiB,CAAC;IAqKvB,6BAA6B,CACjC,YAAY,EAAE,MAAM,EACpB,iBAAiB,CAAC,EAAE,aAAa,GAChC,OAAO,CAAC,iBAAiB,CAAC;IA6BvB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAa5F,uBAAuB;IA8D/B,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsFzE,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwE7G,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2CnG,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BrD,yBAAyB,IAAI,OAAO,CAAC,MAAM,CAAC;IA+B5C,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAiChG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAoBhC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAKjC"}
+{"version":3,"file":"challenge.service.d.ts","sourceRoot":"","sources":["../../src/services/challenge.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAY,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,wBAAwB,IAAI,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAIpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAgB;IAYzB,OAAO,CAAC,QAAQ,CAAC,0BAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAf1B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAM;IAEjD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAK;gBAGvB,0BAA0B,EAAE,UAAU,CAAC,oBAAoB,CAAC,EAC5D,iBAAiB,EAAE,iBAAiB,EACpC,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,gBAAgB,YAAA,EAAE,wEAAwE;IACzG,MAAM,CAAC,EAAE,WAAW,YAAA;IAGvC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IAMtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,sBAAsB,CAC1B,IAAI,EAAE,KAAK,EACX,aAAa,EAAE,aAAa,EAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,iBAAiB,CAAC;IAgJ7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,6BAA6B,CACjC,YAAY,EAAE,MAAM,EACpB,iBAAiB,CAAC,EAAE,aAAa,GAChC,OAAO,CAAC,iBAAiB,CAAC;IAI7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI1G;;;;;;;;OAQG;YACW,uBAAuB;IAgDrC;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkE/E;;;;;;;;;;;;;;;;;;;OAmBG;IACG,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsDnH;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA8BzG;;;;;;;;;;;;OAYG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3D;;;;;;;;;;;;;;OAcG;IACG,yBAAyB,IAAI,OAAO,CAAC,MAAM,CAAC;IAWlD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBhG;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMhC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAKjC"}