@kya-os/mcp-i 1.5.3-canary.0 → 1.5.4

package/dist/runtime/audit.d.ts

@@ -1,41 +1,294 @@
 /**
- * Audit Logging System for XMCP-I Runtime
+ * Audit Logging System for MCP-I Runtime
  *
  * Handles audit record generation and logging with frozen format
- * according to requirements 5.4, 5.5.
+ * 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 { AuditRecord } from "@kya-os/contracts/proof";
 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;
 }
 /**
- * Audit logger class
+ * 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>;
     /**
@@ -43,6 +296,34 @@ export declare class AuditLogger {
      * 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)
      */
@@ -54,6 +335,9 @@ export declare class AuditLogger {
         enabled: boolean;
         sessionsLogged: number;
         includePayloads: boolean;
+        totalRecordsLogged: number;
+        currentLogSize: number;
+        lastRotationTime: number;
     };
     /**
      * Update configuration

package/dist/runtime/audit.js

@@ -1,34 +1,104 @@
 "use strict";
 /**
- * Audit Logging System for XMCP-I Runtime
+ * Audit Logging System for MCP-I Runtime
  *
  * Handles audit record generation and logging with frozen format
- * according to requirements 5.4, 5.5.
+ * 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}
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultAuditLogger = exports.AuditLogger = void 0;
 exports.logKeyRotationAudit = logKeyRotationAudit;
 exports.parseAuditLine = parseAuditLine;
 exports.validateAuditRecord = validateAuditRecord;
+const time_1 = require("./utils/time");
 /**
- * Audit logger class
+ * 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)
  */
 class AuditLogger {
     config;
     sessionAuditLog = new Set(); // Track first call per session
+    totalRecordsLogged = 0; // Total records logged (for count rotation)
+    currentLogSize = 0; // Current log size in bytes (for size rotation)
+    lastRotationTime = Date.now(); // Last rotation timestamp (for time rotation)
+    destroyed = false; // Track if logger has been destroyed
     constructor(config = {}) {
+        // Merge rotation config carefully to preserve defaults
+        const rotationConfig = config.rotation
+            ? {
+                strategy: "custom",
+                ...config.rotation,
+            }
+            : undefined;
         this.config = {
             enabled: true,
             logFunction: console.log,
             includePayloads: false, // Keep identity/proof data out by default
             ...config,
+            rotation: rotationConfig,
         };
     }
     /**
      * 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
      */
     async logAuditRecord(context) {
+        if (this.destroyed) {
+            throw new Error("AuditLogger has been destroyed");
+        }
         if (!this.config.enabled) {
             return;
         }
@@ -46,7 +116,7 @@ class AuditLogger {
             session: context.session.sessionId,
             audience: context.session.audience,
             did: context.identity.did,
-            kid: context.identity.keyId,
+            kid: context.identity.kid,
             reqHash: context.requestHash,
             resHash: context.responseHash,
             verified: context.verified,
@@ -54,8 +124,14 @@ class AuditLogger {
         };
         // Format as frozen audit line
         const auditLine = this.formatAuditLine(auditRecord);
+        // Track size in bytes (UTF-8)
+        const sizeBytes = Buffer.byteLength(auditLine, "utf8");
+        this.currentLogSize += sizeBytes;
+        this.totalRecordsLogged++;
         // Emit audit record
         this.config.logFunction(auditLine);
+        // Check if rotation is needed (event-driven)
+        await this.checkRotation();
     }
     /**
      * Format audit record as frozen audit line
@@ -76,6 +152,92 @@ class AuditLogger {
         ];
         return fields.join(" ");
     }
+    /**
+     * 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.
+     */
+    async checkRotation() {
+        if (!this.config.rotation) {
+            return;
+        }
+        const { strategy, sizeLimit, timeInterval, countThreshold, hooks } = this.config.rotation;
+        let shouldRotate = false;
+        let trigger = "";
+        // Size-based rotation
+        if (strategy === "size" && sizeLimit && this.currentLogSize >= sizeLimit) {
+            shouldRotate = true;
+            trigger = "size-limit";
+            await hooks?.onSizeLimit?.(this.currentLogSize, sizeLimit);
+        }
+        // Time-based rotation (event-driven, not timer-based)
+        if (strategy === "time" &&
+            timeInterval &&
+            Date.now() - this.lastRotationTime >= timeInterval) {
+            shouldRotate = true;
+            trigger = "time-interval";
+            const interval = (0, time_1.formatTimeInterval)(timeInterval);
+            await hooks?.onTimeBased?.(interval);
+        }
+        // Count-based rotation
+        if (strategy === "count" &&
+            countThreshold &&
+            this.totalRecordsLogged >= countThreshold) {
+            shouldRotate = true;
+            trigger = "count-threshold";
+            await hooks?.onCountThreshold?.(this.totalRecordsLogged, countThreshold);
+        }
+        // Trigger rotation if needed
+        if (shouldRotate) {
+            await this.rotateNow(trigger);
+        }
+    }
+    /**
+     * 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")
+     */
+    async rotateNow(trigger = "manual") {
+        if (!this.config.rotation?.hooks?.onRotation) {
+            return;
+        }
+        const context = {
+            strategy: this.config.rotation.strategy || "custom",
+            trigger,
+            recordsLogged: this.totalRecordsLogged,
+            timestamp: Date.now(),
+        };
+        // Call rotation hook (user implements log file rotation)
+        await this.config.rotation.hooks.onRotation(context);
+        // Reset rotation counters
+        this.currentLogSize = 0;
+        this.lastRotationTime = Date.now();
+        this.totalRecordsLogged = 0;
+    }
+    /**
+     * 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() {
+        if (this.destroyed) {
+            return; // Idempotent
+        }
+        this.sessionAuditLog.clear();
+        this.totalRecordsLogged = 0;
+        this.currentLogSize = 0;
+        this.destroyed = true;
+    }
     /**
      * Clear session audit log (useful for testing)
      */
@@ -90,6 +252,9 @@ class AuditLogger {
             enabled: this.config.enabled,
             sessionsLogged: this.sessionAuditLog.size,
             includePayloads: this.config.includePayloads,
+            totalRecordsLogged: this.totalRecordsLogged,
+            currentLogSize: this.currentLogSize,
+            lastRotationTime: this.lastRotationTime,
         };
     }
     /**

package/dist/runtime/auth-handshake.d.ts

@@ -136,7 +136,7 @@ export declare class MemoryResumeTokenStore implements ResumeTokenStore {
  * @param resumeToken - Optional resume token from previous authorization
  * @returns Verification result with delegation or auth error
  */
-export declare function verifyOrHints(agentDid: string, scopes: string[], config: AuthHandshakeConfig, resumeToken?: string): Promise<VerifyOrHintsResult>;
+export declare function verifyOrHints(agentDid: string, scopes: string[], config: AuthHandshakeConfig, _resumeToken?: string): Promise<VerifyOrHintsResult>;
 /**
  * Helper: Check if scopes are sensitive and require authorization
  *

package/dist/runtime/auth-handshake.js

@@ -81,7 +81,7 @@ exports.MemoryResumeTokenStore = MemoryResumeTokenStore;
  * @param resumeToken - Optional resume token from previous authorization
  * @returns Verification result with delegation or auth error
  */
-async function verifyOrHints(agentDid, scopes, config, resumeToken) {
+async function verifyOrHints(agentDid, scopes, config, _resumeToken) {
     const startTime = Date.now();
     if (config.debug) {
         console.log(`[AuthHandshake] Verifying ${agentDid} for scopes: ${scopes.join(', ')}`);

package/dist/runtime/debug.d.ts

@@ -16,7 +16,7 @@ export interface DebugVerificationResult {
     signature: {
         valid: boolean;
         algorithm: string;
-        keyId: string;
+        kid: string;
     };
     proof: {
         valid: boolean;
@@ -43,7 +43,7 @@ export interface DebugVerificationResult {
 export interface DebugPageData {
     identity: {
         did: string;
-        keyId: string;
+        kid: string;
         didDocumentUrl: string;
     };
     registry: {

package/dist/runtime/debug.js

@@ -46,7 +46,7 @@ class DebugManager {
         const data = {
             identity: {
                 did: this.identity.did,
-                keyId: this.identity.keyId,
+                kid: this.identity.kid,
                 didDocumentUrl: this.generateDIDDocumentUrl(this.identity.did),
             },
             registry: {
@@ -115,7 +115,7 @@ class DebugManager {
             signature: {
                 valid: false,
                 algorithm: "EdDSA",
-                keyId: proof.meta.kid,
+                kid: proof.meta.kid,
             },
             proof: {
                 valid: false,
@@ -366,7 +366,7 @@ class DebugManager {
                     </div>
                     <div class="field">
                         <label>Key ID</label>
-                        <div class="value">${data.identity.keyId}</div>
+                        <div class="value">${data.identity.kid}</div>
                     </div>
                     <div class="field">
                         <label>DID Document</label>

package/dist/runtime/delegation/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Delegation Module Exports
+ *
+ * W3C VC-based delegation issuance and verification
+ */
+export * from './vc-issuer';
+export * from './vc-verifier';

package/dist/runtime/delegation/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Delegation Module Exports
+ *
+ * W3C VC-based delegation issuance and verification
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./vc-issuer"), exports);
+__exportStar(require("./vc-verifier"), exports);