@systima/aiact-audit-log 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,501 @@
+/**
+ * Storage backend interface.
+ *
+ * Abstraction layer for log persistence. v0.1 ships with S3-compatible
+ * storage only; future versions will add Azure Blob, GCS, and local
+ * filesystem backends.
+ */
+interface StorageBackend {
+    write(key: string, data: Buffer): Promise<void>;
+    read(key: string): Promise<Buffer>;
+    list(prefix: string): Promise<string[]>;
+    exists(key: string): Promise<boolean>;
+    getObjectMetadata(key: string): Promise<ObjectMetadata>;
+}
+interface ObjectMetadata {
+    lastModified: Date;
+    size: number;
+}
+interface S3StorageConfig {
+    type: 's3';
+    bucket: string;
+    region: string;
+    prefix?: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+}
+type StorageConfig = S3StorageConfig;
+
+/**
+ * Schema definitions and runtime validation for audit log entries.
+ *
+ * Every field is annotated with the Article paragraph it satisfies.
+ * The schema IS the Article 12 mapping.
+ */
+declare const EVENT_TYPES: readonly ["inference", "tool_call", "tool_result", "human_intervention", "system_event", "session_start", "session_end"];
+type EventType = (typeof EVENT_TYPES)[number];
+declare const CAPTURE_METHODS: readonly ["middleware", "manual", "context"];
+type CaptureMethod = (typeof CAPTURE_METHODS)[number];
+interface InputData {
+    type: 'raw' | 'hash';
+    value: string;
+    tokenCount?: number;
+}
+interface OutputData {
+    type: 'raw' | 'hash';
+    value: string;
+    tokenCount?: number;
+    finishReason?: string;
+}
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface ErrorData {
+    code: string;
+    message: string;
+    stack?: string;
+}
+declare const HUMAN_INTERVENTION_TYPES: readonly ["approval", "rejection", "modification", "override", "escalation"];
+type HumanInterventionType = (typeof HUMAN_INTERVENTION_TYPES)[number];
+interface HumanIntervention {
+    /** @article 12(2)(c), 14(5), 12(3)(d) */
+    type: HumanInterventionType;
+    userId: string;
+    reason?: string;
+    originalOutput?: {
+        type: 'raw' | 'hash';
+        value: string;
+    };
+    timestamp: string;
+}
+interface ToolCallData {
+    toolName: string;
+    toolArgs: Record<string, unknown> | string;
+    toolResult?: string;
+}
+interface MatchResult {
+    matched: boolean;
+    matchConfidence?: number;
+    matchedRecordId?: string;
+}
+interface AuditLogEntry {
+    schemaVersion: 'v1';
+    /** @article 12(1) — unique event identification */
+    entryId: string;
+    /** @article 12(2)(a) — risk identification requires correlating related events */
+    decisionId: string;
+    /** @article 12(1) — system identification */
+    systemId: string;
+    /** @article 12(1), 12(3)(a) — automatic recording, period of each use */
+    timestamp: string;
+    /** @article 12(2)(a) — identifying situations that may present a risk */
+    eventType: EventType;
+    /** @article 12(2)(a), 72 — model version tracking */
+    modelId: string | null;
+    providerId: string | null;
+    /** @article 12(2)(a), 12(2)(c), 12(3)(c) — input context and deployer monitoring */
+    input: InputData;
+    /** @article 12(2)(a), 12(2)(b) — risk identification and post-market monitoring */
+    output: OutputData | null;
+    /** @article 12(2)(b), 72 — performance degradation detection */
+    latencyMs: number | null;
+    /** @article 72 — post-market monitoring (usage tracking) */
+    usage: TokenUsage | null;
+    /** @article 12(2)(a) — identifying situations that may present a risk */
+    error: ErrorData | null;
+    /** @article 12(2)(a) — risk identification requires knowing configuration */
+    parameters: Record<string, unknown> | null;
+    captureMethod: CaptureMethod;
+    /** @article 12(1) — event ordering */
+    seq: number;
+    prevHash: string;
+    hash: string;
+}
+interface AuditLogEntryExtended extends AuditLogEntry {
+    /** @article 12(2)(c), 14(5), 12(3)(d) */
+    humanIntervention?: HumanIntervention;
+    /** @article 12(2)(a) — tracing complex decision chains */
+    stepIndex?: number;
+    parentEntryId?: string;
+    /** @article 12(2)(a) — tool calls as risk vectors */
+    toolCall?: ToolCallData;
+    /** @article 12(3)(b) — reference database for biometric systems */
+    referenceDatabase?: string;
+    /** @article 12(3)(c) — match results for biometric systems */
+    matchResult?: MatchResult;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface LogEntryInput {
+    decisionId?: string;
+    eventType: EventType;
+    modelId: string | null;
+    providerId: string | null;
+    input: {
+        value: string;
+        type?: 'raw' | 'hash';
+        tokenCount?: number;
+    };
+    output: {
+        value: string;
+        type?: 'raw' | 'hash';
+        tokenCount?: number;
+        finishReason?: string;
+    } | null;
+    latencyMs: number | null;
+    usage: TokenUsage | null;
+    parameters: Record<string, unknown> | null;
+    error: ErrorData | null;
+    captureMethod?: CaptureMethod;
+    humanIntervention?: HumanIntervention;
+    stepIndex?: number;
+    parentEntryId?: string;
+    toolCall?: ToolCallData;
+    referenceDatabase?: string;
+    matchResult?: MatchResult;
+    metadata?: Record<string, string | number | boolean>;
+}
+declare class SchemaValidationError extends Error {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
+declare function validateLogEntryInput(entry: LogEntryInput): void;
+declare function validateAuditLogEntry(entry: AuditLogEntry): void;
+
+/**
+ * AuditLogger — core class for structured, tamper-evident audit logging.
+ *
+ * Satisfies Article 12(1): automatic recording of events over the
+ * lifetime of the system. Entries are batched in memory and flushed
+ * to S3-compatible storage with SHA-256 hash chains.
+ */
+
+interface RetentionOptions {
+    minimumDays?: number;
+    acknowledgeSubMinimum?: boolean;
+    autoConfigureLifecycle?: boolean;
+}
+interface PIIOptions {
+    hashInputs?: boolean;
+    hashOutputs?: boolean;
+    redactPatterns?: RegExp[];
+}
+interface BatchingOptions {
+    maxSize?: number;
+    maxDelayMs?: number;
+}
+interface ObjectLockOptions {
+    enabled?: boolean;
+    mode?: 'GOVERNANCE' | 'COMPLIANCE';
+}
+interface HealthCheckOptions {
+    enabled?: boolean;
+    intervalMs?: number;
+    onDrift?: 'warn' | 'throw' | ((drift: ComplianceDrift) => void);
+}
+interface ComplianceDrift {
+    check: string;
+    status: 'fail' | 'warn';
+    message: string;
+}
+type ErrorHandler = 'log-and-continue' | 'throw' | ((error: Error) => void);
+interface AuditLoggerConfig {
+    systemId: string;
+    storage: StorageConfig;
+    retention?: RetentionOptions;
+    pii?: PIIOptions;
+    batching?: BatchingOptions;
+    onError?: ErrorHandler;
+    objectLock?: ObjectLockOptions;
+    healthCheck?: HealthCheckOptions;
+}
+declare class AuditLogger {
+    private readonly config;
+    private readonly systemId;
+    private readonly storage;
+    private readonly storageConfig;
+    private readonly retention;
+    private readonly pii;
+    private readonly batching;
+    private readonly onError;
+    private readonly objectLock;
+    private buffer;
+    private seq;
+    private prevHash;
+    private currentFileIndex;
+    private currentFileSize;
+    private flushTimer;
+    private closed;
+    private initialised;
+    private healthCheckTimer;
+    private shutdownHandler;
+    constructor(config: AuditLoggerConfig);
+    /**
+     * Initialise the logger. Loads chain head from storage,
+     * recovers chain state, and writes initial metadata.
+     *
+     * Must be called before the first log() call. If not called
+     * explicitly, log() will call it lazily.
+     */
+    init(): Promise<void>;
+    /**
+     * Log a single event.
+     *
+     * If no decisionId is provided and no AsyncLocalStorage context is active,
+     * throws MissingDecisionIdError.
+     */
+    log(input: LogEntryInput): Promise<AuditLogEntryExtended>;
+    /**
+     * Force flush all buffered entries to storage.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush remaining entries and release all resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Run a health check against the storage backend.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    getSystemId(): string;
+    getStorageBackend(): StorageBackend;
+    getStorageConfig(): StorageConfig;
+    getCurrentSeq(): number;
+    getPrevHash(): string;
+    /** Exposed for testing with custom storage backends */
+    static createWithStorage(config: Omit<AuditLoggerConfig, 'storage'> & {
+        storage: StorageConfig;
+    }, storage: StorageBackend): AuditLogger;
+    private processInputData;
+    private processOutputData;
+    private redact;
+    private currentDatePath;
+    private currentFilePath;
+    private writeEntries;
+    private persistChainHead;
+    private loadChainHead;
+    private writeMetadata;
+    private scheduleFlush;
+    private clearFlushTimer;
+    private handleError;
+    private setupShutdownHooks;
+    private removeShutdownHooks;
+    private checkWriteAccess;
+    private checkReadAccess;
+    private checkChainHeadConsistency;
+    private checkSchemaVersion;
+}
+interface HealthCheckResult {
+    timestamp: string;
+    checks: HealthCheck[];
+    healthy: boolean;
+}
+interface HealthCheck {
+    name: string;
+    status: 'pass' | 'fail' | 'warn';
+    message: string;
+}
+
+/**
+ * SHA-256 hash chain logic for tamper-evident audit logging.
+ *
+ * Each log entry contains:
+ *   - seq: monotonically increasing sequence number
+ *   - prevHash: SHA-256 hash of the previous entry
+ *   - hash: SHA-256 hash of the current entry (excluding the hash field itself)
+ *
+ * The chain proves ordering and non-modification. Combined with S3 Object Lock,
+ * this provides the tamper-evidence required for trustworthy automatic recording
+ * under Article 12(1).
+ */
+
+interface ChainHead {
+    seq: number;
+    hash: string;
+    systemId: string;
+    updatedAt: string;
+}
+interface ChainVerificationResult {
+    valid: boolean;
+    entriesChecked: number;
+    firstBreak: {
+        seq: number;
+        expectedPrevHash: string;
+        actualPrevHash: string;
+    } | null;
+}
+declare function computeGenesisHash(systemId: string): string;
+declare function computeEntryHash(entry: Omit<AuditLogEntry, 'hash'>): string;
+declare function verifyEntryHash(entry: AuditLogEntry): boolean;
+declare function verifyChain(entries: AuditLogEntry[]): ChainVerificationResult;
+declare function verifyChainFromGenesis(entries: AuditLogEntry[], systemId: string): ChainVerificationResult;
+declare function sha256(data: string): string;
+
+/**
+ * AuditLogReader — query, reconstruct, verify, and analyse audit logs.
+ *
+ * Supports Article 12(2) traceability requirements: given a decision
+ * identifier, reconstruct everything. Given a time range, query and
+ * analyse for post-market monitoring (Article 72).
+ */
+
+interface AuditLogReaderConfig {
+    storage: StorageConfig;
+    systemId: string;
+}
+interface QueryOptions {
+    from?: string;
+    to?: string;
+    eventType?: EventType;
+    decisionId?: string;
+    limit?: number;
+}
+interface ReconstructResult {
+    decisionId: string;
+    entries: AuditLogEntryExtended[];
+    timeline: TimelineEntry[];
+    integrity: {
+        valid: boolean;
+        entriesChecked: number;
+    };
+}
+interface TimelineEntry {
+    timestamp: string;
+    eventType: string;
+    summary: string;
+    entryId: string;
+}
+interface StatsResult {
+    totalEntries: number;
+    byEventType: Record<string, number>;
+    byModel: Record<string, number>;
+    byCaptureMethod: Record<string, number>;
+    errorRate: number;
+    avgLatencyMs: number | null;
+    p95LatencyMs: number | null;
+    p99LatencyMs: number | null;
+    tokenUsage: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+}
+declare class AuditLogReader {
+    private readonly storage;
+    private readonly systemId;
+    constructor(config: AuditLogReaderConfig);
+    static createWithStorage(config: AuditLogReaderConfig, storage: StorageBackend): AuditLogReader;
+    getStorageBackend(): StorageBackend;
+    query(options?: QueryOptions): Promise<AuditLogEntryExtended[]>;
+    reconstruct(decisionId: string): Promise<ReconstructResult>;
+    verifyChain(options?: {
+        from?: string;
+        to?: string;
+    }): Promise<ChainVerificationResult>;
+    stats(options?: {
+        from?: string;
+        to?: string;
+    }): Promise<StatsResult>;
+    private loadEntries;
+    private loadAllEntries;
+    private getDatePrefixes;
+}
+
+/**
+ * AsyncLocalStorage-based context propagation for audit logging.
+ *
+ * Allows decision IDs and metadata to flow through async call chains
+ * without manual threading. This reduces the integration burden that
+ * leads to coverage gaps.
+ */
+interface AuditContext {
+    decisionId: string;
+    parentDecisionId?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+declare function withAuditContext<T>(context: AuditContext, callback: () => T | Promise<T>): T | Promise<T>;
+declare function getAuditContext(): AuditContext | undefined;
+declare class MissingDecisionIdError extends Error {
+    constructor();
+}
+
+/**
+ * Coverage diagnostic — analyses logs for completeness gaps.
+ *
+ * Addresses the core feedback: the real compliance risk is not the
+ * schema but incomplete instrumentation. This module makes logging
+ * gaps visible.
+ */
+
+interface CoverageReport {
+    period: {
+        from: string;
+        to: string;
+    };
+    totalEntries: number;
+    byEventType: Record<string, {
+        count: number;
+        percentage: number;
+    }>;
+    byCaptureMethod: Record<string, {
+        count: number;
+        percentage: number;
+    }>;
+    warnings: CoverageWarning[];
+    recommendations: string[];
+}
+interface CoverageWarning {
+    severity: 'high' | 'medium' | 'low';
+    code: string;
+    message: string;
+}
+interface CoverageOptions {
+    from?: string;
+    to?: string;
+}
+declare function analyseCoverage(entries: AuditLogEntryExtended[], options?: CoverageOptions): CoverageReport;
+
+/**
+ * Custom error types for the audit logger.
+ */
+declare class ComplianceConfigError extends Error {
+    constructor(message: string);
+}
+declare class ComplianceDriftError extends Error {
+    constructor(message: string);
+}
+declare class StorageError extends Error {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+declare class ChainIntegrityError extends Error {
+    readonly seq: number;
+    constructor(message: string, seq: number);
+}
+
+/**
+ * In-memory storage backend for testing.
+ *
+ * Not for production use. This backend stores everything in memory
+ * and is used by the test suite to avoid requiring an S3 endpoint.
+ */
+
+declare class MemoryStorage implements StorageBackend {
+    private readonly store;
+    write(key: string, data: Buffer): Promise<void>;
+    read(key: string): Promise<Buffer>;
+    list(prefix: string): Promise<string[]>;
+    exists(key: string): Promise<boolean>;
+    getObjectMetadata(key: string): Promise<ObjectMetadata>;
+    clear(): void;
+    getAll(): Map<string, Buffer>;
+}
+
+export { type AuditContext, type AuditLogEntry, type AuditLogEntryExtended, AuditLogReader, type AuditLogReaderConfig, AuditLogger, type AuditLoggerConfig, type BatchingOptions, CAPTURE_METHODS, type CaptureMethod, type ChainHead, ChainIntegrityError, type ChainVerificationResult, ComplianceConfigError, type ComplianceDrift, ComplianceDriftError, type CoverageOptions, type CoverageReport, type CoverageWarning, EVENT_TYPES, type ErrorData, type ErrorHandler, type EventType, HUMAN_INTERVENTION_TYPES, type HealthCheck, type HealthCheckOptions, type HealthCheckResult, type HumanIntervention, type HumanInterventionType, type InputData, type LogEntryInput, type MatchResult, MemoryStorage, MissingDecisionIdError, type ObjectLockOptions, type ObjectMetadata, type OutputData, type PIIOptions, type QueryOptions, type ReconstructResult, type RetentionOptions, type S3StorageConfig, SchemaValidationError, type StatsResult, type StorageBackend, type StorageConfig, StorageError, type TimelineEntry, type TokenUsage, type ToolCallData, analyseCoverage, computeEntryHash, computeGenesisHash, getAuditContext, sha256, validateAuditLogEntry, validateLogEntryInput, verifyChain, verifyChainFromGenesis, verifyEntryHash, withAuditContext };