@nauth-toolkit/core 0.1.0

package/src/services/mfa-base.service.ts

@@ -0,0 +1,611 @@
+import { Repository } from 'typeorm';
+import { BaseMFADevice, BaseUser } from '../entities';
+import { randomBytes } from 'crypto';
+import { IUser, IMFADevice } from '../interfaces/entities.interface';
+import { NAuthConfig } from '../interfaces/config.interface';
+import { NAuthLogger } from '../utils/nauth-logger';
+import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
+import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+import { ClientInfoService } from './client-info.service';
+import { NAuthException } from '../exceptions/nauth.exception';
+import { AuthErrorCode } from '../enums/error-codes.enum';
+import { IMFAProviderService } from '../interfaces/mfa-provider.interface';
+import { MFADeviceMethod, MFADeviceMethods } from '../enums/mfa-method.enum';
+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 abstract class BaseMFAProviderService implements IMFAProviderService {
+  abstract readonly methodName: string;
+
+  constructor(
+    protected readonly mfaDeviceRepository: Repository<BaseMFADevice>,
+    protected readonly userRepository: Repository<BaseUser>,
+    protected readonly config: NAuthConfig,
+    protected readonly logger: NAuthLogger,
+    protected readonly passwordService?: unknown, // Optional - from @nauth-toolkit/core
+    protected readonly challengeService?: ChallengeService,
+    protected readonly auditService?: AuthAuditService,
+    protected readonly clientInfoService?: ClientInfoService,
+  ) {}
+
+  /**
+   * Check if this MFA method is allowed by configuration
+   *
+   * @returns True if method is allowed
+   */
+  isMethodAllowed(): boolean {
+    const allowedMethods = this.config.mfa?.allowedMethods || [...MFADeviceMethods];
+    return allowedMethods.includes(this.methodName as MFADeviceMethod);
+  }
+
+  // Abstract methods to be implemented by providers
+  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>;
+  // sendChallenge is optional - only providers like SMS need it
+  // TOTP doesn't need it (user generates code locally)
+
+  // ============================================================================
+  // Device Management (Common Logic)
+  // ============================================================================
+
+  /**
+   * Get user's MFA devices
+   *
+   * @param userId - Internal user ID
+   * @returns Array of MFA devices
+   *
+   * @protected
+   */
+  protected async getUserDevices(userId: number): Promise<IMFADevice[]> {
+    const devices = await this.mfaDeviceRepository.find({
+      where: { userId },
+      order: { isPrimary: 'DESC', createdAt: 'DESC' },
+    } as Record<string, unknown>);
+
+    return devices as unknown as 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 async createDevice(userId: number, deviceData: Partial<IMFADevice>): Promise<IMFADevice> {
+    // ============================================================================
+    // Transaction-Safe Device Creation with Race Condition Prevention
+    // ============================================================================
+    // Use TypeORM transaction manager to ensure atomicity across all database adapters
+    // Pessimistic write lock prevents concurrent MFA device creation for same user
+    const device = await this.userRepository.manager.transaction(async (transactionalEntityManager) => {
+      // Step 1: Lock user row to prevent concurrent MFA setup
+      // This works across MySQL and PostgreSQL (TypeORM translates to FOR UPDATE)
+      await transactionalEntityManager
+        .createQueryBuilder()
+        .select('user.id')
+        .from(this.userRepository.target, 'user')
+        .where('user.id = :userId', { userId })
+        .setLock('pessimistic_write')
+        .getOne();
+
+      // Step 2: Check for existing device of this type (within transaction)
+      // This prevents duplicates even if called concurrently
+      const existingDevice = await transactionalEntityManager
+        .getRepository(this.mfaDeviceRepository.target)
+        .createQueryBuilder('device')
+        .where('device.userId = :userId', { userId })
+        .andWhere('device.type = :type', { type: this.methodName })
+        .getOne();
+
+      if (existingDevice) {
+        this.logger?.log?.(
+          `MFA device of type '${this.methodName}' already exists for user ${userId}, returning existing device`,
+        );
+        return existingDevice as unknown as IMFADevice;
+      }
+
+      // Step 3: Create new device (no duplicate exists)
+      const newDevice = transactionalEntityManager.getRepository(this.mfaDeviceRepository.target).create({
+        userId,
+        type: this.methodName,
+        ...deviceData,
+      } as Record<string, unknown>);
+
+      // Step 4: Save device (unique constraint provides final safety net)
+      const saved = await transactionalEntityManager.getRepository(this.mfaDeviceRepository.target).save(newDevice);
+
+      this.logger?.log?.(`Created new MFA device: type='${this.methodName}', userId=${userId}, deviceId=${saved.id}`);
+
+      return saved as unknown as IMFADevice;
+    });
+
+    // ============================================================================
+    // Audit: Record MFA device added
+    // ============================================================================
+    if (this.auditService && this.clientInfoService) {
+      try {
+        await this.auditService.recordEvent({
+          userId,
+          eventType: AuthAuditEventType.MFA_DEVICE_ADDED,
+          eventStatus: 'SUCCESS',
+          metadata: {
+            // Client info automatically included from context
+            mfaMethod: this.methodName,
+            deviceId: device.id,
+            deviceName: device.name,
+            isPrimary: device.isPrimary,
+          },
+        });
+      } catch (auditError) {
+        // Non-blocking: Log but continue
+        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+        this.logger?.error?.(`Failed to record MFA_DEVICE_ADDED audit event: ${errorMessage}`, {
+          error: auditError,
+          userId,
+          methodName: this.methodName,
+        });
+      }
+    }
+
+    return device;
+  }
+
+  /**
+   * 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 async findDevice(userId: number, deviceId?: number): Promise<IMFADevice | null> {
+    const where: Record<string, unknown> = {
+      userId,
+      type: this.methodName,
+      isActive: true,
+    };
+
+    if (deviceId) {
+      where.id = deviceId;
+    }
+
+    const device = await this.mfaDeviceRepository.findOne({
+      where,
+      order: { isPrimary: 'DESC', lastUsedAt: 'DESC' },
+    } as Record<string, unknown>);
+
+    return device ? (device as unknown as IMFADevice) : null;
+  }
+
+  /**
+   * Update device usage statistics
+   *
+   * @param deviceId - Device ID
+   * @protected
+   */
+  protected async updateDeviceUsage(deviceId: number): Promise<void> {
+    const device = await this.mfaDeviceRepository.findOne({ where: { id: deviceId } });
+    if (device) {
+      device.lastUsedAt = new Date();
+      device.usageCount = (device.usageCount || 0) + 1;
+      await this.mfaDeviceRepository.save(device);
+    }
+  }
+
+  /**
+   * 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 async enableMFAForUser(user: IUser): Promise<void> {
+    // Reload user from database to ensure we have the latest state
+    // This prevents overwriting fields like isPhoneVerified that may have been updated
+    // between when the user object was loaded and when MFA is enabled
+    const userId = (user as unknown as Record<string, unknown>).id as number;
+    const userEntity = await this.userRepository.findOne({ where: { id: userId } });
+    if (!userEntity) {
+      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found when enabling MFA');
+    }
+
+    const userEntityRecord = userEntity as unknown as Record<string, unknown>;
+    const isFirstDevice = !userEntityRecord.mfaEnabled;
+
+    if (!userEntityRecord.mfaEnabled) {
+      userEntityRecord.mfaEnabled = true;
+      userEntityRecord.mfaEnforcedAt = new Date();
+    }
+
+    // Update mfaMethods array
+    const devices = await this.getUserDevices(userId);
+    const methods = [...new Set(devices.filter((d) => d.isActive).map((d) => d.type))];
+    userEntityRecord.mfaMethods = methods;
+
+    // Set preferred method if not set
+    if (!userEntityRecord.preferredMfaMethod && methods.length > 0) {
+      const primaryDevice = devices.find((d) => d.isPrimary && d.isActive);
+      userEntityRecord.preferredMfaMethod = primaryDevice?.type || methods[0];
+    }
+
+    await this.userRepository.save(userEntity);
+
+    // If this is the first MFA device being set up, clear any MFA_SETUP_REQUIRED challenges
+    // This prevents phantom challenges when user sets up MFA while logged in
+    // if (isFirstDevice && this.challengeService) {
+    //   try {
+    //     await this.challengeService.deleteUserChallengeSessions(userId, AuthChallenge.MFA_SETUP_REQUIRED);
+    //     this.logger?.log?.(`Cleared MFA_SETUP_REQUIRED challenge for user ${user.sub} after MFA setup`);
+    //   } catch (error) {
+    //     // Log but don't fail MFA setup if challenge clearing fails
+    //     this.logger?.warn?.(`Failed to clear MFA_SETUP_REQUIRED challenge after MFA setup: ${error}`);
+    //   }
+    // }
+
+    // ============================================================================
+    // Audit: Record MFA enabled (only for first device)
+    // ============================================================================
+    if (isFirstDevice && this.auditService && this.clientInfoService) {
+      try {
+        await this.auditService?.recordEvent({
+          userId: user.id,
+          eventType: AuthAuditEventType.MFA_ENABLED,
+          eventStatus: 'SUCCESS',
+          metadata: {
+            // Client info automatically included from context
+            mfaMethod: this.methodName,
+            mfaMethods: methods,
+          },
+        });
+      } catch (auditError) {
+        // Non-blocking: Log but continue
+        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+        this.logger?.error?.(`Failed to record MFA_ENABLED audit event: ${errorMessage}`, {
+          error: auditError,
+          userId: user.id,
+          methodName: this.methodName,
+        });
+      }
+    }
+  }
+
+  // ============================================================================
+  // Backup Codes (Common Logic)
+  // ============================================================================
+
+  /**
+   * 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)
+   */
+  async generateBackupCodes(user: IUser): Promise<string[]> {
+    const userEntity = user as unknown as Record<string, unknown>;
+    const config = this.config.mfa?.backup;
+    const codeCount = config?.codeCount || 10;
+    const codeLength = config?.codeLength || 8;
+
+    // Generate random codes
+    const codes: string[] = [];
+    for (let i = 0; i < codeCount; i++) {
+      const code = this.generateRandomCode(codeLength);
+      codes.push(code);
+    }
+
+    // Check if password service is available
+    if (!this.passwordService || typeof (this.passwordService as Record<string, unknown>).hashPassword !== 'function') {
+      throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'Password service is not available');
+    }
+
+    // Hash codes for storage
+    const passwordService = this.passwordService as { hashPassword: (password: string) => Promise<string> };
+    const hashedCodes = await Promise.all(codes.map((code) => passwordService.hashPassword(code)));
+
+    // Store hashed codes
+    userEntity.backupCodes = hashedCodes;
+    await this.userRepository.save(userEntity);
+
+    this.logger?.log?.(`Generated ${codeCount} backup codes for user: ${user.sub}`);
+
+    // ============================================================================
+    // Audit: Record backup codes generation
+    // ============================================================================
+    if (this.auditService && this.clientInfoService) {
+      try {
+        await this.auditService?.recordEvent({
+          userId: user.id,
+          eventType: AuthAuditEventType.MFA_BACKUP_CODES_GENERATED,
+          eventStatus: 'INFO',
+          metadata: {
+            // Client info automatically included from context
+            codeCount,
+            codeLength,
+          },
+        });
+      } catch (auditError) {
+        // Non-blocking: Log but continue
+        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+        this.logger?.error?.(`Failed to record MFA_BACKUP_CODES_GENERATED audit event: ${errorMessage}`, {
+          error: auditError,
+          userId: user.id,
+        });
+      }
+    }
+
+    return codes;
+  }
+
+  /**
+   * 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 async verifyBackupCode(user: IUser, code: string): Promise<boolean> {
+    const userEntity = user as unknown as Record<string, unknown>;
+
+    const backupCodes = userEntity.backupCodes as string[] | undefined;
+    if (!backupCodes || backupCodes.length === 0) {
+      this.logger?.warn?.('No backup codes available');
+      return false;
+    }
+
+    // Check if password service is available
+    if (
+      !this.passwordService ||
+      typeof (this.passwordService as Record<string, unknown>).verifyPassword !== 'function'
+    ) {
+      this.logger?.warn?.('Backup code verification attempted but password service is not available');
+      return false;
+    }
+
+    // Check code against all stored hashed codes
+    const passwordService = this.passwordService as {
+      verifyPassword: (plain: string, hash: string) => Promise<boolean>;
+    };
+    for (let i = 0; i < backupCodes.length; i++) {
+      const isValid = await passwordService.verifyPassword(code, backupCodes[i]);
+      if (isValid) {
+        // Remove used code
+        backupCodes.splice(i, 1);
+        userEntity.backupCodes = backupCodes;
+        await this.userRepository.save(userEntity);
+
+        this.logger?.log?.(`Backup code verified and removed for user: ${user.sub}`);
+
+        // ============================================================================
+        // Audit: Record backup code usage
+        // ============================================================================
+        if (this.auditService && this.clientInfoService) {
+          try {
+            await this.auditService?.recordEvent({
+              userId: user.id,
+              eventType: AuthAuditEventType.MFA_BACKUP_CODE_USED,
+              eventStatus: 'SUCCESS',
+              authMethod: 'backup',
+              metadata: {
+                // Client info automatically included from context
+                remainingCodes: backupCodes.length,
+              },
+            });
+          } catch (auditError) {
+            // Non-blocking: Log but continue
+            const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+            this.logger?.error?.(`Failed to record MFA_BACKUP_CODE_USED audit event: ${errorMessage}`, {
+              error: auditError,
+              userId: user.id,
+            });
+          }
+        }
+
+        return true;
+      }
+    }
+
+    this.logger?.warn?.('Backup code verification failed');
+    return false;
+  }
+
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+
+  /**
+   * Generate random alphanumeric code
+   *
+   * @param length - Code length
+   * @returns Random code
+   * @protected
+   */
+  protected generateRandomCode(length: number): string {
+    const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Exclude ambiguous characters
+    let code = '';
+    const bytes = randomBytes(length);
+    for (let i = 0; i < length; i++) {
+      code += chars[bytes[i] % chars.length];
+    }
+    return code;
+  }
+
+  /**
+   * Mask phone number for display
+   *
+   * @param phone - Phone number
+   * @returns Masked phone number
+   * @protected
+   */
+  protected maskPhone(phone: string): string {
+    const digits = phone.replace(/\D/g, '');
+    if (digits.length < 4) return phone;
+    return `***-***-${digits.slice(-4)}`;
+  }
+
+  /**
+   * 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 {
+    const [localPart, domain] = email.split('@');
+    if (!localPart || !domain) return email;
+    if (localPart.length <= 2) {
+      return `${localPart[0]}***@${domain}`;
+    }
+    return `${localPart[0]}***${localPart[localPart.length - 1]}@${domain}`;
+  }
+
+  /**
+   * 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 async isMFARequired(user: IUser): Promise<boolean> {
+    // ============================================================================
+    // SECURITY: Check user-level MFA exemption FIRST
+    // ============================================================================
+    // Exemption allows bypassing MFA requirements
+    // This is checked early to ensure exempt users can always login
+    // Handle different database representations (boolean true, MySQL tinyint 1, etc.)
+    const mfaExempt = user.mfaExempt;
+    // Check for boolean true (handle numeric 1 case at runtime if needed)
+    if (mfaExempt === true || (mfaExempt as unknown) === 1) {
+      return false;
+    }
+
+    const mfaConfig = this.config.mfa;
+
+    if (!mfaConfig?.enabled) {
+      return false;
+    }
+
+    const enforcement = mfaConfig.enforcement || 'OPTIONAL';
+
+    if (enforcement === 'OPTIONAL') {
+      return false;
+    }
+
+    if (enforcement === 'REQUIRED' || enforcement === 'ADAPTIVE') {
+      // Check grace period
+      const gracePeriod = mfaConfig.gracePeriod || 7;
+      const gracePeriodEnd = new Date();
+      gracePeriodEnd.setDate(gracePeriodEnd.getDate() - gracePeriod);
+
+      // If user has enrolled in MFA, check if they're within grace period
+      const userWithDates = user as IUser & { mfaEnforcedAt?: Date; createdAt: Date };
+      if (userWithDates.mfaEnforcedAt) {
+        return userWithDates.mfaEnforcedAt <= gracePeriodEnd;
+      }
+
+      // User hasn't enrolled - check account creation date
+      if (userWithDates.createdAt) {
+        return userWithDates.createdAt <= gracePeriodEnd;
+      }
+
+      // No dates available - require MFA immediately
+      return true;
+    }
+
+    return false;
+  }
+}