@nauth-toolkit/core 0.1.0

package/src/services/auth-audit.service.ts

@@ -0,0 +1,558 @@
+import { Repository } from 'typeorm';
+import { BaseAuthAudit, BaseUser } from '../entities';
+import { IAuthAudit, IUser } from '../interfaces/entities.interface';
+import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+import { AuthAuditEventStatus } from '../entities/auth-audit.entity';
+import { NAuthLogger } from '../utils/nauth-logger';
+import { NAuthException } from '../exceptions/nauth.exception';
+import { AuthErrorCode } from '../enums/error-codes.enum';
+import { ClientInfoService } from './client-info.service';
+import { RiskFactor } from '../enums/risk-factor.enum';
+import { GetUserAuthHistoryDTO, GetUserAuthHistoryResponseDTO } from '../dto/get-user-auth-history.dto';
+import { GetEventsByTypeDTO, GetEventsByTypeResponseDTO } from '../dto/get-events-by-type.dto';
+import { GetSuspiciousActivityDTO, GetSuspiciousActivityResponseDTO } from '../dto/get-suspicious-activity.dto';
+import {
+  GetRiskAssessmentHistoryDTO,
+  GetRiskAssessmentHistoryResponseDTO,
+} from '../dto/get-risk-assessment-history.dto';
+
+/**
+ * DTO for creating audit events
+ *
+ * @internal
+ * This DTO is only used by InternalAuthAuditService and should not be exposed
+ * to consumer applications.
+ */
+export interface CreateAuthAuditEventDTO {
+  userId?: number; // Internal user ID (preferred)
+  userSub?: string; // External user identifier (will lookup userId)
+  eventType: AuthAuditEventType;
+  eventStatus: AuthAuditEventStatus;
+  riskFactor?: number | null;
+  riskFactors?: RiskFactor[] | null;
+  adaptiveMfaTriggered?: boolean | null;
+  // Note: ipAddress, ipCountry, ipCity, userAgent, platform, browser, deviceId, deviceName, deviceType
+  // are automatically captured from ClientInfoService and cannot be overridden
+  // Use metadata for event-specific data only
+  deviceId?: string | null; // Special case: can override for newly created device tokens
+  sessionId?: number | null;
+  challengeSessionId?: number | null;
+  authMethod?: string | null;
+  performedBy?: string | null; // Auto-populated from session context if not provided (userId of authenticated user)
+  reason?: string | null;
+  description?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+/**
+ * Authentication Audit Service (Base Class - Public API)
+ *
+ * Manages audit trail queries for authentication and security events.
+ * Provides query capabilities for retrieving audit history.
+ *
+ * **Key Features:**
+ * - Efficient queries using userId (internal integer ID)
+ * - Pagination support for large datasets
+ * - Query filtering by event type, status, date ranges
+ * - User history queries (resolves userSub to userId automatically)
+ *
+ * **Design Notes:**
+ * - Only stores `userId` (integer) - no userSub duplication
+ * - All methods accepting userSub resolve to userId before querying
+ * - Risk tracking fields are infrastructure for future adaptive MFA (no business logic)
+ *
+ * **Note:** This is the public API class. Event recording is handled internally
+ * by `InternalAuthAuditService` and is not exposed to consumer applications.
+ *
+ * @example
+ * ```typescript
+ * // Get user history (accepts userSub, resolves to userId)
+ * const history = await auditService.getUserAuthHistory({
+ *   userSub: 'user-uuid',
+ *   page: 1,
+ *   limit: 50,
+ *   startDate: new Date('2025-01-01'),
+ * });
+ * ```
+ */
+export class AuthAuditService {
+  constructor(
+    protected readonly auditRepository: Repository<BaseAuthAudit>,
+    protected readonly userRepository: Repository<BaseUser>,
+    protected readonly logger: NAuthLogger,
+    protected readonly clientInfoService?: ClientInfoService,
+  ) {}
+
+  // ============================================================================
+  // Query Methods
+  // ============================================================================
+
+  /**
+   * Get paginated authentication history for a user
+   *
+   * Accepts userSub (external identifier) and resolves to userId for efficient queries.
+   * Supports filtering by event types, status, and date ranges.
+   *
+   * @param request - Request DTO containing userSub and filtering options
+   * @returns Response DTO with paginated audit records
+   * @throws {NAuthException} If user not found
+   *
+   * @example
+   * ```typescript
+   * const history = await auditService.getUserAuthHistory({
+   *   userSub: 'user-uuid',
+   *   page: 1,
+   *   limit: 50,
+   *   eventTypes: [AuthAuditEventType.LOGIN_SUCCESS, AuthAuditEventType.LOGIN_FAILED],
+   *   startDate: new Date('2025-01-01'),
+   * });
+   * ```
+   */
+  async getUserAuthHistory(request: GetUserAuthHistoryDTO): Promise<GetUserAuthHistoryResponseDTO> {
+    // Resolve userSub to userId
+    const user = (await this.userRepository.findOne({ where: { sub: request.userSub } })) as IUser | null;
+    if (!user) {
+      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
+    }
+
+    const page = request.page || 1;
+    const limit = request.limit || 50;
+    const skip = (page - 1) * limit;
+
+    // Build query
+    const queryBuilder = this.auditRepository
+      .createQueryBuilder('audit')
+      .where('audit.userId = :userId', { userId: user.id });
+
+    // Date range filter
+    if (request.startDate) {
+      queryBuilder.andWhere('audit.createdAt >= :startDate', { startDate: request.startDate });
+    }
+    if (request.endDate) {
+      queryBuilder.andWhere('audit.createdAt <= :endDate', { endDate: request.endDate });
+    }
+
+    // Event type filter
+    if (request.eventTypes && request.eventTypes.length > 0) {
+      queryBuilder.andWhere('audit.eventType IN (:...eventTypes)', { eventTypes: request.eventTypes });
+    }
+
+    // Event status filter
+    if (request.eventStatus && request.eventStatus.length > 0) {
+      queryBuilder.andWhere('audit.eventStatus IN (:...eventStatus)', { eventStatus: request.eventStatus });
+    }
+
+    // Order by date (newest first)
+    queryBuilder.orderBy('audit.createdAt', 'DESC');
+
+    // Pagination
+    queryBuilder.skip(skip).take(limit);
+
+    const [data, total] = await queryBuilder.getManyAndCount();
+
+    const response = new GetUserAuthHistoryResponseDTO();
+    response.data = data as unknown as IAuthAudit[];
+    response.total = total;
+    response.page = page;
+    response.limit = limit;
+    response.totalPages = Math.ceil(total / limit);
+
+    return response;
+  }
+
+  /**
+   * Get events by type with pagination
+   *
+   * @param request - Request DTO containing eventType and pagination options
+   * @returns Response DTO with paginated audit records
+   *
+   * @example
+   * ```typescript
+   * const events = await auditService.getEventsByType({
+   *   eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
+   *   page: 1,
+   *   limit: 100,
+   * });
+   * ```
+   */
+  async getEventsByType(request: GetEventsByTypeDTO): Promise<GetEventsByTypeResponseDTO> {
+    const page = request.page || 1;
+    const limit = request.limit || 50;
+    const skip = (page - 1) * limit;
+
+    const queryBuilder = this.auditRepository.createQueryBuilder('audit').where('audit.eventType = :eventType', {
+      eventType: request.eventType,
+    });
+
+    // Date range filter
+    if (request.startDate) {
+      queryBuilder.andWhere('audit.createdAt >= :startDate', { startDate: request.startDate });
+    }
+    if (request.endDate) {
+      queryBuilder.andWhere('audit.createdAt <= :endDate', { endDate: request.endDate });
+    }
+
+    queryBuilder.orderBy('audit.createdAt', 'DESC').skip(skip).take(limit);
+
+    const [data, total] = await queryBuilder.getManyAndCount();
+
+    const response = new GetEventsByTypeResponseDTO();
+    response.data = data as unknown as IAuthAudit[];
+    response.total = total;
+    response.page = page;
+    response.limit = limit;
+    response.totalPages = Math.ceil(total / limit);
+
+    return response;
+  }
+
+  /**
+   * Get suspicious activity events
+   *
+   * Returns events with SUSPICIOUS status or SUSPICIOUS_ACTIVITY event type.
+   *
+   * @param request - Request DTO containing optional userSub and limit
+   * @returns Response DTO with array of suspicious audit events
+   *
+   * @example
+   * ```typescript
+   * // Get all suspicious activity
+   * const suspicious = await auditService.getSuspiciousActivity({});
+   *
+   * // Get suspicious activity for specific user
+   * const userSuspicious = await auditService.getSuspiciousActivity({
+   *   userSub: 'user-uuid',
+   *   limit: 50,
+   * });
+   * ```
+   */
+  async getSuspiciousActivity(request: GetSuspiciousActivityDTO): Promise<GetSuspiciousActivityResponseDTO> {
+    const limit = request.limit || 100;
+
+    const queryBuilder = this.auditRepository
+      .createQueryBuilder('audit')
+      .where('(audit.eventStatus = :status OR audit.eventType = :eventType)', {
+        status: 'SUSPICIOUS',
+        eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
+      });
+
+    // Filter by user if provided
+    if (request.userSub) {
+      const user = (await this.userRepository.findOne({ where: { sub: request.userSub } })) as IUser | null;
+      if (!user) {
+        throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
+      }
+      queryBuilder.andWhere('audit.userId = :userId', { userId: user.id });
+    }
+
+    queryBuilder.orderBy('audit.createdAt', 'DESC').take(limit);
+
+    const data = await queryBuilder.getMany();
+
+    const response = new GetSuspiciousActivityResponseDTO();
+    response.data = data as unknown as IAuthAudit[];
+
+    return response;
+  }
+
+  /**
+   * Get risk assessment history for adaptive MFA analysis
+   *
+   * Returns events where risk assessment was performed (ADAPTIVE_MFA_RISK_ASSESSED,
+   * ADAPTIVE_MFA_TRIGGERED, ADAPTIVE_MFA_BYPASSED).
+   *
+   * @param request - Request DTO containing userSub and limit
+   * @returns Response DTO with array of risk assessment audit events
+   * @throws {NAuthException} If user not found
+   *
+   * @example
+   * ```typescript
+   * const riskHistory = await auditService.getRiskAssessmentHistory({
+   *   userSub: 'user-uuid',
+   *   limit: 50,
+   * });
+   * ```
+   */
+  async getRiskAssessmentHistory(request: GetRiskAssessmentHistoryDTO): Promise<GetRiskAssessmentHistoryResponseDTO> {
+    const limit = request.limit || 100;
+
+    // Resolve userSub to userId
+    const user = (await this.userRepository.findOne({ where: { sub: request.userSub } })) as IUser | null;
+    if (!user) {
+      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
+    }
+
+    const queryBuilder = this.auditRepository
+      .createQueryBuilder('audit')
+      .where('audit.userId = :userId', { userId: user.id })
+      .andWhere('audit.eventType IN (:...eventTypes)', {
+        eventTypes: [
+          AuthAuditEventType.ADAPTIVE_MFA_RISK_ASSESSED,
+          AuthAuditEventType.ADAPTIVE_MFA_TRIGGERED,
+          AuthAuditEventType.ADAPTIVE_MFA_BYPASSED,
+        ],
+      })
+      .orderBy('audit.createdAt', 'DESC')
+      .take(limit);
+
+    const data = await queryBuilder.getMany();
+
+    const response = new GetRiskAssessmentHistoryResponseDTO();
+    response.data = data as unknown as IAuthAudit[];
+
+    return response;
+  }
+}
+
+// ============================================================================
+// Internal Service (Framework Adapters Only)
+// ============================================================================
+
+/**
+ * Internal Authentication Audit Service
+ *
+ * Extends the base AuthAuditService with event recording capabilities.
+ * This service is only available via `@nauth-toolkit/core/internal` and should
+ * NOT be used by consumer applications.
+ *
+ * **Event Recording:**
+ * The `recordEvent()` method is internal-only and is used by nauth-toolkit
+ * services to log authentication events. Consumer applications should use
+ * the query methods from the base `AuthAuditService` class.
+ *
+ * @internal
+ * This class is only exported from `@nauth-toolkit/core/internal` for use
+ * by framework adapters. Consumer applications should use the base
+ * `AuthAuditService` from `@nauth-toolkit/core`.
+ *
+ * @example
+ * ```typescript
+ * // Framework adapter usage
+ * import { AuthAuditService } from '@nauth-toolkit/core/internal';
+ *
+ * const auditService = new AuthAuditService(...);
+ * // Can use recordEvent() here (internal only)
+ * await auditService.recordEvent({ ... });
+ * ```
+ */
+export class InternalAuthAuditService extends AuthAuditService {
+  /**
+   * Record an authentication audit event
+   *
+   * Creates an audit record for an authentication or security event.
+   * Automatically extracts client information from request context when available.
+   * This method is non-blocking - errors are logged but don't throw exceptions.
+   *
+   * **Automatic Client Info Extraction:**
+   * When ClientInfoService is available, the following fields are automatically populated:
+   * - ipAddress, ipCountry, ipCity (from request and geolocation)
+   * - userAgent, platform, browser (from user agent parsing)
+   * - deviceId, deviceName, deviceType (from request context)
+   *
+   * Note: These fields cannot be overridden via the DTO - they are always captured from the request context.
+   * Only deviceId can be explicitly set for special cases (e.g., newly created device tokens).
+   * Do not include ipAddress, ipCountry, ipCity, userAgent, platform, browser, deviceName, or deviceType
+   * in the DTO - they will be automatically captured and attempts to include them will cause TypeScript errors.
+   *
+   * **Automatic performedBy Population:**
+   * The `performedBy` field is automatically populated from the authenticated user's context:
+   * - If userId is available from ClientInfoService (extracted from JWT token by interceptors/handlers), it is used as `performedBy`
+   * - This captures who performed the action (e.g., admin performing action on another user)
+   * - If no userId is found in client info, `performedBy` defaults to the event's `userId` (user performing action on themselves)
+   * - Explicit `performedBy` in DTO overrides automatic population
+   *
+   * @internal
+   * This method is only available in InternalAuthAuditService and should not
+   * be exposed to consumer applications.
+   *
+   * @param data - Audit event data (only event-specific fields needed)
+   * @param data.userId - Internal user ID (preferred, more efficient)
+   * @param data.userSub - External user identifier (will lookup userId if userId not provided)
+   * @param data.eventType - Type of event
+   * @param data.eventStatus - Event classification status
+   * @returns Created audit record
+   *
+   * @example
+   * ```typescript
+   * // Simple recording - client info auto-populated
+   * await auditService.recordEvent({
+   *   userId: user.id,
+   *   eventType: AuthAuditEventType.LOGIN_SUCCESS,
+   *   eventStatus: 'SUCCESS',
+   *   authMethod: 'password',
+   *   // ipAddress, userAgent, deviceName, etc. automatically included!
+   * });
+   *
+   * // Override specific fields if needed
+   * await auditService.recordEvent({
+   *   userId: user.id,
+   *   eventType: AuthAuditEventType.LOGIN_SUCCESS,
+   *   eventStatus: 'SUCCESS',
+   *   // ipAddress, userAgent, etc. automatically captured from request context
+   * });
+   * ```
+   */
+  async recordEvent(data: CreateAuthAuditEventDTO): Promise<IAuthAudit | null> {
+    try {
+      // Resolve userId if userSub provided
+      let userId = data.userId;
+      if (!userId && data.userSub) {
+        const user = (await this.userRepository.findOne({ where: { sub: data.userSub } })) as IUser | null;
+        if (!user) {
+          this.logger?.warn?.(`Cannot record audit event - user not found: ${data.userSub}`);
+          return null;
+        }
+        userId = user.id;
+      }
+
+      if (!userId) {
+        this.logger?.warn?.('Cannot record audit event - userId or userSub required');
+        return null;
+      }
+
+      // ============================================================================
+      // Auto-extract client info from context (when available)
+      // Note: These fields are automatically captured and cannot be overridden by callers
+      // ============================================================================
+      let clientInfo: {
+        ipAddress?: string | null;
+        ipCountry?: string | null;
+        ipCity?: string | null;
+        ipLatitude?: number | null;
+        ipLongitude?: number | null;
+        userAgent?: string | null;
+        platform?: string | null;
+        browser?: string | null;
+        deviceId?: string | null;
+        deviceName?: string | null;
+        deviceType?: string | null;
+        sessionId?: number | null;
+      } = {};
+
+      if (this.clientInfoService) {
+        try {
+          const clientInfoFromContext = this.clientInfoService.get();
+          
+          // Debug logging
+          if (!clientInfoFromContext.ipLatitude || !clientInfoFromContext.ipLongitude) {
+            this.logger?.warn?.(
+              `[AuthAuditService] Creating audit WITHOUT coordinates from context: ` +
+              `IP=${clientInfoFromContext.ipAddress}, country=${clientInfoFromContext.ipCountry}, ` +
+              `city=${clientInfoFromContext.ipCity}, lat=${clientInfoFromContext.ipLatitude}, ` +
+              `lon=${clientInfoFromContext.ipLongitude}`,
+            );
+          } else {
+            this.logger?.debug?.(
+              `[AuthAuditService] Creating audit WITH coordinates from context: ` +
+              `IP=${clientInfoFromContext.ipAddress}, ${clientInfoFromContext.ipCity}, ` +
+              `${clientInfoFromContext.ipCountry} (${clientInfoFromContext.ipLatitude}, ${clientInfoFromContext.ipLongitude})`,
+            );
+          }
+          
+          // Automatically capture from context (no override allowed)
+          clientInfo = {
+            ipAddress: clientInfoFromContext.ipAddress || null,
+            ipCountry: clientInfoFromContext.ipCountry || null,
+            ipCity: clientInfoFromContext.ipCity || null,
+            ipLatitude: clientInfoFromContext.ipLatitude || null,
+            ipLongitude: clientInfoFromContext.ipLongitude || null,
+            userAgent: clientInfoFromContext.userAgent || null,
+            platform: clientInfoFromContext.platform || null,
+            browser: clientInfoFromContext.browser || null,
+            deviceId: clientInfoFromContext.deviceToken || null,
+            deviceName: clientInfoFromContext.deviceName || null,
+            deviceType: clientInfoFromContext.deviceType || null,
+            sessionId: clientInfoFromContext.sessionId || null,
+          };
+        } catch (error) {
+          // Non-blocking: If client info extraction fails, continue without it
+          // This can happen if called outside request context (e.g., cron jobs)
+          this.logger?.debug?.(
+            `Failed to extract client info for audit: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          );
+        }
+      }
+
+      // ============================================================================
+      // Use auto-extracted client info (deviceId can be overridden for special cases)
+      // ============================================================================
+      const mergedData = {
+        ipAddress: clientInfo.ipAddress ?? null,
+        ipCountry: clientInfo.ipCountry ?? null,
+        ipCity: clientInfo.ipCity ?? null,
+        ipLatitude: clientInfo.ipLatitude ?? null,
+        ipLongitude: clientInfo.ipLongitude ?? null,
+        userAgent: clientInfo.userAgent ?? null,
+        platform: clientInfo.platform ?? null,
+        browser: clientInfo.browser ?? null,
+        deviceId: data.deviceId ?? clientInfo.deviceId ?? null, // Allow override for newly created device tokens
+        deviceName: clientInfo.deviceName ?? null,
+        deviceType: clientInfo.deviceType ?? null,
+        sessionId: data.sessionId ?? clientInfo.sessionId ?? null,
+      };
+
+      // ============================================================================
+      // Auto-populate performedBy from client info context (if available)
+      // ============================================================================
+      let performedBy: string | null = data.performedBy ?? null;
+      if (!performedBy && this.clientInfoService) {
+        try {
+          // Get userId from client info (extracted from JWT token by interceptors/handlers)
+          const clientInfo = this.clientInfoService.get();
+          if (clientInfo?.userId) {
+            // Use the userId from client info as performedBy
+            // This captures who performed the action (could be admin performing action on another user)
+            performedBy = String(clientInfo.userId);
+          }
+        } catch (error) {
+          // Non-blocking: If client info extraction fails, continue without performedBy
+          this.logger?.debug?.(
+            `Failed to get userId from client info for performedBy: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          );
+        }
+      }
+
+      // If still no performedBy and we have userId, use it as fallback
+      // (most actions are performed by the user themselves)
+      if (!performedBy && userId) {
+        performedBy = String(userId);
+      }
+
+      // Create audit record
+      const auditRecord = this.auditRepository.create({
+        userId,
+        eventType: data.eventType,
+        eventStatus: data.eventStatus,
+        riskFactor: data.riskFactor ?? null,
+        riskFactors: data.riskFactors ?? null,
+        adaptiveMfaTriggered: data.adaptiveMfaTriggered ?? null,
+        ipAddress: mergedData.ipAddress,
+        ipCountry: mergedData.ipCountry,
+        ipCity: mergedData.ipCity,
+        ipLatitude: mergedData.ipLatitude,
+        ipLongitude: mergedData.ipLongitude,
+        userAgent: mergedData.userAgent,
+        platform: mergedData.platform,
+        browser: mergedData.browser,
+        deviceId: mergedData.deviceId,
+        deviceName: mergedData.deviceName,
+        deviceType: mergedData.deviceType,
+        sessionId: mergedData.sessionId,
+        challengeSessionId: data.challengeSessionId ?? null,
+        authMethod: data.authMethod ?? null,
+        performedBy,
+        reason: data.reason ?? null,
+        description: data.description ?? null,
+        metadata: data.metadata ?? null,
+      });
+
+      const saved = await this.auditRepository.save(auditRecord);
+      return saved as unknown as IAuthAudit;
+    } catch (error) {
+      // Non-blocking: Log error but don't throw
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger?.error?.(`Failed to record audit event: ${errorMessage}`, { eventType: data.eventType, error });
+      return null;
+    }
+  }
+}