@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.0

package/src/runtime/base.ts

@@ -0,0 +1,1329 @@
+/**
+ * MCPIRuntimeBase - Provider-based runtime
+ *
+ * Core runtime that accepts providers for all platform-specific operations.
+ * This enables the same runtime logic to work across Node.js, Cloudflare Workers,
+ * and other platforms.
+ */
+
+import {
+  CryptoProvider,
+  ClockProvider,
+  FetchProvider,
+  StorageProvider,
+  NonceCacheProvider,
+  IdentityProvider,
+  AgentIdentity,
+} from "../providers/base";
+import { DelegationRequiredError } from "../types/tool-protection.js";
+import { CryptoService, type Ed25519JWK } from "../services/crypto.service.js";
+import { ProofVerifier } from "../services/proof-verifier.js";
+import type { DetachedProof } from "@kya-os/contracts/proof";
+import type {
+  DIDDocument,
+  AgentDocument,
+  MCPIdentity,
+  WellKnownConfig,
+  WellKnownResponse,
+} from "@kya-os/contracts/well-known";
+import type { AccessControlApiService } from "../services/access-control.service.js";
+import type { VerifyDelegationRequest } from "@kya-os/contracts/agentshield-api";
+import { AgentShieldAPIError } from "@kya-os/contracts/agentshield-api";
+
+// Import the new provider runtime config
+import type { ProviderRuntimeConfig } from "../config";
+import { UserDidManager } from "../identity/user-did-manager";
+import type { InterceptedToolCall } from "../types/tool-protection.js";
+
+/**
+ * Interface for runtime instances that have AccessControlApiService available
+ * This allows type-safe access to the access control service without using `as any`
+ *
+ * @deprecated AccessControlApiService is now directly available as protected property on MCPIRuntimeBase
+ */
+export interface RuntimeWithAccessControl {
+  accessControlService?: AccessControlApiService;
+}
+
+export class MCPIRuntimeBase {
+  protected crypto: CryptoProvider;
+  protected clock: ClockProvider;
+  protected fetch: FetchProvider;
+  protected storage: StorageProvider;
+  protected nonceCache: NonceCacheProvider;
+  protected identity: IdentityProvider;
+  protected config: ProviderRuntimeConfig;
+  private cachedIdentity?: AgentIdentity;
+  private sessions: Map<string, any> = new Map();
+  private lastProof?: any;
+  private userDidManager?: UserDidManager;
+  private interceptedCalls: Map<string, any> = new Map(); // Store intercepted tool calls by resume token
+  private cryptoService?: CryptoService;
+  protected proofVerifier?: ProofVerifier; // Optional ProofVerifier (injected by subclasses)
+  protected accessControlService?: AccessControlApiService; // Optional AccessControlApiService (injected by subclasses)
+
+  constructor(config: ProviderRuntimeConfig) {
+    this.config = config;
+    this.crypto = config.cryptoProvider;
+    this.clock = config.clockProvider;
+    this.fetch = config.fetchProvider;
+    this.storage = config.storageProvider;
+    this.nonceCache = config.nonceCacheProvider;
+    this.identity = config.identityProvider;
+    // Initialize CryptoService for JWS verification
+    this.cryptoService = new CryptoService(this.crypto);
+  }
+
+  /**
+   * Initialize the runtime
+   */
+  async initialize(): Promise<void> {
+    // Load or generate identity
+    this.cachedIdentity = await this.identity.getIdentity();
+
+    // Initialize user DID manager if identity config enables it
+    if (this.config.identity?.generateUserDids) {
+      this.userDidManager = new UserDidManager({
+        crypto: this.crypto,
+        storage: this.config.identity?.userDidStorage
+          ? {
+              get: async (key: string) =>
+                await this.storage.get(`userDid:${key}`),
+              set: async (key: string, value: string, ttl?: number) => {
+                await this.storage.set(`userDid:${key}`, value);
+              },
+              delete: async (key: string) =>
+                await this.storage.delete(`userDid:${key}`),
+            }
+          : undefined,
+        useDidWeb: this.config.identity?.userDidStorage === "persistent",
+      });
+    }
+
+    // Initialize nonce cache if it has an initialize method
+    if (
+      "initialize" in this.nonceCache &&
+      typeof (this.nonceCache as any).initialize === "function"
+    ) {
+      await (this.nonceCache as any).initialize();
+    }
+
+    // Log initialization if audit is enabled
+    if (this.config.audit?.enabled) {
+      this.logAudit("runtime_initialized", {
+        did: this.cachedIdentity.did,
+        environment: this.config.environment || "development",
+        userDidGeneration: this.config.identity?.generateUserDids
+          ? "enabled"
+          : "disabled",
+      });
+    }
+  }
+
+  /**
+   * Get the current agent identity
+   */
+  async getIdentity(): Promise<AgentIdentity> {
+    if (!this.cachedIdentity) {
+      this.cachedIdentity = await this.identity.getIdentity();
+    }
+    return this.cachedIdentity;
+  }
+
+  /**
+   * Handle handshake request
+   */
+  /**
+   * Handle MCP handshake request
+   *
+   * @param request - Handshake request object (may include oauthIdentity for persistent user DID lookup)
+   * @returns Handshake response with session ID and agent DID
+   *
+   * @remarks
+   * - Accepts optional oauthIdentity via request.oauthIdentity (backward compatible)
+   * - If OAuth identity provided, uses it to retrieve/create persistent user DID
+   * - Falls back to ephemeral user DID generation if OAuth unavailable
+   */
+  async handleHandshake(
+    request: any & {
+      oauthIdentity?:
+        | import("../identity/user-did-manager").OAuthIdentity
+        | null;
+    }
+  ): Promise<any> {
+    const identity = await this.getIdentity();
+    const timestamp = this.clock.now();
+    const sessionId = await this.generateSessionId();
+
+    // Generate user DID if user DID generation is enabled
+    // Use OAuth identity if provided for persistent user DID lookup
+    let userDid: string | undefined;
+    if (this.userDidManager) {
+      try {
+        const oauthIdentity = request.oauthIdentity;
+        userDid = await this.userDidManager.getOrCreateUserDid(
+          sessionId,
+          oauthIdentity
+        );
+        if (this.config.audit?.enabled) {
+          console.log("[MCP-I] Generated user DID for session:", {
+            userDid: userDid.substring(0, 20) + "...",
+            hasOAuth: !!oauthIdentity,
+            provider: oauthIdentity?.provider,
+          });
+        }
+      } catch (error) {
+        console.warn("[MCP-I] Failed to generate user DID:", error);
+        // Continue without user DID - not critical
+      }
+    }
+
+    // Extract client info if available
+    const normalizeString = (value: unknown): string | undefined => {
+      if (typeof value !== "string") {
+        return undefined;
+      }
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : undefined;
+    };
+
+    const protocolVersion = normalizeString(request.clientProtocolVersion);
+    const clientCapabilities = request.clientCapabilities;
+
+    const requestClientInfo = request.clientInfo;
+    const shouldPersistClientInfo =
+      requestClientInfo ||
+      typeof protocolVersion === "string" ||
+      typeof clientCapabilities !== "undefined";
+
+    const clientInfo = shouldPersistClientInfo
+      ? {
+          name: normalizeString(requestClientInfo?.name) ?? "unknown",
+          title: normalizeString(requestClientInfo?.title),
+          version: normalizeString(requestClientInfo?.version),
+          platform: normalizeString(requestClientInfo?.platform),
+          vendor: normalizeString(requestClientInfo?.vendor),
+          persistentId: normalizeString(requestClientInfo?.persistentId),
+          clientId:
+            normalizeString(requestClientInfo?.clientId) ?? crypto.randomUUID(),
+          protocolVersion,
+          capabilities: clientCapabilities,
+        }
+      : undefined;
+
+    // Create session
+    const session = {
+      id: sessionId,
+      clientDid: request.clientDid || userDid, // Use provided clientDid or generated userDid
+      userDid: userDid, // Store generated user DID separately
+      agentDid: request.agentDid, // ✅ FIXED: Only agent DID, no fallback
+      serverDid: identity.did, // ✅ NEW: Server's DID (for clarity)
+      audience: request.audience,
+      createdAt: timestamp,
+      expiresAt: this.clock.calculateExpiry(
+        (this.config.session?.ttlMinutes || 30) * 60
+      ),
+      clientInfo, // NEW: Store client information
+    };
+
+    this.sessions.set(sessionId, session);
+
+    // Create handshake response
+    const response = {
+      sessionId,
+      agentDid: identity.did,
+      timestamp,
+      capabilities: ["identity", "proof", "audit"],
+      ...(userDid && { userDid }), // Include user DID in response if generated
+    };
+
+    // Sign the response
+    const signature = await this.signData(response);
+
+    return {
+      ...response,
+      signature,
+    };
+  }
+
+  /**
+   * Process tool call with automatic proof generation
+   * Returns clean result only - proof is stored for out-of-band retrieval
+   *
+   * @param toolName - Name of the tool being called
+   * @param args - Tool arguments
+   * @param handler - Tool execution handler
+   * @param session - Session context (expected fields: id, audience, nonce?, delegationToken?, consentProof?)
+   */
+  async processToolCall(
+    toolName: string,
+    args: any,
+    handler: (args: any) => Promise<any>,
+    session?: any
+  ): Promise<any> {
+    // Check tool protection (delegation requirement)
+    if (this.config.toolProtectionService) {
+      // Get agent identity to check protection
+      const identity = await this.getIdentity();
+
+      if (this.config.audit?.enabled) {
+        console.log("[MCP-I] Checking tool protection:", {
+          tool: toolName,
+          agentDid: identity.did.slice(0, 20) + "...",
+          hasDelegation: !!(session?.delegationToken || session?.consentProof),
+        });
+      }
+
+      const protection =
+        await this.config.toolProtectionService.checkToolProtection(
+          toolName,
+          identity.did
+        );
+
+      if (protection) {
+        // Tool requires delegation
+        const hasDelegation = session?.delegationToken || session?.consentProof;
+
+        if (!hasDelegation) {
+          // No delegation provided - intercept the tool call and store context
+          // Store intercepted tool call context for resumption
+          const interceptedCall: InterceptedToolCall = {
+            toolName,
+            args,
+            sessionId: session?.id || "unknown",
+            timestamp: this.clock.now(),
+            expiresAt: this.clock.calculateExpiry(1800), // 30 minutes
+          };
+
+          // Generate resume token
+          const resumeToken = this.generateResumeToken(interceptedCall);
+
+          // Build consent URL with resume token
+          // Note: projectId is not available in base class - subclasses should override buildConsentUrl
+          const consentUrl = this.buildConsentUrl(
+            toolName,
+            protection.requiredScopes,
+            session,
+            resumeToken
+          );
+
+          // Create error with intercepted call context and pre-generated resume token
+          const error = new DelegationRequiredError(
+            toolName,
+            protection.requiredScopes,
+            consentUrl,
+            interceptedCall,
+            resumeToken
+          );
+
+          // Store intercepted call for resumption
+          this.interceptedCalls.set(resumeToken, interceptedCall);
+
+          // Clean up expired intercepted calls periodically
+          this.cleanupExpiredInterceptedCalls();
+
+          if (this.config.audit?.enabled) {
+            console.warn(
+              "[MCP-I] BLOCKED: Tool requires delegation but none provided",
+              {
+                tool: toolName,
+                requiredScopes: protection.requiredScopes,
+                agentDid: identity.did.slice(0, 20) + "...",
+                resumeToken: error.resumeToken,
+                consentUrl,
+              }
+            );
+          }
+
+          throw error;
+        }
+
+        // Delegation provided - verify it with AccessControlApiService
+        const delegationToken = session?.delegationToken;
+        const consentProof = session?.consentProof;
+
+        if (!this.accessControlService) {
+          // Access control service not available - log warning but allow execution
+          // This enables graceful degradation when service is not configured
+          if (this.config.audit?.enabled) {
+            console.warn(
+              "[MCP-I] ⚠️ Delegation token provided but AccessControlApiService not configured - skipping verification",
+              {
+                tool: toolName,
+                agentDid: identity.did.slice(0, 20) + "...",
+                hasDelegationToken: !!delegationToken,
+                hasConsentProof: !!consentProof,
+              }
+            );
+          }
+        } else {
+          // Verify delegation token with AccessControlApiService
+          try {
+            if (this.config.audit?.enabled) {
+              console.log(
+                "[MCP-I] 🔐 Verifying delegation token with AccessControlApiService",
+                {
+                  tool: toolName,
+                  agentDid: identity.did.slice(0, 20) + "...",
+                  hasDelegationToken: !!delegationToken,
+                  hasConsentProof: !!consentProof,
+                  requiredScopes: protection.requiredScopes,
+                }
+              );
+            }
+
+            // Build verification request
+            const verifyRequest: VerifyDelegationRequest = {
+              agent_did: identity.did,
+              scopes: protection.requiredScopes,
+            };
+
+            // Add delegation token if available (preferred over consent proof)
+            if (delegationToken) {
+              verifyRequest.delegation_token = delegationToken;
+            } else if (consentProof) {
+              // Consent proof is a JWT credential - use as credential_jwt
+              verifyRequest.credential_jwt = consentProof;
+            }
+
+            // Add optional timestamp for verification
+            verifyRequest.timestamp = this.clock.now();
+
+            // Add client info from session if available
+            if (session?.clientDid || session?.clientId) {
+              verifyRequest.client_info = {
+                origin: session?.serverOrigin,
+                user_agent: session?.userAgent,
+              };
+            }
+
+            // Perform verification
+            const verificationResult =
+              await this.accessControlService.verifyDelegation(verifyRequest, {
+                delegationToken: delegationToken || undefined,
+                credentialJwt: consentProof || undefined,
+              });
+
+            // Check verification result
+            if (!verificationResult.data.valid) {
+              // Delegation verification failed
+              const reason =
+                verificationResult.data.reason ||
+                "Delegation token invalid or expired";
+              const errorDetails = verificationResult.data.error;
+
+              if (this.config.audit?.enabled) {
+                console.error("[MCP-I] ❌ Delegation verification FAILED", {
+                  tool: toolName,
+                  agentDid: identity.did.slice(0, 20) + "...",
+                  reason,
+                  errorCode: errorDetails?.code,
+                  errorMessage: errorDetails?.message,
+                  requiredScopes: protection.requiredScopes,
+                });
+              }
+
+              // Throw DelegationRequiredError to trigger consent flow
+              const interceptedCall: InterceptedToolCall = {
+                toolName,
+                args,
+                sessionId: session?.id || "unknown",
+                timestamp: this.clock.now(),
+                expiresAt: this.clock.calculateExpiry(1800), // 30 minutes
+              };
+
+              const resumeToken = this.generateResumeToken(interceptedCall);
+              const consentUrl = this.buildConsentUrl(
+                toolName,
+                protection.requiredScopes,
+                session,
+                resumeToken
+              );
+
+              this.interceptedCalls.set(resumeToken, interceptedCall);
+              this.cleanupExpiredInterceptedCalls();
+
+              throw new DelegationRequiredError(
+                toolName,
+                protection.requiredScopes,
+                consentUrl,
+                interceptedCall,
+                resumeToken
+              );
+            }
+
+            // ✅ SECURITY: Validate user_identifier matches session userDid
+            // This ensures delegations are user-specific and prevents user isolation bypass
+            const credential = verificationResult.data.credential;
+            const delegationUserIdentifier = credential?.user_identifier;
+            const sessionUserDid = session?.userDid;
+
+            if (delegationUserIdentifier && sessionUserDid) {
+              if (delegationUserIdentifier !== sessionUserDid) {
+                // User identifier mismatch - potential security issue
+                const securityError = `Delegation user_identifier mismatch: delegation has "${delegationUserIdentifier.substring(0, 20)}..." but session has "${sessionUserDid.substring(0, 20)}..."`;
+
+                if (this.config.audit?.enabled) {
+                  console.error(
+                    "[MCP-I] 🔒 SECURITY: User identifier validation FAILED",
+                    {
+                      tool: toolName,
+                      agentDid: identity.did.slice(0, 20) + "...",
+                      delegationUserIdentifier:
+                        delegationUserIdentifier.substring(0, 20) + "...",
+                      sessionUserDid: sessionUserDid.substring(0, 20) + "...",
+                      sessionId: session?.id?.substring(0, 20) + "...",
+                      reason: "user_identifier_mismatch",
+                      severity: "high",
+                    }
+                  );
+                }
+
+                // Throw DelegationRequiredError to force re-authentication
+                const interceptedCall: InterceptedToolCall = {
+                  toolName,
+                  args,
+                  sessionId: session?.id || "unknown",
+                  timestamp: this.clock.now(),
+                  expiresAt: this.clock.calculateExpiry(1800), // 30 minutes
+                };
+
+                const resumeToken = this.generateResumeToken(interceptedCall);
+                const consentUrl = this.buildConsentUrl(
+                  toolName,
+                  protection.requiredScopes,
+                  session,
+                  resumeToken
+                );
+
+                this.interceptedCalls.set(resumeToken, interceptedCall);
+                this.cleanupExpiredInterceptedCalls();
+
+                throw new DelegationRequiredError(
+                  toolName,
+                  protection.requiredScopes,
+                  consentUrl,
+                  interceptedCall,
+                  resumeToken
+                );
+              }
+
+              // User identifier matches - log success for audit
+              if (this.config.audit?.enabled) {
+                console.log("[MCP-I] ✅ User identifier validation PASSED", {
+                  tool: toolName,
+                  agentDid: identity.did.slice(0, 20) + "...",
+                  userDid: sessionUserDid.substring(0, 20) + "...",
+                  sessionId: session?.id?.substring(0, 20) + "...",
+                });
+              }
+            } else if (delegationUserIdentifier && !sessionUserDid) {
+              // Delegation has user_identifier but session doesn't - log warning
+              if (this.config.audit?.enabled) {
+                console.warn(
+                  "[MCP-I] ⚠️ Delegation has user_identifier but session missing userDid",
+                  {
+                    tool: toolName,
+                    agentDid: identity.did.slice(0, 20) + "...",
+                    delegationUserIdentifier:
+                      delegationUserIdentifier.substring(0, 20) + "...",
+                    sessionId: session?.id?.substring(0, 20) + "...",
+                  }
+                );
+              }
+            }
+
+            // Verification succeeded
+            if (this.config.audit?.enabled) {
+              console.log("[MCP-I] ✅ Delegation verification SUCCEEDED", {
+                tool: toolName,
+                agentDid: identity.did.slice(0, 20) + "...",
+                delegationId: verificationResult.data.delegation_id,
+                credentialScopes: verificationResult.data.credential?.scopes,
+                requiredScopes: protection.requiredScopes,
+              });
+            }
+          } catch (error: any) {
+            // Handle verification errors
+            if (error instanceof DelegationRequiredError) {
+              // Re-throw DelegationRequiredError as-is (already handled above)
+              throw error;
+            }
+
+            // Handle AgentShieldAPIError (network errors, API errors, etc.)
+            if (error instanceof AgentShieldAPIError) {
+              if (this.config.audit?.enabled) {
+                console.error(
+                  "[MCP-I] ❌ Delegation verification error (API failure)",
+                  {
+                    tool: toolName,
+                    agentDid: identity.did.slice(0, 20) + "...",
+                    errorCode: error.code,
+                    errorMessage: error.message,
+                    errorDetails: error.details,
+                  }
+                );
+              }
+
+              // On API errors, fail securely by requiring delegation
+              // This prevents unauthorized access when verification service is unavailable
+              const interceptedCall: InterceptedToolCall = {
+                toolName,
+                args,
+                sessionId: session?.id || "unknown",
+                timestamp: this.clock.now(),
+                expiresAt: this.clock.calculateExpiry(1800),
+              };
+
+              const resumeToken = this.generateResumeToken(interceptedCall);
+              const consentUrl = this.buildConsentUrl(
+                toolName,
+                protection.requiredScopes,
+                session,
+                resumeToken
+              );
+
+              this.interceptedCalls.set(resumeToken, interceptedCall);
+              this.cleanupExpiredInterceptedCalls();
+
+              throw new DelegationRequiredError(
+                toolName,
+                protection.requiredScopes,
+                consentUrl,
+                interceptedCall,
+                resumeToken
+              );
+            }
+
+            // Unexpected error - log and fail securely
+            if (this.config.audit?.enabled) {
+              console.error(
+                "[MCP-I] ❌ Unexpected error during delegation verification",
+                {
+                  tool: toolName,
+                  agentDid: identity.did.slice(0, 20) + "...",
+                  error: error.message || String(error),
+                  errorStack: error.stack,
+                }
+              );
+            }
+
+            // Fail securely - require delegation on unexpected errors
+            const interceptedCall: InterceptedToolCall = {
+              toolName,
+              args,
+              sessionId: session?.id || "unknown",
+              timestamp: this.clock.now(),
+              expiresAt: this.clock.calculateExpiry(1800),
+            };
+
+            const resumeToken = this.generateResumeToken(interceptedCall);
+            const consentUrl = this.buildConsentUrl(
+              toolName,
+              protection.requiredScopes,
+              session,
+              resumeToken
+            );
+
+            this.interceptedCalls.set(resumeToken, interceptedCall);
+            this.cleanupExpiredInterceptedCalls();
+
+            throw new DelegationRequiredError(
+              toolName,
+              protection.requiredScopes,
+              consentUrl,
+              interceptedCall,
+              resumeToken
+            );
+          }
+        }
+      } else {
+        // No protection required - tool can be executed freely
+        if (this.config.audit?.enabled) {
+          console.log(
+            "[MCP-I] Tool protection check passed (no delegation required)",
+            {
+              tool: toolName,
+              agentDid: identity.did.slice(0, 20) + "...",
+              reason: "Tool not configured to require delegation",
+            }
+          );
+        }
+      }
+    }
+
+    // Execute the tool
+    const result = await handler(args);
+
+    // Create proof
+    const proof = await this.createProof(result, session);
+
+    // Store proof for out-of-band retrieval
+    this.lastProof = proof;
+
+    // Log if audit is enabled
+    if (this.config.audit?.enabled) {
+      this.logAudit("tool_executed", {
+        tool: toolName,
+        sessionId: session?.id,
+        timestamp: this.clock.now(),
+      });
+    }
+
+    // Return clean result only (no proof in LLM context)
+    return result;
+  }
+
+  /**
+   * Resume a tool call after authorization
+   *
+   * @param resumeToken - Token from DelegationRequiredError
+   * @param handler - Tool execution handler
+   * @param delegationToken - Delegation token from authorization
+   * @returns Tool execution result
+   */
+  async resumeToolCall(
+    resumeToken: string,
+    handler: (args: any) => Promise<any>,
+    delegationToken?: string
+  ): Promise<any> {
+    const interceptedCall = this.interceptedCalls.get(resumeToken);
+
+    if (!interceptedCall) {
+      throw new Error(`Invalid or expired resume token: ${resumeToken}`);
+    }
+
+    // Check if call has expired
+    if (this.clock.hasExpired(interceptedCall.expiresAt)) {
+      this.interceptedCalls.delete(resumeToken);
+      throw new Error(`Resume token expired: ${resumeToken}`);
+    }
+
+    // Get session for the intercepted call
+    const session = this.sessions.get(interceptedCall.sessionId);
+    if (!session) {
+      throw new Error(
+        `Session not found for intercepted call: ${interceptedCall.sessionId}`
+      );
+    }
+
+    // Add delegation token to session
+    const enhancedSession = {
+      ...session,
+      delegationToken,
+    };
+
+    // Resume the tool call with delegation
+    const result = await this.processToolCall(
+      interceptedCall.toolName,
+      interceptedCall.args,
+      handler,
+      enhancedSession
+    );
+
+    // Clean up intercepted call after successful resumption to prevent memory leak
+    this.interceptedCalls.delete(resumeToken);
+
+    return result;
+  }
+
+  /**
+   * Generate a resume token for intercepted tool call
+   */
+  private generateResumeToken(call: InterceptedToolCall): string {
+    // Create a deterministic token from the call context
+    const tokenData = JSON.stringify({
+      tool: call.toolName,
+      args: call.args,
+      sessionId: call.sessionId,
+      timestamp: call.timestamp,
+    });
+
+    // Simple hash-based token (in production, use proper crypto)
+    let hash = 0;
+    for (let i = 0; i < tokenData.length; i++) {
+      const char = tokenData.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash; // Convert to 32bit integer
+    }
+
+    return `resume_${Math.abs(hash).toString(36)}_${Date.now().toString(36)}`;
+  }
+
+  /**
+   * Clean up expired intercepted calls
+   */
+  private cleanupExpiredInterceptedCalls(): void {
+    const now = this.clock.now();
+    for (const [token, call] of this.interceptedCalls.entries()) {
+      if (this.clock.hasExpired(call.expiresAt)) {
+        this.interceptedCalls.delete(token);
+      }
+    }
+  }
+
+  /**
+   * Build consent URL for AgentShield delegation flow
+   *
+   * Note: Parameter names use snake_case for AgentShield API compatibility.
+   * This is documented in docs/API_PARITY_GUIDE.md under "Field Naming Conventions".
+   *
+   * AgentShield API requires snake_case in URL parameters:
+   * - session_id (not sessionId)
+   * - agent_did (not agentDid)
+   * - resume_token (not resumeToken)
+   *
+   * @param toolName - Tool that requires delegation
+   * @param scopes - Required scopes for the tool
+   * @param session - Current session context
+   * @param resumeToken - Token to resume after delegation
+   * @param projectId - Project ID for AgentShield API
+   * @returns Full consent URL with snake_case parameters
+   */
+  protected buildConsentUrl(
+    toolName: string,
+    scopes: string[],
+    session?: any,
+    resumeToken?: string,
+    projectId?: string
+  ): string {
+    // Default implementation - override in subclasses
+    // This URL should point to AgentShield's consent page
+    // Parameter names use snake_case for AgentShield API compatibility
+    const params = new URLSearchParams({
+      tool: toolName,
+      scopes: scopes.join(","),
+      session_id: session?.id || "",
+      agent_did: session?.agentDid || "",
+    });
+
+    // Add project_id if provided (required for AgentShield consent endpoint)
+    if (projectId) {
+      params.set("project_id", projectId);
+    }
+
+    // Add resume token if provided
+    if (resumeToken) {
+      params.set("resume_token", resumeToken);
+    }
+
+    // Use AgentShield consent endpoint
+    return `https://kya.vouched.id/bouncer/consent?${params.toString()}`;
+  }
+
+  /**
+   * Issue a new nonce and register it in the cache
+   * Use this to get a nonce for the session context before calling processToolCall
+   */
+  async issueNonce(sessionId: string): Promise<string> {
+    const nonce = await this.generateNonce();
+    // Get session to extract agentDid for agent-scoped nonce caching
+    const session = this.sessions.get(sessionId);
+    const agentDid = session?.agentDid || (await this.getIdentity()).did;
+    await this.nonceCache.add(
+      nonce,
+      300, // 5 minute expiry in seconds
+      agentDid // Agent-scoped nonce to prevent cross-agent replay attacks
+    );
+    return nonce;
+  }
+
+  /**
+   * Create cryptographic proof for data
+   */
+  async createProof(data: any, session?: any): Promise<any> {
+    const identity = await this.getIdentity();
+    const timestamp = this.clock.now();
+
+    // Use nonce from session if provided, otherwise generate new one
+    let nonce: string;
+    if (session?.nonce) {
+      nonce = session.nonce;
+    } else {
+      nonce = await this.generateNonce();
+      // Add nonce to cache to prevent replay (agent-scoped to prevent cross-agent replay attacks)
+      const agentDid = session?.agentDid || identity.did;
+      await this.nonceCache.add(
+        nonce,
+        300, // 5 minute expiry in seconds
+        agentDid // Agent-scoped nonce to prevent cross-agent replay attacks
+      );
+    }
+
+    const proofData = {
+      data,
+      timestamp,
+      nonce,
+      did: identity.did,
+      sessionId: session?.id,
+      audience: session?.audience,
+    };
+
+    const signature = await this.signData(proofData);
+
+    return {
+      timestamp,
+      nonce,
+      did: identity.did,
+      signature,
+      algorithm: "Ed25519",
+      sessionId: session?.id,
+      audience: session?.audience,
+    };
+  }
+
+  /**
+   * Verify a proof
+   *
+   * Supports both old format (data, proof) and new DetachedProof format.
+   * When DetachedProof format is used, ProofVerifier is used if available.
+   *
+   * @param dataOrProof - Either raw data (old format) or DetachedProof (new format)
+   * @param proofOrSession - Either proof object (old format) or session context (new format)
+   * @returns true if proof is valid, false otherwise
+   */
+  async verifyProof(dataOrProof: any, proofOrSession?: any): Promise<boolean> {
+    // Check if first argument is DetachedProof format
+    if (
+      dataOrProof &&
+      typeof dataOrProof === "object" &&
+      "jws" in dataOrProof &&
+      "meta" in dataOrProof
+    ) {
+      // New DetachedProof format
+      const detachedProof = dataOrProof as DetachedProof;
+      const session = proofOrSession;
+
+      // Use ProofVerifier if available
+      if (this.proofVerifier) {
+        try {
+          // Resolve DID to get public key
+          const didDoc = await this.fetch.resolveDID(detachedProof.meta.did);
+          const publicKeyJwk = this.extractPublicKeyJwk(
+            didDoc,
+            detachedProof.meta.kid
+          );
+
+          if (!publicKeyJwk) {
+            console.error("[MCPIRuntimeBase] Failed to extract public key JWK");
+            return false;
+          }
+
+          // Verify proof using ProofVerifier
+          const result = await this.proofVerifier.verifyProof(
+            detachedProof,
+            publicKeyJwk
+          );
+
+          if (result.valid && session) {
+            // Store canonical payload in session for detached JWS consumers
+            const canonicalPayload = this.proofVerifier.buildCanonicalPayload(
+              detachedProof.meta
+            );
+            session.canonicalPayload = canonicalPayload;
+          }
+
+          return result.valid;
+        } catch (error) {
+          console.error("[MCPIRuntimeBase] Proof verification failed:", error);
+          return false;
+        }
+      } else {
+        // Fallback to old verification if ProofVerifier not available
+        console.warn(
+          "[MCPIRuntimeBase] ProofVerifier not available, using fallback verification"
+        );
+        return this.verifyProofLegacy(dataOrProof, proofOrSession);
+      }
+    } else {
+      // Old format (data, proof)
+      return this.verifyProofLegacy(dataOrProof, proofOrSession);
+    }
+  }
+
+  /**
+   * Legacy proof verification (backward compatibility)
+   * @internal
+   */
+  private async verifyProofLegacy(data: any, proof: any): Promise<boolean> {
+    try {
+      // Check nonce hasn't been used (scoped to agent DID to prevent cross-agent replay attacks)
+      if (await this.nonceCache.has(proof.nonce, proof.did)) {
+        return false;
+      }
+
+      // Check timestamp is within skew
+      if (
+        !this.clock.isWithinSkew(
+          proof.timestamp,
+          this.config.session?.timestampSkewSeconds || 120
+        )
+      ) {
+        return false;
+      }
+
+      // Resolve DID to get public key
+      const didDoc = await this.fetch.resolveDID(proof.did);
+      const publicKey = this.extractPublicKey(didDoc);
+
+      // Verify signature
+      const proofData = {
+        data,
+        timestamp: proof.timestamp,
+        nonce: proof.nonce,
+        did: proof.did,
+        sessionId: proof.sessionId,
+      };
+
+      const dataBytes = new TextEncoder().encode(JSON.stringify(proofData));
+      const signatureBytes = this.base64ToBytes(proof.signature);
+
+      const isValid = await this.crypto.verify(
+        dataBytes,
+        signatureBytes,
+        publicKey
+      );
+
+      // If signature is valid, add nonce to cache to prevent replay (scoped to agent DID)
+      if (isValid) {
+        // Pass TTL in seconds, not absolute timestamp
+        const ttlSeconds = (this.config.session?.ttlMinutes || 30) * 60; // Convert minutes to seconds
+        await this.nonceCache.add(proof.nonce, ttlSeconds, proof.did);
+      }
+
+      return isValid;
+    } catch (error) {
+      console.error("Proof verification failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Verify a JWS proof (full compact JWS format: header.payload.signature)
+   *
+   * This method provides full cryptographic signature verification using CryptoService.
+   * Use this when you have a DetachedProof with JWS instead of raw signature.
+   *
+   * @param jws - Full compact JWS string (header.payload.signature)
+   * @param publicKeyJwk - Ed25519 public key in JWK format
+   * @param detachedPayload - Optional detached payload for detached JWS format
+   * @returns true if signature is valid, false otherwise
+   */
+  async verifyProofJWS(
+    jws: string,
+    publicKeyJwk: Ed25519JWK,
+    detachedPayload?: string | Uint8Array
+  ): Promise<boolean> {
+    if (!this.cryptoService) {
+      console.error("[MCPIRuntimeBase] CryptoService not initialized");
+      return false;
+    }
+
+    try {
+      const options =
+        detachedPayload !== undefined ? { detachedPayload } : undefined;
+      return await this.cryptoService.verifyJWS(jws, publicKeyJwk, options);
+    } catch (error) {
+      console.error("[MCPIRuntimeBase] JWS verification failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Get current session
+   */
+  async getCurrentSession(): Promise<any> {
+    // Find non-expired session
+    for (const [id, session] of this.sessions) {
+      if (!this.clock.hasExpired(session.expiresAt)) {
+        return session;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get the last generated proof for out-of-band transport
+   */
+  getLastProof(): any {
+    return this.lastProof;
+  }
+
+  /**
+   * Create well-known handler for identity verification
+   */
+  createWellKnownHandler(
+    config?: WellKnownConfig
+  ): (path: string) => Promise<WellKnownResponse | MCPIdentity | null> {
+    return async (path: string) => {
+      const identity = await this.getIdentity();
+
+      if (path === "/.well-known/did.json") {
+        const didDocument = this.createDIDDocument(identity);
+        return {
+          status: 200,
+          headers: {
+            "Content-Type": "application/did+json",
+            "Cache-Control":
+              this.config.environment === "production"
+                ? "public, max-age=300"
+                : "no-store",
+          },
+          body: JSON.stringify(didDocument, null, 2),
+        };
+      }
+
+      if (path === "/.well-known/agent.json") {
+        const agentDocument: AgentDocument = {
+          id: identity.did,
+          capabilities: {
+            "mcp-i": ["handshake", "signing", "verification"],
+          },
+        };
+
+        if (config?.serviceName || config?.serviceEndpoint) {
+          agentDocument.metadata = {
+            ...(config?.serviceName && { name: config.serviceName }),
+            ...(config?.serviceEndpoint && {
+              serviceEndpoint: config.serviceEndpoint,
+            }),
+          };
+        }
+
+        return {
+          status: 200,
+          headers: {
+            "Content-Type": "application/json",
+            "Cache-Control":
+              this.config.environment === "production"
+                ? "public, max-age=300"
+                : "no-store",
+          },
+          body: JSON.stringify(agentDocument, null, 2),
+        };
+      }
+
+      if (path === "/.well-known/mcp-identity") {
+        return {
+          did: identity.did,
+          publicKey: identity.publicKey,
+          serviceName: config?.serviceName || "MCP-I Service",
+          serviceEndpoint: config?.serviceEndpoint || "https://example.com",
+          timestamp: this.clock.now(),
+        };
+      }
+
+      return null;
+    };
+  }
+
+  /**
+   * Create debug endpoint (development only)
+   */
+  createDebugEndpoint(): any {
+    if (this.config.environment === "production") {
+      return null;
+    }
+
+    return async () => {
+      const identity = await this.getIdentity();
+      const session = await this.getCurrentSession();
+
+      return {
+        identity: {
+          did: identity.did,
+          publicKey: identity.publicKey,
+        },
+        session,
+        config: {
+          environment: this.config.environment,
+          timestampSkewSeconds: this.config.session?.timestampSkewSeconds,
+          sessionTtlMinutes: this.config.session?.ttlMinutes,
+        },
+        timestamp: this.clock.now(),
+      };
+    };
+  }
+
+  /**
+   * Get audit logger
+   */
+  getAuditLogger(): any {
+    return {
+      log: (event: string, data: any) => this.logAudit(event, data),
+    };
+  }
+
+  /**
+   * Rotate keys
+   */
+  async rotateKeys(): Promise<AgentIdentity> {
+    const oldDid = this.cachedIdentity?.did;
+    const newIdentity = await this.identity.rotateKeys();
+    this.cachedIdentity = newIdentity;
+
+    if (this.config.audit?.enabled) {
+      this.logAudit("keys_rotated", {
+        oldDid: oldDid,
+        newDid: newIdentity.did,
+        timestamp: this.clock.now(),
+      });
+    }
+
+    return newIdentity;
+  }
+
+  // Helper methods
+
+  private async signData(data: any): Promise<string> {
+    const identity = await this.getIdentity();
+    const dataBytes = new TextEncoder().encode(JSON.stringify(data));
+    const signature = await this.crypto.sign(dataBytes, identity.privateKey);
+    return this.bytesToBase64(signature);
+  }
+
+  private async generateNonce(): Promise<string> {
+    const bytes = await this.crypto.randomBytes(32);
+    return this.bytesToBase64(bytes);
+  }
+
+  private async generateSessionId(): Promise<string> {
+    const bytes = await this.crypto.randomBytes(16);
+    return this.bytesToHex(bytes);
+  }
+
+  /**
+   * Log structured events in JSON format (NOT frozen audit format).
+   *
+   * **Important:** This method logs events in JSON format for general runtime events
+   * (e.g., "runtime_initialized", "tool_executed", "keys_rotated").
+   *
+   * **For frozen format audit logs** (MCP-I spec compliance), use `AuditLogger.logAuditRecord()`
+   * from `@kya-os/mcp-i/runtime` instead. The frozen format is:
+   * ```
+   * audit.v1 ts=<unix> session=<id> audience=<host> did=<did> kid=<kid> reqHash=<sha256:..> resHash=<sha256:..> verified=yes|no scope=<scopeId|->
+   * ```
+   *
+   * **Format:** JSON object with `event`, `data`, `timestamp`, and `timestampFormatted` fields.
+   *
+   * **Privacy:** If `includePayloads` is false (default), the `data` field is omitted.
+   *
+   * **Use Cases:**
+   * - Developer debugging and local logging
+   * - Runtime initialization events
+   * - Tool execution tracking (non-spec-compliant)
+   * - Key rotation events
+   *
+   * **NOT for:**
+   * - MCP-I spec-compliant audit logs (use `AuditLogger`)
+   * - Production audit trails (use `AuditLogger`)
+   * - Compliance requirements (use `AuditLogger`)
+   *
+   * @param event - Event name (e.g., "runtime_initialized", "tool_executed")
+   * @param data - Event data (only included if `includePayloads` is true)
+   *
+   * @example
+   * ```typescript
+   * // Logs: {"event":"runtime_initialized","timestamp":1234567890,"timestampFormatted":"2024-01-01T00:00:00Z"}
+   * this.logAudit("runtime_initialized", { did: "did:key:..." });
+   * ```
+   *
+   * @internal This is a private method for internal runtime events.
+   * Use AuditLogger for spec-compliant frozen format audit logs.
+   */
+  private logAudit(event: string, data: any): void {
+    if (!this.config.audit?.enabled) return;
+
+    const record = {
+      event,
+      data: this.config.audit.includePayloads ? data : undefined,
+      timestamp: this.clock.now(),
+      timestampFormatted: this.clock.format(this.clock.now()),
+    };
+
+    const logLine = JSON.stringify(record);
+
+    if (this.config.audit.logFunction) {
+      this.config.audit.logFunction(logLine);
+    } else {
+      console.log("[AUDIT]", logLine);
+    }
+  }
+
+  private createDIDDocument(identity: AgentIdentity): DIDDocument {
+    return {
+      "@context": ["https://www.w3.org/ns/did/v1"],
+      id: identity.did,
+      verificationMethod: [
+        {
+          id: `${identity.did}#key-1`,
+          type: "Ed25519VerificationKey2020",
+          controller: identity.did,
+          // Using base64 for cross-platform compatibility (Cloudflare Workers)
+          // W3C DID spec supports both base64 and multibase formats
+          publicKeyBase64: identity.publicKey,
+        },
+      ],
+      authentication: [`${identity.did}#key-1`],
+      assertionMethod: [`${identity.did}#key-1`],
+    };
+  }
+
+  private extractPublicKey(didDoc: any): string {
+    const method = didDoc.verificationMethod?.[0];
+    if (method?.publicKeyBase64) {
+      return method.publicKeyBase64;
+    }
+    if (method?.publicKeyMultibase) {
+      // Convert multibase to base64
+      return method.publicKeyMultibase; // Simplified
+    }
+    throw new Error("Public key not found in DID document");
+  }
+
+  /**
+   * Extract public key JWK from DID document
+   */
+  private extractPublicKeyJwk(didDoc: any, kid?: string): Ed25519JWK | null {
+    // Try to find Ed25519 public key matching kid if provided
+    const verificationMethod =
+      didDoc.verificationMethod?.find((vm: any) => {
+        const matchesType =
+          vm.type === "Ed25519VerificationKey2020" ||
+          vm.type === "JsonWebKey2020";
+        const matchesKid = !kid || vm.id === kid || vm.id.endsWith(`#${kid}`);
+        return matchesType && matchesKid;
+      }) || didDoc.verificationMethod?.[0]; // Fallback to first method
+
+    if (verificationMethod?.publicKeyJwk) {
+      const jwk = verificationMethod.publicKeyJwk;
+      // Ensure it's Ed25519 format
+      if (jwk.kty === "OKP" && jwk.crv === "Ed25519") {
+        return jwk as Ed25519JWK;
+      }
+    }
+
+    // Fallback: try to convert multibase to JWK (simplified)
+    if (verificationMethod?.publicKeyMultibase) {
+      // This is a simplified conversion - in production, use proper multibase decoding
+      console.warn(
+        "[MCPIRuntimeBase] Multibase to JWK conversion not fully implemented"
+      );
+      return null;
+    }
+
+    return null;
+  }
+
+  private bytesToBase64(bytes: Uint8Array): string {
+    return Buffer.from(bytes).toString("base64");
+  }
+
+  private base64ToBytes(base64: string): Uint8Array {
+    return new Uint8Array(Buffer.from(base64, "base64"));
+  }
+
+  private bytesToHex(bytes: Uint8Array): string {
+    return Buffer.from(bytes).toString("hex");
+  }
+}