// src/core/security/IAuditEvent.ts

/**
 * Audit Event - Immutable record of a security-relevant action.
 *
 * Vision 27 Section 7.1: "All security-relevant events MUST be auditable"
 *
 * Expert consensus:
 * - Complete trail for compliance (SOC2, GDPR, HIPAA)
 * - Capability lineage for forensics
 * - Cross-realm correlation for federation
 *
 * See: Vision/27-SECURITY-FEDERATION-DRAFT.md Section 7.1
 */

// ═══════════════════════════════════════════════════════════════════════════
// AUDIT EVENT TYPES
// ═══════════════════════════════════════════════════════════════════════════

/**
 * Audit action types - what operation was attempted.
 *
 * Security-critical actions (always logged at 100%):
 * - 'spawn', 'context-create', 'interpreter'
 *
 * Configurable actions (per-realm audit level):
 * - 'invoke', 'emit', 'read', 'write'
 */
export type AuditAction =
  | 'invoke'
  | 'emit'
  | 'read'
  | 'write'
  | 'spawn'
  | 'context-create'
  | 'interpreter'
  | 'capability-mint'
  | 'capability-attenuate'
  | 'capability-revoke'
  | 'capability-verify';

/**
 * Outcome of the audited action.
 */
export type AuditOutcome = 'success' | 'denied' | 'error';

/**
 * Data classification for compliance.
 * Per GDPR/HIPAA requirements.
 */
export type DataClassification = 'public' | 'internal' | 'confidential' | 'restricted';

// ═══════════════════════════════════════════════════════════════════════════
// AUDIT EVENT INTERFACE
// ═══════════════════════════════════════════════════════════════════════════

/**
 * Audit event - immutable record of security action.
 *
 * Vision 27 Section 7.1:
 * ```
 * interface AuditEvent {
 *   eventId: string;
 *   timestamp: number;
 *   principal: string;
 *   capability: string;
 *   action: string;
 *   target: string;
 *   outcome: 'success' | 'denied' | 'error';
 *   ...
 * }
 * ```
 */
export interface IAuditEvent {
  // ─────────────────────────────────────────────────────────────────────────
  // Identity
  // ─────────────────────────────────────────────────────────────────────────

  /** Unique event ID (e.g., 'audit-1702500000000-abc123') */
  eventId: string;

  /** High-precision timestamp (ms since epoch) */
  timestamp: number;

  // ─────────────────────────────────────────────────────────────────────────
  // Who
  // ─────────────────────────────────────────────────────────────────────────

  /** Who initiated (mount path or identity) */
  principal: string;

  /** Capability ID used (if any) */
  capability?: string;

  /** How they got the capability (delegation chain) */
  delegationChain?: string[];

  // ─────────────────────────────────────────────────────────────────────────
  // What
  // ─────────────────────────────────────────────────────────────────────────

  /** Action attempted */
  action: AuditAction;

  /** Mount path of target */
  target: string;

  /** Specific command if invoke */
  command?: string;

  // ─────────────────────────────────────────────────────────────────────────
  // Context
  // ─────────────────────────────────────────────────────────────────────────

  /** Where request originated */
  sourceRealm: string;

  /** Where request went */
  targetRealm: string;

  /** Trust level (1-5) */
  trustLevel?: number;

  // ─────────────────────────────────────────────────────────────────────────
  // Outcome
  // ─────────────────────────────────────────────────────────────────────────

  /** Result of the action */
  outcome: AuditOutcome;

  /** Why denied (if applicable) */
  denialReason?: string;

  /** Error info (if applicable) */
  errorDetails?: string;

  // ─────────────────────────────────────────────────────────────────────────
  // Compliance
  // ─────────────────────────────────────────────────────────────────────────

  /** Data classification for compliance */
  dataClassification?: DataClassification;

  /** Retention policy identifier */
  retentionPolicy?: string;
}

// ═══════════════════════════════════════════════════════════════════════════
// AUDIT EVENT SUMMARY (for 'summary' mode)
// ═══════════════════════════════════════════════════════════════════════════

/**
 * Summary audit event - reduced detail for 'summary' audit level.
 *
 * Vision 27 Section 7.3:
 * - Summary mode logs WHAT happened, not full context
 * - Useful for high-volume internal operations
 */
export interface IAuditEventSummary {
  eventId: string;
  timestamp: number;
  principal: string;
  action: AuditAction;
  target: string;
  outcome: AuditOutcome;
  denialReason?: string;
}
