@nauth-toolkit/core 0.1.13 → 0.1.17

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

@@ -7,6 +7,49 @@ import { InternalAuthAuditService as AuthAuditService } from './auth-audit.servi
 import { ClientInfoService } from './client-info.service';
 import { IMFAProviderService } from '../interfaces/mfa-provider.interface';
 import { ChallengeService } from './challenge.service';
+/**
+ * Base MFA Provider Service
+ *
+ * Abstract base class that provides common functionality for all MFA providers.
+ * Provider-specific services (TOTP, SMS, Passkey, etc.) should extend this class
+ * and implement the IMFAProviderService interface methods.
+ *
+ * This base class handles:
+ * - Device repository access
+ * - User repository access
+ * - Common device management operations
+ * - Backup codes generation and verification
+ * - MFA enforcement checks
+ * - Helper methods
+ *
+ * **Key Design:**
+ * - No hardcoded method names - works with any provider
+ * - Provider config accessed dynamically via `methodName`
+ * - Future developers can add new providers without modifying this class
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class TOTPMFAProviderService extends BaseMFAProviderService implements IMFAProviderService {
+ *   readonly methodName = 'totp';
+ *
+ *   constructor(
+ *     // ... base dependencies injected via super()
+ *     private readonly totpService: TOTPService,
+ *   ) {
+ *     super(/* ... base dependencies *\/);
+ *   }
+ *
+ *   async setup(user: IUser): Promise<unknown> {
+ *     // TOTP-specific setup logic
+ *   }
+ *
+ *   async verify(user: IUser, code: unknown): Promise<boolean> {
+ *     // TOTP verification logic
+ *   }
+ * }
+ * ```
+ */
 export declare abstract class BaseMFAProviderService implements IMFAProviderService {
     protected readonly mfaDeviceRepository: Repository<BaseMFADevice>;
     protected readonly userRepository: Repository<BaseUser>;
@@ -17,21 +60,156 @@ export declare abstract class BaseMFAProviderService implements IMFAProviderServ
     protected readonly auditService?: AuthAuditService | undefined;
     protected readonly clientInfoService?: ClientInfoService | undefined;
     abstract readonly methodName: string;
-    constructor(mfaDeviceRepository: Repository<BaseMFADevice>, userRepository: Repository<BaseUser>, config: NAuthConfig, logger: NAuthLogger, passwordService?: unknown | undefined, challengeService?: ChallengeService | undefined, auditService?: AuthAuditService | undefined, clientInfoService?: ClientInfoService | undefined);
+    constructor(mfaDeviceRepository: Repository<BaseMFADevice>, userRepository: Repository<BaseUser>, config: NAuthConfig, logger: NAuthLogger, passwordService?: unknown | undefined, // Optional - from @nauth-toolkit/core
+    challengeService?: ChallengeService | undefined, auditService?: AuthAuditService | undefined, clientInfoService?: ClientInfoService | undefined);
+    /**
+     * Check if this MFA method is allowed by configuration
+     *
+     * @returns True if method is allowed
+     */
     isMethodAllowed(): boolean;
     abstract setup(user: IUser, setupData?: unknown): Promise<unknown>;
     abstract verifySetup(user: IUser, verificationData: unknown, deviceName?: string): Promise<number>;
     abstract verify(user: IUser, code: unknown, deviceId?: number): Promise<boolean>;
+    /**
+     * Get user's MFA devices
+     *
+     * @param userId - Internal user ID
+     * @returns Array of MFA devices
+     *
+     * @protected
+     */
     protected getUserDevices(userId: number): Promise<IMFADevice[]>;
+    /**
+     * Create MFA device for user
+     *
+     * Creates a new MFA device with proper duplicate prevention and transaction safety.
+     * Uses database-level unique constraint (userId, type) to prevent race conditions.
+     *
+     * **Race Condition Prevention:**
+     * - Checks for existing device before creation
+     * - Wraps in transaction with pessimistic write lock on user row
+     * - Database unique constraint provides final safety net
+     *
+     * **Transaction Flow:**
+     * 1. Lock user row (prevents concurrent MFA setup)
+     * 2. Check for existing device of this type
+     * 3. Create device if none exists
+     * 4. Update user MFA flags
+     * 5. Commit transaction
+     *
+     * @param userId - Internal user ID
+     * @param deviceData - Device data to create
+     * @returns Created device (or existing device if already present)
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * const device = await this.createDevice(user.id, {
+     *   name: 'SMS Phone',
+     *   phoneNumber: '+1234567890',
+     *   isActive: true,
+     *   isPrimary: !user.mfaEnabled,
+     * });
+     * ```
+     */
     protected createDevice(userId: number, deviceData: Partial<IMFADevice>): Promise<IMFADevice>;
+    /**
+     * Find active device for user by method
+     *
+     * @param userId - Internal user ID
+     * @param deviceId - Optional device ID
+     * @returns Device if found, null otherwise
+     * @protected
+     */
     protected findDevice(userId: number, deviceId?: number): Promise<IMFADevice | null>;
+    /**
+     * Update device usage statistics
+     *
+     * @param deviceId - Device ID
+     * @protected
+     */
     protected updateDeviceUsage(deviceId: number): Promise<void>;
+    /**
+     * Enable MFA for user
+     *
+     * Sets mfaEnabled flag and updates mfaMethods array.
+     * Called automatically when first device is registered.
+     * Automatically clears MFA_SETUP_REQUIRED challenges if they exist.
+     *
+     * @param user - User to enable MFA for
+     * @protected
+     */
     protected enableMFAForUser(user: IUser): Promise<void>;
+    /**
+     * Generate backup codes for user
+     *
+     * Creates single-use recovery codes that can be used when MFA devices are unavailable.
+     * Exposed as optional method in IMFAProviderService interface.
+     *
+     * @param user - User to generate codes for
+     * @returns Generated backup codes (plain text - shown only once)
+     */
     generateBackupCodes(user: IUser): Promise<string[]>;
+    /**
+     * Verify backup code
+     *
+     * Validates backup code and removes it after use (single-use).
+     *
+     * @param user - User being authenticated
+     * @param code - Backup code to verify
+     * @returns True if code is valid
+     * @protected
+     */
     protected verifyBackupCode(user: IUser, code: string): Promise<boolean>;
+    /**
+     * Generate random alphanumeric code
+     *
+     * @param length - Code length
+     * @returns Random code
+     * @protected
+     */
     protected generateRandomCode(length: number): string;
+    /**
+     * Mask phone number for display
+     *
+     * @param phone - Phone number
+     * @returns Masked phone number
+     * @protected
+     */
     protected maskPhone(phone: string): string;
+    /**
+     * Mask email address for display
+     *
+     * Masks the local part of the email while showing the domain.
+     * Example: user@example.com → u***r@example.com
+     *
+     * @param email - Email address
+     * @returns Masked email address
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * const masked = this.maskEmail('user@example.com');
+     * // Returns: 'u***r@example.com'
+     * ```
+     */
     protected maskEmail(email: string): string;
+    /**
+     * Check if MFA is required for a user
+     *
+     * Determines MFA requirement based on:
+     * - User-level MFA exemption (admin override)
+     * - Global enforcement policy (OPTIONAL, REQUIRED, ADAPTIVE)
+     * - Grace period for REQUIRED enforcement
+     * - User's MFA enrollment date
+     *
+     * ADAPTIVE enforcement currently behaves like REQUIRED (placeholder for future risk-based logic)
+     *
+     * @param user - User to check
+     * @returns True if MFA is required
+     * @protected
+     */
     protected isMFARequired(user: IUser): Promise<boolean>;
 }
 //# sourceMappingURL=mfa-base.service.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mfa-base.service.d.ts","sourceRoot":"","sources":["../../src/services/mfa-base.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,wBAAwB,IAAI,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA6CvD,8BAAsB,sBAAuB,YAAW,mBAAmB;IAIvE,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE,UAAU,CAAC,aAAa,CAAC;IACjE,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC;IACvD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW;IACtC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW;IACtC,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO;IAC5C,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB;IACtD,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB;IAClD,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB;IAV1D,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAGhB,mBAAmB,EAAE,UAAU,CAAC,aAAa,CAAC,EAC9C,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,eAAe,CAAC,EAAE,OAAO,YAAA,EACzB,gBAAgB,CAAC,EAAE,gBAAgB,YAAA,EACnC,YAAY,CAAC,EAAE,gBAAgB,YAAA,EAC/B,iBAAiB,CAAC,EAAE,iBAAiB,YAAA;IAQ1D,eAAe,IAAI,OAAO;IAM1B,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAClE,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAClG,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;cAgBhE,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;cA0CrD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;cAuFlF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;cAyBzE,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cAmBlD,gBAAgB,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAmFtD,mBAAmB,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;cAkEzC,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4E7E,SAAS,CAAC,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAiBpD,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAsB1C,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;cAwB1B,aAAa,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;CAgD7D"}
+{"version":3,"file":"mfa-base.service.d.ts","sourceRoot":"","sources":["../../src/services/mfa-base.service.ts"],"names":[],"mappings":"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"}