@wildo-ai/saas-backend-lib 1.0.1

package/src/compliance/audit-trails/services/audit-logs.backend.service.ts

@@ -0,0 +1,1313 @@
+import 'reflect-metadata';
+import { inject, injectable } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { AuditEventDispatcherBackendService } from './audit-event-dispatcher.backend.service';
+import {
+  getAuditEventClassification,
+  SiemExportChangeType,
+  SsoConfigChangeType,
+  SsoConnectionType,
+  AuditableEvent,
+  AuditableEvent_User_LoginEventData,
+  AuditableEvent_User_LogoutEventData,
+  AuditableEvent_User_LoginFailedEventData,
+  AuditableEvent_User_AccountLockedEventData,
+  AuditableEvent_User_SessionExpiredEventData,
+  AuditableEvent_FieldAccess_EventData,
+  AuditableEvent_User_SSOLoginEventData,
+  AuditableEvent_User_SSOLoginFailedEventData,
+  AuditableEvent_User_SSOEnforcementBlockedEventData,
+  AuditableEvent_User_TokenRefreshedEventData,
+  AuditableEvent_Organization_SSOConfigurationChangedEventData,
+  AuditableEvent_Organization_SIEMExportConfiguredEventData,
+  AuditableEvent_EmergencyAccess_UsedEventData,
+  AuditableEvent_User_PasswordResetRequestedEventData,
+  AuditableEvent_User_PasswordResetCompletedEventData,
+  AuditableEvent_User_RegisteredEventData,
+  AuditableEvent_User_EmailVerifiedEventData,
+  AuditableEvent_User_VerificationEmailResentEventData,
+  AuditableEvent_User_MFASetupStartedEventData,
+  AuditableEvent_User_MFASetupCompletedEventData,
+  AuditableEvent_User_MFAEmailOTPSentEventData,
+  AuditableEvent_User_PasskeyRegisteredEventData,
+  AuditableEvent_User_PasskeyAuthSuccessEventData,
+  AuditableEvent_User_PasskeyAuthFailureEventData,
+  AuditableEvent_User_PasskeyRemovedEventData,
+  AuditableEvent_SCIM_UserProvisionedEventData,
+  AuditableEvent_SCIM_UserUpdatedEventData,
+  AuditableEvent_SCIM_UserDeactivatedEventData,
+  AuditableEvent_User_MagicLinkSentEventData,
+  AuditableEvent_User_MagicLinkVerifiedEventData,
+  AuditableEvent_User_MagicLinkFailedEventData,
+  AuditableEvent_User_SMSOTPSentEventData,
+  AuditableEvent_User_SMSOTPVerifiedEventData,
+  AuditableEvent_User_SMSOTPFailedEventData,
+  AuditableEvent_User_PhoneVerifiedEventData,
+  AuditableEvent_User_PhoneVerificationFailedEventData,
+  AuditableEvent_OAuth2ProviderBlockedEventData,
+  CoreAuditableEventType,
+  ErrorCustomMessageReference,
+  ErrorType,
+  ResourceOperationRiskLevel,
+  ResourceOperationVariantType,
+  ResourcePrimaryScope,
+  ResourceType,
+  CORE_APP_ROLES
+} from '@wildo-ai/saas-models';
+import type { ResourceConfiguration_OperationPath } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, CoreResourceType } from '@wildo-ai/saas-models';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+
+@injectable()
+export class AuditLogsBackendService {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService) private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuditEventDispatcherService) private readonly auditEventDispatcher: AuditEventDispatcherBackendService,
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService) private readonly executionContextCreator: ExecutionContextCreatorBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('AuditLogsBackendService');
+    this.logger.setDebugTypeLogging('AuditLogsBackendService', true);
+  }
+
+  private async _getTempExecutionContext(): Promise<ExecutionContext<any>> {
+    const operation: ResourceConfiguration_OperationPath<any, any> = {
+      resourceIdentifier: CoreResourceType.AUDIT_LOGS,
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+      isOperationDefault: true
+    };
+
+    return this.executionContextCreator.createForInternalOperation({
+      operation,
+      contextResourcesFieldIdentifier: new Map(),
+      initiatorIds: null,
+      initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
+    });
+  }
+
+  /**
+   * Create an audit log entry.
+   * Enriches eventCategory and severity from getAuditEventClassification.
+   */
+  private async _createAuditLog(auditEvent: Omit<AuditableEvent, '_id' | 'createdAt' | 'updatedAt' | 'eventCategory' | 'severity'>): Promise<void> {
+    try {
+      const ec = await this._getTempExecutionContext();
+      const auditRepo = this.repositoriesRegistry.getRepositoryOrThrow(CoreResourceType.AUDIT_LOGS);
+
+      const classification = getAuditEventClassification(auditEvent.eventType);
+      const auditLogData = {
+        ...auditEvent,
+        eventData: auditEvent.eventData as Record<string, any>,
+        eventCategory: classification.category,
+        severity: classification.severity,
+        createdAt: new Date(),
+        updatedAt: new Date()
+      };
+
+      await auditRepo.create(ec, auditLogData);
+      this.logDebug(`Created audit log: ${auditEvent.eventType}`, { eventData: auditEvent.eventData });
+
+      if (auditEvent.organizationId) {
+        this.auditEventDispatcher.dispatchToOrganizationSIEM(ec, auditLogData, auditEvent.organizationId)
+          .catch(err => this.logger.error?.('SIEM dispatch fire-and-forget error', { err }));
+      }
+    } catch (error) {
+      this.logger.error?.('Failed to create audit log', { error, eventType: auditEvent.eventType });
+    }
+  }
+
+  // ===============================
+  // USER AUTHENTICATION AUDIT METHODS
+  // ===============================
+
+  /**
+   * Log successful user login
+   */
+  public async logUserLogin(data: {
+    userId: string;
+    email: string;
+    authMethod: string;
+    ipAddress: string;
+    userAgent: string;
+    sessionId: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const typedEventData: AuditableEvent_User_LoginEventData = {
+      eventType: CoreAuditableEventType.USER_LOGIN,
+      userId: data.userId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      authMethod: data.authMethod,
+      email: data.email,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_LOGIN,
+      eventData: typedEventData as Record<string, any> // Store as plain object
+    });
+  }
+
+  /**
+   * Log user logout
+   */
+  public async logUserLogout(data: {
+    userId: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_LogoutEventData = {
+      eventType: CoreAuditableEventType.USER_LOGOUT,
+      userId: data.userId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_LOGOUT,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log user login failure
+   */
+  public async logUserLoginFailed(data: {
+    email: string;
+    authMethod: string;
+    failureReason: string;
+    ipAddress: string;
+    userAgent: string;
+    attemptsRemaining?: number;
+    sessionId: string;
+    organizationId?: string;
+  }): Promise<void> {
+    // Validate with typed schema first
+    const typedEventData: AuditableEvent_User_LoginFailedEventData = {
+      eventType: CoreAuditableEventType.USER_LOGIN_FAILED,
+      email: data.email,
+      authMethod: data.authMethod,
+      failureReason: data.failureReason,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      attemptsRemaining: data.attemptsRemaining,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: undefined, // No userId available for failed login (user not identified)
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_LOGIN_FAILED,
+      eventData: typedEventData as Record<string, any> // Store as plain object
+    });
+  }
+
+  /**
+   * Log user account lockout
+   */
+  public async logUserAccountLocked(data: {
+    userId: string;
+    email: string;
+    authMethod: string;
+    lockoutDuration: number;
+    ipAddress: string;
+    userAgent: string;
+    sessionId: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_AccountLockedEventData = {
+      eventType: CoreAuditableEventType.USER_ACCOUNT_LOCKED,
+      userId: data.userId,
+      email: data.email,
+      authMethod: data.authMethod,
+      lockoutDuration: data.lockoutDuration,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.HIGH,
+      eventType: CoreAuditableEventType.USER_ACCOUNT_LOCKED,
+      eventData: eventData
+    });
+  }
+
+  // ===============================
+  // FIELD ACCESS AUDIT METHODS
+  // ===============================
+
+  /**
+   * Phase 3.10 + Q4: Log field access for sensitive backend-only fields.
+   * Called when fields with `isReturnedAtCreation` (CREATE) or `auditAccess` (any operation) are returned in API responses.
+   */
+  public async logFieldAccess(data: {
+    fieldName: string;
+    resourceType: ResourceType;
+    resourceId?: string;
+    userId?: string;
+    organizationId?: string;
+    applicationId?: string;
+    operationIdentifier: string;
+    isCreateOperation: boolean;
+  }): Promise<void> {
+    const eventData: AuditableEvent_FieldAccess_EventData = {
+      eventType: CoreAuditableEventType.FIELD_ACCESS,
+      fieldName: data.fieldName,
+      resourceType: data.resourceType,
+      resourceId: data.resourceId,
+      operationIdentifier: data.operationIdentifier,
+      isCreateOperation: data.isCreateOperation,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM, // Field access is medium risk
+      eventType: CoreAuditableEventType.FIELD_ACCESS,
+      eventData: eventData as Record<string, any>
+    });
+  }
+
+  // ===============================
+  // SSO AUTHENTICATION AUDIT METHODS (Step 18)
+  // ===============================
+
+  /**
+   * Log successful SSO login (distinct from USER_LOGIN — captures provider ref, connection type)
+   */
+  public async logUserSSOLogin(data: {
+    userId: string;
+    email: string;
+    providerRef: string;
+    connectionType: SsoConnectionType;
+    authSource?: string;
+    organizationId?: string;
+    ipAddress: string;
+    userAgent: string;
+    sessionId: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_SSOLoginEventData = {
+      eventType: CoreAuditableEventType.USER_SSO_LOGIN,
+      userId: data.userId,
+      email: data.email,
+      providerRef: data.providerRef,
+      connectionType: data.connectionType,
+      authSource: data.authSource,
+      organizationId: data.organizationId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_SSO_LOGIN,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log SSO login failure (with failure reason: enforcement blocked, IdP error, etc.)
+   */
+  public async logUserSSOLoginFailed(data: {
+    email?: string;
+    providerRef?: string;
+    connectionType?: SsoConnectionType;
+    authSource?: string;
+    failureReason: string;
+    organizationId?: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_SSOLoginFailedEventData = {
+      eventType: CoreAuditableEventType.USER_SSO_LOGIN_FAILED,
+      email: data.email,
+      providerRef: data.providerRef,
+      connectionType: data.connectionType,
+      authSource: data.authSource,
+      failureReason: data.failureReason,
+      organizationId: data.organizationId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: undefined,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_SSO_LOGIN_FAILED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log SSO enforcement blocked (social SSO rejected due to org enforcement — the C4 scenario)
+   */
+  public async logUserSSOEnforcementBlocked(data: {
+    email: string;
+    attemptedProviderRef: string;
+    attemptedConnectionType: SsoConnectionType;
+    organizationId: string;
+    enforcementPolicy: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_SSOEnforcementBlockedEventData = {
+      eventType: CoreAuditableEventType.USER_SSO_ENFORCEMENT_BLOCKED,
+      email: data.email,
+      attemptedProviderRef: data.attemptedProviderRef,
+      attemptedConnectionType: data.attemptedConnectionType,
+      organizationId: data.organizationId,
+      enforcementPolicy: data.enforcementPolicy,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: undefined,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.HIGH,
+      eventType: CoreAuditableEventType.USER_SSO_ENFORCEMENT_BLOCKED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log token refresh (security-relevant for enterprise)
+   */
+  public async logUserTokenRefreshed(data: {
+    userId: string;
+    sessionId: string;
+    organizationId?: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_TokenRefreshedEventData = {
+      eventType: CoreAuditableEventType.USER_TOKEN_REFRESHED,
+      userId: data.userId,
+      sessionId: data.sessionId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_TOKEN_REFRESHED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // ORGANIZATION SECURITY MANAGEMENT AUDIT METHODS (Step 18)
+  // ===============================
+
+  /**
+   * Log SSO configuration change (admin changed SSO settings)
+   */
+  public async logOrganizationSSOConfigurationChanged(data: {
+    organizationId: string;
+    changedBy: string;
+    changeType: SsoConfigChangeType;
+    affectedProviderRef?: string;
+    changes?: Record<string, unknown>;
+  }): Promise<void> {
+    const eventData: AuditableEvent_Organization_SSOConfigurationChangedEventData = {
+      eventType: CoreAuditableEventType.ORGANIZATION_SSO_CONFIGURATION_CHANGED,
+      organizationId: data.organizationId,
+      changedBy: data.changedBy,
+      changeType: data.changeType,
+      affectedProviderRef: data.affectedProviderRef,
+      changes: data.changes,
+    };
+
+    await this._createAuditLog({
+      userId: data.changedBy,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.ORGANIZATION_SSO_CONFIGURATION_CHANGED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log SIEM export configuration change (meta-audit — admin configured SIEM export)
+   */
+  public async logOrganizationSIEMExportConfigured(data: {
+    organizationId: string;
+    changedBy: string;
+    changeType: SiemExportChangeType;
+    webhookUrlDomain?: string;
+    eventFormatConfigured?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_Organization_SIEMExportConfiguredEventData = {
+      eventType: CoreAuditableEventType.ORGANIZATION_SIEM_EXPORT_CONFIGURED,
+      organizationId: data.organizationId,
+      changedBy: data.changedBy,
+      changeType: data.changeType,
+      webhookUrlDomain: data.webhookUrlDomain,
+      eventFormatConfigured: data.eventFormatConfigured,
+    };
+
+    await this._createAuditLog({
+      userId: data.changedBy,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.ORGANIZATION_SIEM_EXPORT_CONFIGURED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log emergency access used (break-glass account used)
+   */
+  public async logEmergencyAccessUsed(data: {
+    userId: string;
+    email: string;
+    organizationId: string;
+    reason?: string;
+    ipAddress: string;
+    userAgent: string;
+    sessionId: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_EmergencyAccess_UsedEventData = {
+      eventType: CoreAuditableEventType.EMERGENCY_ACCESS_USED,
+      userId: data.userId,
+      email: data.email,
+      organizationId: data.organizationId,
+      reason: data.reason,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.HIGH,
+      eventType: CoreAuditableEventType.EMERGENCY_ACCESS_USED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // PASSWORD RESET AUDIT METHODS (H5)
+  // ===============================
+
+  /**
+   * Log password reset requested
+   */
+  public async logUserPasswordResetRequested(data: {
+    email: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PasswordResetRequestedEventData = {
+      eventType: CoreAuditableEventType.USER_PASSWORD_RESET_REQUESTED,
+      email: data.email,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: undefined,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_PASSWORD_RESET_REQUESTED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log password reset completed
+   */
+  public async logUserPasswordResetCompleted(data: {
+    userId: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PasswordResetCompletedEventData = {
+      eventType: CoreAuditableEventType.USER_PASSWORD_RESET_COMPLETED,
+      userId: data.userId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PASSWORD_RESET_COMPLETED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // REGISTRATION & VERIFICATION AUDIT METHODS (H5)
+  // ===============================
+
+  /**
+   * Log user registration
+   */
+  public async logUserRegistered(data: {
+    userId: string;
+    email: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_RegisteredEventData = {
+      eventType: CoreAuditableEventType.USER_REGISTERED,
+      userId: data.userId,
+      email: data.email,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_REGISTERED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log email verified
+   */
+  public async logUserEmailVerified(data: {
+    userId: string;
+    email: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_EmailVerifiedEventData = {
+      eventType: CoreAuditableEventType.USER_EMAIL_VERIFIED,
+      userId: data.userId,
+      email: data.email,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_EMAIL_VERIFIED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  public async logUserVerificationEmailResent(data: {
+    userId: string;
+    email: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_VerificationEmailResentEventData = {
+      eventType: CoreAuditableEventType.USER_VERIFICATION_EMAIL_RESENT,
+      userId: data.userId,
+      email: data.email,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_VERIFICATION_EMAIL_RESENT,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // MFA LIFECYCLE AUDIT METHODS (H5)
+  // ===============================
+
+  /**
+   * Log MFA setup started (TOTP enrollment initiated)
+   */
+  public async logUserMFASetupStarted(data: {
+    userId: string;
+    mfaMethod: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_MFASetupStartedEventData = {
+      eventType: CoreAuditableEventType.USER_MFA_SETUP_STARTED,
+      userId: data.userId,
+      mfaMethod: data.mfaMethod,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_MFA_SETUP_STARTED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log MFA setup completed (TOTP enrollment verified)
+   */
+  public async logUserMFASetupCompleted(data: {
+    userId: string;
+    mfaMethod: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_MFASetupCompletedEventData = {
+      eventType: CoreAuditableEventType.USER_MFA_SETUP_COMPLETED,
+      userId: data.userId,
+      mfaMethod: data.mfaMethod,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_MFA_SETUP_COMPLETED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log MFA email OTP sent
+   */
+  public async logUserMFAEmailOTPSent(data: {
+    email: string;
+    sessionId: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_MFAEmailOTPSentEventData = {
+      eventType: CoreAuditableEventType.USER_MFA_EMAIL_OTP_SENT,
+      email: data.email,
+      sessionId: data.sessionId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: undefined,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_MFA_EMAIL_OTP_SENT,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // WEBAUTHN/PASSKEY AUDIT METHODS (Phase G1)
+  // ===============================
+
+  /**
+   * Log passkey registered
+   */
+  public async logUserPasskeyRegistered(data: {
+    userId: string;
+    email: string;
+    credentialId: string;
+    credentialName: string;
+    credentialDeviceType: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PasskeyRegisteredEventData = {
+      eventType: CoreAuditableEventType.USER_PASSKEY_REGISTERED,
+      userId: data.userId,
+      email: data.email,
+      credentialId: data.credentialId,
+      credentialName: data.credentialName,
+      credentialDeviceType: data.credentialDeviceType,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PASSKEY_REGISTERED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log passkey authentication success
+   */
+  public async logUserPasskeyAuthSuccess(data: {
+    userId: string;
+    email: string;
+    credentialId: string;
+    ipAddress: string;
+    userAgent: string;
+    sessionId: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PasskeyAuthSuccessEventData = {
+      eventType: CoreAuditableEventType.USER_PASSKEY_AUTHENTICATION_SUCCESS,
+      userId: data.userId,
+      email: data.email,
+      credentialId: data.credentialId,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_PASSKEY_AUTHENTICATION_SUCCESS,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log passkey authentication failure
+   */
+  public async logUserPasskeyAuthFailure(data: {
+    email: string;
+    failureReason: string;
+    ipAddress: string;
+    userAgent: string;
+    sessionId: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PasskeyAuthFailureEventData = {
+      eventType: CoreAuditableEventType.USER_PASSKEY_AUTHENTICATION_FAILURE,
+      email: data.email,
+      failureReason: data.failureReason,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+      sessionId: data.sessionId,
+    };
+
+    await this._createAuditLog({
+      userId: undefined,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PASSKEY_AUTHENTICATION_FAILURE,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log passkey removed
+   */
+  public async logUserPasskeyRemoved(data: {
+    userId: string;
+    email: string;
+    credentialId: string;
+    credentialName: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PasskeyRemovedEventData = {
+      eventType: CoreAuditableEventType.USER_PASSKEY_REMOVED,
+      userId: data.userId,
+      email: data.email,
+      credentialId: data.credentialId,
+      credentialName: data.credentialName,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PASSKEY_REMOVED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // SCIM USER PROVISIONING AUDIT METHODS (H8)
+  // ===============================
+
+  /**
+   * Log SCIM user provisioned (created)
+   */
+  public async logSCIMUserProvisioned(data: {
+    organizationId: string;
+    userId: string;
+    email: string;
+    isNewUser: boolean;
+    provisionedVia: string;
+    authSource?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_SCIM_UserProvisionedEventData = {
+      eventType: CoreAuditableEventType.SCIM_USER_PROVISIONED,
+      organizationId: data.organizationId,
+      userId: data.userId,
+      email: data.email,
+      isNewUser: data.isNewUser,
+      provisionedVia: data.provisionedVia,
+      authSource: data.authSource,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.SCIM_USER_PROVISIONED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log SCIM user updated (replace or patch)
+   */
+  public async logSCIMUserUpdated(data: {
+    organizationId: string;
+    userId: string;
+    operation: string;
+    updatedAttributes?: string[];
+  }): Promise<void> {
+    const eventData: AuditableEvent_SCIM_UserUpdatedEventData = {
+      eventType: CoreAuditableEventType.SCIM_USER_UPDATED,
+      organizationId: data.organizationId,
+      userId: data.userId,
+      operation: data.operation,
+      updatedAttributes: data.updatedAttributes,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.SCIM_USER_UPDATED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  /**
+   * Log SCIM user deactivated (deleted/deactivated)
+   */
+  public async logSCIMUserDeactivated(data: {
+    organizationId: string;
+    userId: string;
+    email?: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_SCIM_UserDeactivatedEventData = {
+      eventType: CoreAuditableEventType.SCIM_USER_DEACTIVATED,
+      organizationId: data.organizationId,
+      userId: data.userId,
+      email: data.email,
+    };
+
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.SCIM_USER_DEACTIVATED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // Magic Link Events (Phase G2)
+  // ===============================
+
+  public async logMagicLinkSent(data: {
+    email: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_MagicLinkSentEventData = {
+      eventType: CoreAuditableEventType.USER_MAGIC_LINK_SENT,
+      ...data,
+    };
+    await this._createAuditLog({
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_MAGIC_LINK_SENT,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  public async logMagicLinkVerified(data: {
+    userId: string;
+    email: string;
+    sessionId: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_MagicLinkVerifiedEventData = {
+      eventType: CoreAuditableEventType.USER_MAGIC_LINK_VERIFIED,
+      ...data,
+    };
+    await this._createAuditLog({
+      userId: data.userId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_MAGIC_LINK_VERIFIED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  public async logMagicLinkFailed(data: {
+    email?: string;
+    failureReason: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_MagicLinkFailedEventData = {
+      eventType: CoreAuditableEventType.USER_MAGIC_LINK_FAILED,
+      ...data,
+    };
+    await this._createAuditLog({
+      riskLevel: ResourceOperationRiskLevel.HIGH,
+      eventType: CoreAuditableEventType.USER_MAGIC_LINK_FAILED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // SMS OTP Events (Phase G2)
+  // ===============================
+
+  public async logSMSOTPSent(data: {
+    phoneNumber: string;
+    factorLevel: string;
+    sessionId: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_SMSOTPSentEventData = {
+      eventType: CoreAuditableEventType.USER_SMS_OTP_SENT,
+      ...data,
+    };
+    await this._createAuditLog({
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.USER_SMS_OTP_SENT,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  public async logSMSOTPVerified(data: {
+    userId: string;
+    phoneNumber: string;
+    factorLevel: string;
+    sessionId: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_SMSOTPVerifiedEventData = {
+      eventType: CoreAuditableEventType.USER_SMS_OTP_VERIFIED,
+      ...data,
+    };
+    await this._createAuditLog({
+      userId: data.userId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_SMS_OTP_VERIFIED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  public async logSMSOTPFailed(data: {
+    phoneNumber?: string;
+    factorLevel: string;
+    failureReason: string;
+    sessionId: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_SMSOTPFailedEventData = {
+      eventType: CoreAuditableEventType.USER_SMS_OTP_FAILED,
+      ...data,
+    };
+    await this._createAuditLog({
+      riskLevel: ResourceOperationRiskLevel.HIGH,
+      eventType: CoreAuditableEventType.USER_SMS_OTP_FAILED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // Phone Verification Events (Phase G2)
+  // ===============================
+
+  public async logPhoneVerified(data: {
+    userId: string;
+    phoneNumber: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PhoneVerifiedEventData = {
+      eventType: CoreAuditableEventType.USER_PHONE_VERIFIED,
+      ...data,
+    };
+    await this._createAuditLog({
+      userId: data.userId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PHONE_VERIFIED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  public async logPhoneVerificationFailed(data: {
+    phoneNumber: string;
+    failureReason: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const eventData: AuditableEvent_User_PhoneVerificationFailedEventData = {
+      eventType: CoreAuditableEventType.USER_PHONE_VERIFICATION_FAILED,
+      ...data,
+    };
+    await this._createAuditLog({
+      riskLevel: ResourceOperationRiskLevel.HIGH,
+      eventType: CoreAuditableEventType.USER_PHONE_VERIFICATION_FAILED,
+      eventData: eventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // OAuth2 Provider Restriction Events (Phase G3)
+  // ===============================
+
+  /**
+   * Log OAuth2 provider blocked by org-level restrictions.
+   * Emitted at initiation (G3-M4) and callback (G3-M5) enforcement points.
+   */
+  public async logOAuth2ProviderBlocked(data: {
+    email?: string;
+    providerRef: string;
+    organizationId: string;
+    reason: string;
+    ipAddress: string;
+    userAgent: string;
+  }): Promise<void> {
+    const typedEventData: AuditableEvent_OAuth2ProviderBlockedEventData = {
+      eventType: CoreAuditableEventType.OAUTH2_PROVIDER_BLOCKED,
+      email: data.email,
+      providerRef: data.providerRef,
+      organizationId: data.organizationId,
+      reason: data.reason,
+      ipAddress: data.ipAddress,
+      userAgent: data.userAgent,
+    };
+    await this._createAuditLog({
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.OAUTH2_PROVIDER_BLOCKED,
+      eventData: typedEventData as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // METHOD MANAGEMENT AUDIT METHODS (#13f)
+  // ===============================
+
+  public async logUserPasswordChanged(data: {
+    userId: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PASSWORD_CHANGED,
+      eventData: { eventType: CoreAuditableEventType.USER_PASSWORD_CHANGED, userId: data.userId, ipAddress: data.ipAddress, userAgent: data.userAgent } as Record<string, any>,
+    });
+  }
+
+  public async logUserPasswordSet(data: {
+    userId: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_PASSWORD_SET,
+      eventData: { eventType: CoreAuditableEventType.USER_PASSWORD_SET, userId: data.userId, ipAddress: data.ipAddress, userAgent: data.userAgent } as Record<string, any>,
+    });
+  }
+
+  public async logUserTOTPDisabled(data: {
+    userId: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_TOTP_DISABLED,
+      eventData: { eventType: CoreAuditableEventType.USER_TOTP_DISABLED, userId: data.userId, ipAddress: data.ipAddress, userAgent: data.userAgent } as Record<string, any>,
+    });
+  }
+
+  public async logUserIdentityLinkRemoved(data: {
+    userId: string;
+    linkId: string;
+    providerRef: string;
+    ipAddress: string;
+    userAgent: string;
+    organizationId?: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.USER_IDENTITY_LINK_REMOVED,
+      eventData: { eventType: CoreAuditableEventType.USER_IDENTITY_LINK_REMOVED, userId: data.userId, linkId: data.linkId, providerRef: data.providerRef, ipAddress: data.ipAddress, userAgent: data.userAgent } as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // SCIM TOKEN LIFECYCLE EVENTS (Phase H)
+  // ===============================
+
+  public async logSCIMTokenGenerated(data: {
+    tokenId: string;
+    displayName: string;
+    organizationId: string;
+    createdByUserId: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.createdByUserId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.SCIM_TOKEN_GENERATED,
+      eventData: { eventType: CoreAuditableEventType.SCIM_TOKEN_GENERATED, ...data } as Record<string, any>,
+    });
+  }
+
+  public async logSCIMTokenRevoked(data: {
+    tokenId: string;
+    displayName: string;
+    organizationId: string;
+    revokedByUserId: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.revokedByUserId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.SCIM_TOKEN_REVOKED,
+      eventData: { eventType: CoreAuditableEventType.SCIM_TOKEN_REVOKED, ...data } as Record<string, any>,
+    });
+  }
+
+  public async logSCIMTokenRotated(data: {
+    newTokenId: string;
+    oldTokenId: string;
+    organizationId: string;
+    rotatedByUserId: string;
+    overlapHours: number;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.rotatedByUserId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.SCIM_TOKEN_ROTATED,
+      eventData: { eventType: CoreAuditableEventType.SCIM_TOKEN_ROTATED, ...data } as Record<string, any>,
+    });
+  }
+
+  public async logSCIMProvisioningConfigUpdated(data: {
+    organizationId: string;
+    updatedByUserId: string;
+    changes: Record<string, unknown>;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.updatedByUserId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.LOW,
+      eventType: CoreAuditableEventType.SCIM_PROVISIONING_CONFIG_UPDATED,
+      eventData: { eventType: CoreAuditableEventType.SCIM_PROVISIONING_CONFIG_UPDATED, ...data } as Record<string, any>,
+    });
+  }
+
+  public async logSCIMProvisioningFailed(data: {
+    organizationId: string;
+    operation: string;
+    errorMessage: string;
+    userId?: string;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: ResourceOperationRiskLevel.MEDIUM,
+      eventType: CoreAuditableEventType.SCIM_PROVISIONING_FAILED,
+      eventData: { eventType: CoreAuditableEventType.SCIM_PROVISIONING_FAILED, ...data } as Record<string, any>,
+    });
+  }
+
+  // ===============================
+  // SAML AUDIT METHODS (AUTH-2, D13/D19.4)
+  // ===============================
+
+  public async logSAMLEvent(
+    eventType: CoreAuditableEventType,
+    riskLevel: ResourceOperationRiskLevel,
+    data: Record<string, unknown> & { organizationId?: string; userId?: string },
+  ): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel,
+      eventType,
+      eventData: { eventType, ...data } as Record<string, any>,
+    });
+  }
+
+  public async logGenericEvent(data: {
+    userId?: string;
+    organizationId?: string;
+    riskLevel: ResourceOperationRiskLevel;
+    eventType: CoreAuditableEventType | string;
+    eventData: Record<string, unknown>;
+  }): Promise<void> {
+    await this._createAuditLog({
+      userId: data.userId,
+      organizationId: data.organizationId,
+      riskLevel: data.riskLevel,
+      eventType: data.eventType,
+      eventData: { eventType: data.eventType, ...data.eventData } as Record<string, any>,
+    });
+  }
+}