@kya-os/mcp-i 1.11.1 → 1.12.0

package/dist/runtime/audit.d.ts

@@ -1,430 +0,0 @@
-/**
- * Audit Logging System for MCP-I Runtime
- *
- * TODO: Update AuditLogger to implement IAuditLogger from @kya-os/mcp-i-core/runtime/audit-logger.
- * Currently using Node.js-specific implementation. This will allow the interface to be used
- * across all platform implementations while maintaining platform-specific crypto implementations.
- *
- * Handles audit record generation and logging with frozen format
- * according to requirements 5.4, 5.5, and 6.7 (configurable retention).
- *
- * ## Privacy Guarantees
- *
- * This system is designed with privacy-first principles:
- *
- * **NEVER Logged:**
- * - Request/response bodies (only SHA-256 hashes)
- * - Secrets (private keys, API keys, tokens, nonces)
- * - PII (names, emails, addresses, phone numbers)
- * - Key material (only key IDs are logged)
- *
- * **ALWAYS Logged:**
- * - Metadata only (DIDs, key IDs, timestamps)
- * - SHA-256 hashes (not plaintext data)
- * - Session IDs (for correlation, not sensitive)
- * - Verification results (yes/no only)
- * - Scope identifiers (application-level)
- *
- * ## Frozen Format
- *
- * The audit.v1 format is **frozen** and will not change:
- *
- * ```
- * audit.v1 ts=<unix> session=<id> audience=<host> did=<did> kid=<kid> reqHash=<sha256:..> resHash=<sha256:..> verified=yes|no scope=<scopeId|->
- * ```
- *
- * ## Event-Driven Rotation
- *
- * This implementation uses **event-driven rotation** (not timers):
- * - Rotation checks happen on each `logAuditRecord()` call
- * - No setInterval/setTimeout (works in Cloudflare Workers)
- * - No cleanup needed (no timers to clear)
- * - Predictable behavior (rotation on activity)
- *
- * @module audit
- * @see {@link https://github.com/kya-os/xmcp-i/docs/concepts/audit-logging.md | Audit Logging Documentation}
- */
-import type { AuditRecord } from "@kya-os/mcp/types" with { "resolution-mode": "import" };
-import { SessionContext } from "@kya-os/contracts/handshake";
-import { AgentIdentity } from "./identity";
-/**
- * Audit log rotation strategy
- */
-export type AuditRotationStrategy = "size" | "time" | "count" | "custom";
-/**
- * Audit rotation context passed to hooks
- */
-export interface AuditRotationContext {
-    strategy: AuditRotationStrategy;
-    trigger: string;
-    recordsLogged: number;
-    timestamp: number;
-}
-/**
- * Audit log rotation hooks
- */
-export interface AuditRotationHooks {
-    /**
-     * Called when audit log should be rotated
-     * @param context - Rotation context with metadata
-     * @returns Promise that resolves when rotation is complete
-     */
-    onRotation?: (context: AuditRotationContext) => Promise<void>;
-    /**
-     * Called when audit log reaches size limit
-     * @param sizeBytes - Current size in bytes
-     * @param limit - Size limit that was exceeded
-     */
-    onSizeLimit?: (sizeBytes: number, limit: number) => Promise<void>;
-    /**
-     * Called on time-based rotation (e.g., daily, hourly)
-     * @param interval - Rotation interval that triggered (e.g., "daily", "hourly")
-     */
-    onTimeBased?: (interval: string) => Promise<void>;
-    /**
-     * Called when record count reaches threshold
-     * @param count - Number of records logged
-     * @param threshold - Count threshold that was exceeded
-     */
-    onCountThreshold?: (count: number, threshold: number) => Promise<void>;
-}
-/**
- * Audit logging configuration
- *
- * @example Basic configuration
- * ```typescript
- * const config: AuditConfig = {
- *   enabled: true,
- *   logFunction: console.log,
- *   includePayloads: false, // ALWAYS false for privacy
- * };
- * ```
- *
- * @example With rotation
- * ```typescript
- * const config: AuditConfig = {
- *   enabled: true,
- *   rotation: {
- *     strategy: 'size',
- *     sizeLimit: 10 * 1024 * 1024, // 10 MB
- *     hooks: {
- *       onRotation: async (context) => {
- *         // Archive old log file
- *       },
- *     },
- *   },
- * };
- * ```
- */
-export interface AuditConfig {
-    /**
-     * Enable audit logging (default: true)
-     */
-    enabled?: boolean;
-    /**
-     * Custom log function (default: console.log)
-     *
-     * @param record - The formatted audit line (frozen format)
-     *
-     * @example File-based logging
-     * ```typescript
-     * logFunction: (record) => {
-     *   fs.appendFileSync('/var/log/audit.log', record + '\n');
-     * }
-     * ```
-     */
-    logFunction?: (record: string) => void;
-    /**
-     * Include payloads in logs (default: false)
-     *
-     * **WARNING:** This should ALWAYS be false. The frozen format ensures
-     * that even if set to true, no request/response bodies will be logged.
-     * This flag exists for compatibility but has no effect on the frozen format.
-     *
-     * @deprecated This flag has no effect due to frozen format privacy guarantees
-     */
-    includePayloads?: boolean;
-    /**
-     * Log rotation configuration (event-driven, no timers)
-     */
-    rotation?: {
-        /**
-         * Rotation strategy
-         * - 'size': Rotate when log reaches size limit (checked on each call)
-         * - 'time': Rotate based on elapsed time (checked on each call)
-         * - 'count': Rotate after N records
-         * - 'custom': Custom rotation logic via hooks only
-         */
-        strategy?: AuditRotationStrategy;
-        /**
-         * Size limit in bytes (for size-based rotation)
-         *
-         * @example 10 MB limit
-         * ```typescript
-         * sizeLimit: 10 * 1024 * 1024
-         * ```
-         */
-        sizeLimit?: number;
-        /**
-         * Time interval in milliseconds (for time-based rotation)
-         * Rotation is checked on each logAuditRecord() call, not via timer.
-         *
-         * @example Daily rotation
-         * ```typescript
-         * timeInterval: 24 * 60 * 60 * 1000
-         * ```
-         */
-        timeInterval?: number;
-        /**
-         * Record count threshold (for count-based rotation)
-         *
-         * @example Rotate after 10k records
-         * ```typescript
-         * countThreshold: 10000
-         * ```
-         */
-        countThreshold?: number;
-        /**
-         * Custom rotation hooks
-         */
-        hooks?: AuditRotationHooks;
-    };
-}
-/**
- * Audit context for logging
- *
- * Contains all metadata needed to generate an audit record.
- *
- * **Privacy Note:** Only metadata is extracted from these objects.
- * The identity's private key, session's nonce, and other sensitive
- * fields are NEVER included in the audit log.
- *
- * @example
- * ```typescript
- * const context: AuditContext = {
- *   identity: {
- *     did: 'did:web:example.com:agents:agent-1',
- *     keyId: 'key-20241014-abc123',
- *     // ... private key NOT logged
- *   },
- *   session: {
- *     sessionId: 'sess_abc123',
- *     audience: 'example.com',
- *     // ... nonce NOT logged
- *   },
- *   requestHash: 'sha256:1234567890abcdef...',
- *   responseHash: 'sha256:fedcba0987654321...',
- *   verified: 'yes',
- *   scopeId: 'orders.create',
- * };
- * ```
- */
-export interface AuditContext {
-    /**
-     * Agent identity
-     *
-     * Only `did` and `keyId` are logged. Private key is NEVER logged.
-     */
-    identity: AgentIdentity;
-    /**
-     * Session context
-     *
-     * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
-     */
-    session: SessionContext;
-    /**
-     * Request hash (SHA-256 with `sha256:` prefix)
-     *
-     * @example 'sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
-     */
-    requestHash: string;
-    /**
-     * Response hash (SHA-256 with `sha256:` prefix)
-     *
-     * @example 'sha256:fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321'
-     */
-    responseHash: string;
-    /**
-     * Verification result
-     *
-     * - 'yes': Proof was verified successfully
-     * - 'no': Proof verification failed
-     */
-    verified: "yes" | "no";
-    /**
-     * Optional scope identifier
-     *
-     * Application-level scope (e.g., 'orders.create', 'users.read').
-     * If not provided, '-' is used in the audit log.
-     *
-     * @example 'orders.create'
-     */
-    scopeId?: string;
-}
-/**
- * Event context for logging events that bypass session deduplication
- *
- * Used for consent events where multiple events occur in the same session.
- * Unlike AuditContext, this allows multiple events per session.
- */
-export interface AuditEventContext {
-    /**
-     * Event type identifier
-     *
-     * @example "consent:page_viewed", "consent:approved", "runtime:initialized"
-     */
-    eventType: string;
-    /**
-     * Agent identity
-     *
-     * Only `did` and `keyId` are logged. Private key is NEVER logged.
-     */
-    identity: AgentIdentity;
-    /**
-     * Session context
-     *
-     * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
-     */
-    session: SessionContext;
-    /**
-     * Optional event-specific data
-     *
-     * Used for generating event hash. Not logged directly.
-     */
-    eventData?: Record<string, any>;
-}
-/**
- * Audit logger class with event-driven rotation support
- *
- * Privacy Guarantees:
- * - NEVER logs request/response bodies (only SHA-256 hashes)
- * - NEVER logs secrets (private keys, API keys, tokens, nonces)
- * - NEVER logs PII (personal information)
- * - Only logs metadata: DIDs, key IDs, timestamps, hashes, session IDs
- * - Frozen format: audit.v1 with fixed field order
- *
- * Rotation Strategy:
- * - Event-driven (no timers) - rotation checks on each logAuditRecord() call
- * - Works in all environments (Node.js, Cloudflare Workers, Vercel Edge)
- * - No cleanup needed (no timers to clear)
- */
-export declare class AuditLogger {
-    private config;
-    private sessionAuditLog;
-    private totalRecordsLogged;
-    private currentLogSize;
-    private lastRotationTime;
-    private destroyed;
-    constructor(config?: AuditConfig);
-    /**
-     * Emit audit record on first call per session
-     * Requirements: 5.4, 5.5
-     *
-     * This method:
-     * 1. Checks if logger is destroyed
-     * 2. Logs audit record (first call per session)
-     * 3. Checks if rotation is needed (event-driven)
-     * 4. Triggers rotation hooks if threshold met
-     */
-    logAuditRecord(context: AuditContext): Promise<void>;
-    /**
-     * Log an event using the frozen audit format WITHOUT session deduplication.
-     *
-     * Unlike logAuditRecord(), this method ALWAYS logs the event, regardless
-     * of whether an event has already been logged for this session. This is
-     * necessary for consent events where multiple events occur in the same session.
-     *
-     * The event still uses the frozen audit.v1 format for consistency, but
-     * bypasses the "once per session" constraint.
-     *
-     * @param context - Event context including eventType, identity, session, and eventData
-     */
-    logEvent(context: AuditEventContext): Promise<void>;
-    /**
-     * Generate deterministic hash for event
-     */
-    private hashEvent;
-    /**
-     * Format audit record as frozen audit line
-     * Format: audit.v1 ts=<unix> session=<id> audience=<host> did=<did> kid=<kid> reqHash=<sha256:..> resHash=<sha256:..> verified=yes|no scope=<scopeId|->
-     */
-    private formatAuditLine;
-    /**
-     * Check if rotation is needed and trigger if necessary (event-driven)
-     *
-     * This method is called on each logAuditRecord() call.
-     * No timers are used - rotation is checked based on current state.
-     */
-    private checkRotation;
-    /**
-     * Rotate audit log now (manually triggered)
-     *
-     * This method:
-     * 1. Calls onRotation hook (for user to archive/rotate log file)
-     * 2. Resets rotation counters (size, time, count)
-     *
-     * @param trigger - Reason for rotation (e.g., "manual", "size-limit")
-     */
-    rotateNow(trigger?: string): Promise<void>;
-    /**
-     * Destroy audit logger and cleanup resources
-     *
-     * This method:
-     * 1. Clears session tracking (memory)
-     * 2. Resets statistics
-     * 3. Marks logger as destroyed
-     *
-     * Note: No timers to clear (event-driven rotation)
-     */
-    destroy(): void;
-    /**
-     * Clear session audit log (useful for testing)
-     */
-    clearSessionLog(): void;
-    /**
-     * Get audit statistics
-     */
-    getStats(): {
-        enabled: boolean;
-        sessionsLogged: number;
-        includePayloads: boolean;
-        totalRecordsLogged: number;
-        currentLogSize: number;
-        lastRotationTime: number;
-    };
-    /**
-     * Update configuration
-     */
-    updateConfig(config: Partial<AuditConfig>): void;
-}
-/**
- * Key rotation audit logging
- */
-export interface KeyRotationAuditContext {
-    identity: AgentIdentity;
-    oldKeyId: string;
-    newKeyId: string;
-    mode: "dev" | "prod";
-    delegated: "yes" | "no";
-    force: "yes" | "no";
-}
-/**
- * Log key rotation audit record
- * Format: keys.rotate.v1 ts=<unix> did=<did> oldKid=<kid> newKid=<kid> mode=dev|prod delegated=yes|no force=yes|no
- */
-export declare function logKeyRotationAudit(context: KeyRotationAuditContext, logFunction?: (record: string) => void): void;
-/**
- * Default audit logger instance
- */
-export declare const defaultAuditLogger: AuditLogger;
-/**
- * Utility functions
- */
-/**
- * Parse audit line back to record (for testing/analysis)
- */
-export declare function parseAuditLine(line: string): AuditRecord | null;
-/**
- * Validate audit record format
- */
-export declare function validateAuditRecord(record: any): record is AuditRecord;