@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/services/adaptive-mfa-decision.service.ts

@@ -1,457 +0,0 @@
-import { IUser } from '../interfaces/entities.interface';
-import { StorageAdapter } from '../interfaces/storage-adapter.interface';
-import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
-import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
-import { RiskFactor } from '../enums/risk-factor.enum';
-import { RiskDetectionService } from './risk-detection.service';
-import { RiskScoringService } from './risk-scoring.service';
-import { ClientInfoService } from './client-info.service';
-import { ClientInfo } from '../interfaces/client-info.interface';
-import { NAuthConfig, AdaptiveMFARiskEventPayload, SignInBlockedPayload } from '../interfaces/config.interface';
-import { NAuthLogger } from '../utils/nauth-logger';
-
-/**
- * Adaptive MFA decision result
- */
-export interface AdaptiveMFADecision {
-  /**
-   * Action to take
-   */
-  action: 'allow' | 'require_mfa' | 'block_signin';
-
-  /**
-   * Risk score (0-100)
-   */
-  riskScore: number;
-
-  /**
-   * Risk level classification
-   */
-  riskLevel: 'low' | 'medium' | 'high';
-
-  /**
-   * Detected risk factors
-   * Array of RiskFactor enum values (stored as strings at runtime)
-   */
-  riskFactors: RiskFactor[];
-
-  /**
-   * Whether user should be notified
-   */
-  notifyUser: boolean;
-
-  /**
-   * Whether lifecycle hook overrode the decision
-   */
-  hookOverride: boolean;
-
-  /**
-   * Risk event payload (included when action requires it or notifyUser is true)
-   * Contains full client context for use in blockUserSignIn or audit logging
-   */
-  payload?: AdaptiveMFARiskEventPayload;
-}
-
-/**
- * Adaptive MFA Decision Service
- *
- * Makes context-aware MFA requirement decisions based on risk analysis.
- * Supports multiple actions (allow, require_mfa, block_signin) based on risk level.
- *
- * **Decision Flow:**
- * 1. Detect risk factors (via RiskDetectionService)
- * 2. Calculate risk score (via RiskScoringService)
- * 3. Determine risk level and action from configuration
- * 4. Call lifecycle hooks if notifyUser is true
- * 5. Record audit event (non-blocking)
- * 6. Return decision object
- *
- * **Default Risk Levels:**
- * - Low (0-20): action 'allow', notifyUser false
- * - Medium (21-50): action 'require_mfa', notifyUser true
- * - High (51-100): action 'require_mfa', notifyUser true (conservative default)
- *
- * **User Blocking:**
- * When action is 'block_signin', user is blocked in storage adapter with optional TTL.
- * Block status is checked before evaluation to prevent blocked users from attempting sign-in.
- *
- * @example
- * ```typescript
- * const decision = await adaptiveMFADecisionService.evaluateAdaptiveMFA(user, 'password');
- * if (decision.action === 'block_signin') {
- *   throw new NAuthException(AuthErrorCode.SIGNIN_BLOCKED_HIGH_RISK, 'Sign-in blocked');
- * }
- * return decision.action === 'require_mfa';
- * ```
- */
-export class AdaptiveMFADecisionService {
-  /**
-   * Default risk level configuration
-   *
-   * Conservative defaults that prioritize security:
-   * - Low risk: Allow without MFA (normal flow)
-   * - Medium risk: Require MFA
-   * - High risk: Require MFA (conservative - don't block by default)
-   */
-  private readonly defaultRiskLevels: {
-    low: { maxScore: number; action?: 'allow' | 'require_mfa' | 'block_signin'; notifyUser?: boolean };
-    medium: { maxScore: number; action?: 'allow' | 'require_mfa' | 'block_signin'; notifyUser?: boolean };
-    high: { maxScore: number; action?: 'allow' | 'require_mfa' | 'block_signin'; notifyUser?: boolean };
-  } = {
-    low: {
-      maxScore: 20,
-      action: 'allow',
-      notifyUser: false,
-    },
-    medium: {
-      maxScore: 50,
-      action: 'require_mfa',
-      notifyUser: true,
-    },
-    high: {
-      maxScore: 100,
-      action: 'require_mfa', // Conservative default (don't block)
-      notifyUser: true,
-    },
-  };
-
-  constructor(
-    private readonly riskDetectionService: RiskDetectionService,
-    private readonly riskScoringService: RiskScoringService,
-    private readonly storageAdapter: StorageAdapter,
-    private readonly clientInfoService: ClientInfoService,
-    private readonly config: NAuthConfig,
-    private readonly logger: NAuthLogger,
-    private readonly auditService?: AuthAuditService, // Optional - audit trail service (enabled via config.auditLogs.enabled)
-  ) {}
-
-  /**
-   * Evaluate adaptive MFA requirement with risk-based actions
-   *
-   * Main entry point for adaptive MFA evaluation. Analyzes current login context,
-   * calculates risk score, determines action, and calls lifecycle hooks.
-   *
-   * @param user - User being authenticated
-   * @param authMethod - Authentication method ('password', 'google', 'apple', etc.)
-   * @returns Decision object with action, risk details, and hook override status
-   *
-   * @example
-   * ```typescript
-   * const decision = await adaptiveMFADecisionService.evaluateAdaptiveMFA(user, 'password');
-   * if (decision.action === 'block_signin') {
-   *   // Handle blocking
-   * }
-   * ```
-   */
-  async evaluateAdaptiveMFA(user: IUser, authMethod: string): Promise<AdaptiveMFADecision> {
-    // Validate email is present (required by IUser interface but runtime check for safety)
-    if (!user.email) {
-      this.logger?.error?.(`User ${user.sub} missing email - cannot evaluate adaptive MFA`, {
-        userId: user.id,
-        userSub: user.sub,
-      });
-      throw new Error(`User email is required for adaptive MFA evaluation`);
-    }
-
-    // Get current client context
-    const clientInfo: ClientInfo = this.clientInfoService.get();
-
-    // Detect risk factors
-    const riskFactors = await this.riskDetectionService.detectRiskFactors(user, clientInfo);
-
-    // Calculate risk score
-    const riskScore = this.riskScoringService.calculateRiskScore(riskFactors);
-
-    // Determine risk level and action
-    const riskLevels = this.config.mfa?.adaptive?.riskLevels || this.defaultRiskLevels;
-    const { level, action, notifyUser } = this.determineRiskLevelAndAction(riskScore, riskLevels);
-
-    this.logger?.log?.(
-      `Adaptive MFA evaluation: user=${user.sub}, score=${riskScore}, level=${level}, action=${action}, notify=${notifyUser}, factors=[${riskFactors.join(', ')}]`,
-    );
-
-    // Prepare payload for hooks and audit
-    // Include payload when action requires it (block_signin) or when notifyUser is true
-    const payload: AdaptiveMFARiskEventPayload = {
-      user: {
-        sub: user.sub,
-        email: user.email, // Safe after validation above
-        username: user.username || undefined,
-        phoneNumber: user.phone || undefined,
-      },
-      riskScore,
-      riskLevel: level,
-      riskFactors,
-      action,
-      clientInfo: {
-        ipAddress: clientInfo.ipAddress,
-        ipCountry: clientInfo.ipCountry,
-        ipCity: clientInfo.ipCity,
-        deviceId: clientInfo.deviceToken, // deviceToken maps to deviceId in sessions
-        deviceName: clientInfo.deviceName,
-        deviceType: clientInfo.deviceType,
-        userAgent: clientInfo.userAgent,
-        platform: clientInfo.platform,
-        browser: clientInfo.browser,
-      },
-      authMethod,
-      timestamp: new Date(),
-    };
-
-    // Call lifecycle hook if configured and user should be notified
-    let hookOverride = false;
-    if (notifyUser && this.config.hooks?.onAdaptiveMFATriggered) {
-      try {
-        const result = await this.config.hooks.onAdaptiveMFATriggered(payload);
-        // Hook can return false to override and allow sign-in
-        if (result === false) {
-          hookOverride = true;
-          this.logger?.warn?.(`Adaptive MFA action overridden by hook: user=${user.sub}`);
-        }
-      } catch (error) {
-        // Non-blocking: Log error but continue with original action
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        this.logger?.error?.(`Adaptive MFA hook failed: ${errorMessage}`, { error, userId: user.sub });
-      }
-    }
-
-    // Record in audit trail (non-blocking)
-    // This logs the risk assessment result
-    // Determine event status based on risk level and action:
-    // - block_signin: SUSPICIOUS (security violation)
-    // - require_mfa with high/medium risk or suspicious factors: SUSPICIOUS
-    // - require_mfa with low risk: INFO (normal security measure)
-    // - allow: INFO (no risk detected)
-    const hasSuspiciousFactors =
-      riskFactors.includes(RiskFactor.SUSPICIOUS_ACTIVITY) ||
-      riskFactors.includes(RiskFactor.IMPOSSIBLE_TRAVEL) ||
-      level === 'high';
-    const eventStatus =
-      action === 'block_signin'
-        ? 'SUSPICIOUS'
-        : action === 'require_mfa' && hasSuspiciousFactors
-          ? 'SUSPICIOUS'
-          : 'INFO';
-
-    this.auditService
-      ?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.ADAPTIVE_MFA_RISK_ASSESSED,
-        eventStatus,
-        riskFactor: riskScore,
-        riskFactors,
-        adaptiveMfaTriggered: action !== 'allow',
-        description: `Adaptive MFA risk assessment: ${action} (score: ${riskScore}, level: ${level})`,
-        authMethod,
-        metadata: {
-          riskScore,
-          riskLevel: level,
-          action,
-          riskFactors,
-        },
-        // Client info automatically included from context
-      })
-      .catch((err) => {
-        this.logger?.warn?.(`Failed to record ADAPTIVE_MFA_RISK_ASSESSED audit: ${err.message}`);
-      });
-
-    return {
-      action: hookOverride ? 'allow' : action,
-      riskScore,
-      riskLevel: level,
-      riskFactors,
-      notifyUser,
-      hookOverride,
-      // Include payload when action requires it or when notifyUser is true
-      // This ensures consistent clientInfo data for blockUserSignIn and audit logs
-      payload: action === 'block_signin' || notifyUser ? payload : undefined,
-    };
-  }
-
-  /**
-   * Determine risk level and action based on score and configured thresholds
-   *
-   * Evaluates risk score against configured thresholds in order: low → medium → high.
-   * Returns the first level that the score falls within.
-   *
-   * @param riskScore - Calculated risk score (0-100)
-   * @param riskLevels - Configured risk level thresholds
-   * @returns Risk level, action, and notifyUser flag
-   * @private
-   */
-  private determineRiskLevelAndAction(
-    riskScore: number,
-    riskLevels: {
-      low?: { maxScore: number; action?: 'allow' | 'require_mfa' | 'block_signin'; notifyUser?: boolean };
-      medium?: { maxScore: number; action?: 'allow' | 'require_mfa' | 'block_signin'; notifyUser?: boolean };
-      high?: { maxScore: number; action?: 'allow' | 'require_mfa' | 'block_signin'; notifyUser?: boolean };
-    },
-  ): {
-    level: 'low' | 'medium' | 'high';
-    action: 'allow' | 'require_mfa' | 'block_signin';
-    notifyUser: boolean;
-  } {
-    // Check in order: low → medium → high
-    if (riskScore <= (riskLevels.low?.maxScore ?? 20)) {
-      return {
-        level: 'low',
-        action: riskLevels.low?.action ?? 'allow',
-        notifyUser: riskLevels.low?.notifyUser ?? false,
-      };
-    }
-
-    if (riskScore <= (riskLevels.medium?.maxScore ?? 50)) {
-      return {
-        level: 'medium',
-        action: riskLevels.medium?.action ?? 'require_mfa',
-        notifyUser: riskLevels.medium?.notifyUser ?? true,
-      };
-    }
-
-    return {
-      level: 'high',
-      action: riskLevels.high?.action ?? 'require_mfa',
-      notifyUser: riskLevels.high?.notifyUser ?? true,
-    };
-  }
-
-  /**
-   * Check if user is currently blocked due to high-risk sign-in
-   *
-   * Uses storage adapter to check for existing block. Block is stored with
-   * key format: `adaptive_mfa_block:{userId}`.
-   *
-   * @param userId - Internal user ID (integer)
-   * @returns Block status with expiration and message if blocked
-   *
-   * @example
-   * ```typescript
-   * const blockStatus = await adaptiveMFADecisionService.isUserBlocked(user.id);
-   * if (blockStatus.blocked) {
-   *   throw new NAuthException(AuthErrorCode.SIGNIN_BLOCKED_HIGH_RISK, blockStatus.message);
-   * }
-   * ```
-   */
-  async isUserBlocked(userId: number): Promise<{
-    blocked: boolean;
-    expiresAt?: Date;
-    message?: string;
-  }> {
-    try {
-      const blockKey = `adaptive_mfa_block:${userId}`;
-      const blockData = await this.storageAdapter.get(blockKey);
-
-      if (!blockData) {
-        return { blocked: false };
-      }
-
-      const parsed = JSON.parse(blockData);
-      const expiresAt = parsed.expiresAt ? new Date(parsed.expiresAt) : undefined;
-
-      // Check if block has expired (if temporary)
-      if (expiresAt && expiresAt < new Date()) {
-        // Block expired - clean up
-        await this.storageAdapter.del(blockKey);
-        return { blocked: false };
-      }
-
-      return {
-        blocked: true,
-        expiresAt,
-        message: parsed.message,
-      };
-    } catch (error) {
-      // Non-blocking: Log error but assume not blocked (safer for UX)
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-      this.logger?.warn?.(`Failed to check user block status: ${errorMessage}`, { error, userId });
-      return { blocked: false };
-    }
-  }
-
-  /**
-   * Block user sign-in due to high risk
-   *
-   * Stores block in storage adapter with optional TTL. Block data includes:
-   * - userId, userSub (for reference)
-   * - message (shown to user)
-   * - riskScore, riskFactors (for audit)
-   * - blockedAt, expiresAt (timestamps)
-   *
-   * Also calls onSignInBlocked lifecycle hook if configured.
-   *
-   * @param user - User to block
-   * @param payload - Risk event payload with all context
-   *
-   * @example
-   * ```typescript
-   * await adaptiveMFADecisionService.blockUserSignIn(user, payload);
-   * ```
-   */
-  async blockUserSignIn(user: IUser, payload: AdaptiveMFARiskEventPayload): Promise<void> {
-    const blockConfig = this.config.mfa?.adaptive?.blockedSignIn;
-    const blockDuration = blockConfig?.blockDuration; // minutes
-    const message = blockConfig?.message || 'Sign-in blocked due to suspicious activity. Please contact support.';
-
-    // Store block in storage adapter
-    const blockKey = `adaptive_mfa_block:${user.id}`;
-    const blockData = {
-      userId: user.id,
-      userSub: user.sub,
-      message,
-      riskScore: payload.riskScore,
-      riskFactors: payload.riskFactors,
-      blockedAt: new Date().toISOString(),
-      expiresAt: blockDuration ? new Date(Date.now() + blockDuration * 60 * 1000).toISOString() : undefined,
-    };
-
-    const ttl = blockDuration ? blockDuration * 60 : undefined; // Convert to seconds
-    await this.storageAdapter.set(blockKey, JSON.stringify(blockData), ttl);
-
-    this.logger?.warn?.(
-      `User sign-in blocked: user=${user.sub}, score=${payload.riskScore}, duration=${blockDuration ? `${blockDuration}min` : 'permanent'}`,
-    );
-
-    // Call sign-in blocked hook if configured
-    if (this.config.hooks?.onSignInBlocked) {
-      const blockedPayload: SignInBlockedPayload = {
-        ...payload,
-        blockDuration,
-        blockExpiresAt: blockDuration ? new Date(Date.now() + blockDuration * 60 * 1000) : undefined,
-        message,
-      };
-
-      try {
-        await this.config.hooks.onSignInBlocked(blockedPayload);
-      } catch (error) {
-        // Non-blocking
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        this.logger?.error?.(`Sign-in blocked hook failed: ${errorMessage}`, { error, userId: user.sub });
-      }
-    }
-  }
-
-  /**
-   * Clear user block (manual unblock)
-   *
-   * Removes the block from storage adapter, allowing user to sign in again.
-   * Useful for admin actions or when risk situation has improved.
-   *
-   * @param userId - Internal user ID (integer)
-   *
-   * @example
-   * ```typescript
-   * await adaptiveMFADecisionService.clearUserBlock(user.id);
-   * ```
-   */
-  async clearUserBlock(userId: number): Promise<void> {
-    try {
-      const blockKey = `adaptive_mfa_block:${userId}`;
-      await this.storageAdapter.del(blockKey);
-      this.logger?.log?.(`User block cleared: userId=${userId}`);
-    } catch (error) {
-      // Non-blocking: Log error but continue
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-      this.logger?.warn?.(`Failed to clear user block: ${errorMessage}`, { error, userId });
-    }
-  }
-}