@nauth-toolkit/core 0.1.14 → 0.1.17

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

@@ -7,6 +7,35 @@ import { NAuthLogger } from '../utils/nauth-logger';
 import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
 import { ClientInfoService } from './client-info.service';
 import { GetAvailableMethodsDTO, GetAvailableMethodsResponseDTO, GetChallengeDataDTO, GetChallengeDataResponseDTO, GetMFAStatusDTO, GetMFAStatusResponseDTO, GetSetupDataDTO, GetSetupDataResponseDTO, GetUserDevicesDTO, GetUserDevicesResponseDTO, HasProviderDTO, HasProviderResponseDTO, ListProvidersResponseDTO, RemoveDevicesDTO, RemoveDevicesResponseDTO, SetMFAExemptionDTO, SetMFAExemptionResponseDTO, SetPreferredMethodDTO, SetPreferredMethodResponseDTO, SetupMFADTO, SetupMFAResponseDTO, VerifyMFACodeDTO, VerifyMFACodeResponseDTO } from '../dto';
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
 export declare class MFAService {
     private readonly mfaDeviceRepository;
     private readonly userRepository;
@@ -17,19 +46,294 @@ export declare class MFAService {
     private readonly clientInfoService?;
     private readonly providers;
     constructor(mfaDeviceRepository: Repository<BaseMFADevice>, userRepository: Repository<BaseUser>, challengeService?: ChallengeService | undefined, config?: NAuthConfig | undefined, logger?: NAuthLogger | undefined, auditService?: AuthAuditService | undefined, clientInfoService?: ClientInfoService | undefined);
+    /**
+     * 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: IMFAProviderService): void;
+    /**
+     * 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: string): IMFAProviderService;
+    /**
+     * 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: HasProviderDTO): HasProviderResponseDTO;
+    /**
+     * 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(): ListProvidersResponseDTO;
+    /**
+     * 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'] }
+     * ```
+     */
     getAvailableMethods(dto: GetAvailableMethodsDTO): Promise<GetAvailableMethodsResponseDTO>;
+    /**
+     * 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'
+     * });
+     * ```
+     */
     verifyCode(dto: VerifyMFACodeDTO): Promise<VerifyMFACodeResponseDTO>;
+    /**
+     * 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 } }
+     * ```
+     */
     setup(dto: SetupMFADTO): Promise<SetupMFAResponseDTO>;
+    /**
+     * 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: [...] }
+     * ```
+     */
     getUserDevices(dto: GetUserDevicesDTO): Promise<GetUserDevicesResponseDTO>;
+    /**
+     * 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 });
+     * }
+     * ```
+     */
     getMFAStatus(dto: GetMFAStatusDTO): Promise<GetMFAStatusResponseDTO>;
+    /**
+     * 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 };
+     * }
+     * ```
+     */
     removeDevices(dto: RemoveDevicesDTO): Promise<RemoveDevicesResponseDTO>;
+    /**
+     * 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 });
+     * }
+     * ```
+     */
     setPreferredMethod(dto: SetPreferredMethodDTO): Promise<SetPreferredMethodResponseDTO>;
+    /**
+     * 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'
+     * });
+     * ```
+     */
     setMFAExemption(dto: SetMFAExemptionDTO): Promise<SetMFAExemptionResponseDTO>;
+    /**
+     * 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' } }
+     * ```
+     */
     getSetupData(dto: GetSetupDataDTO): Promise<GetSetupDataResponseDTO>;
+    /**
+     * 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: [...], ... } }
+     * ```
+     */
     getChallengeData(dto: GetChallengeDataDTO): Promise<GetChallengeDataResponseDTO>;
 }
 //# sourceMappingURL=mfa.service.d.ts.map

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

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