@kya-os/mcp-i-core 1.3.12 → 1.3.14

package/src/runtime/base.ts

@@ -1,1392 +0,0 @@
-/**
- * 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 MCP handshake request
-   *
-   * Phase 5: Anonymous Sessions Until OAuth
-   * - Sessions start anonymous (no userDid) unless OAuth identity provided
-   * - User DID is resolved via AgentShield after OAuth completes
-   * - Eliminates DID fragmentation (same user = same DID across sessions)
-   *
-   * @param request - Handshake request object (may include oauthIdentity for persistent user DID lookup)
-   * @returns Handshake response with session ID and agent DID
-   */
-  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();
-
-    // Phase 5: Try to resolve user DID from existing OAuth mapping
-    // Sessions start anonymous - no ephemeral generation
-    let userDid: string | undefined;
-    if (this.userDidManager) {
-      try {
-        const oauthIdentity = request.oauthIdentity;
-        const resolvedDid = await this.userDidManager.getOrCreateUserDid(
-          sessionId,
-          oauthIdentity
-        );
-        // Convert null to undefined for session storage
-        userDid = resolvedDid ?? undefined;
-
-        if (this.config.audit?.enabled) {
-          if (userDid) {
-            console.log("[MCP-I] Resolved existing user DID for session:", {
-              userDid: userDid.substring(0, 20) + "...",
-              hasOAuth: !!oauthIdentity,
-              provider: oauthIdentity?.provider,
-            });
-          } else {
-            console.log("[MCP-I] Session started anonymous (no userDid):", {
-              sessionId: sessionId.substring(0, 8) + "...",
-              hasOAuth: !!oauthIdentity,
-            });
-          }
-        }
-      } catch (error) {
-        console.warn("[MCP-I] Failed to resolve user DID:", error);
-        // Continue without user DID - session is anonymous
-      }
-    }
-
-    // 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 with Phase 5 identity state
-    const session = {
-      id: sessionId,
-      clientDid: request.clientDid || userDid, // Use provided clientDid or generated userDid
-      userDid: userDid, // Store user DID (may be undefined for anonymous sessions)
-      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, // Store client information
-      // Phase 5: Identity state tracking
-      identityState: userDid ? "authenticated" : "anonymous",
-      oauthIdentity: request.oauthIdentity ?? undefined,
-    };
-
-    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,
-    };
-  }
-
-  /**
-   * Update session identity after OAuth resolution (Phase 5)
-   *
-   * Called after AgentShield identity/resolve returns a persistent user DID.
-   * Updates the session to authenticated state with the resolved DID.
-   *
-   * @param sessionId - MCP session ID
-   * @param userDid - Persistent user DID from AgentShield
-   * @param oauthIdentity - OAuth identity information
-   * @throws Error if session not found
-   */
-  async updateSessionIdentity(
-    sessionId: string,
-    userDid: string,
-    oauthIdentity?: { provider: string; subject: string; email?: string }
-  ): Promise<void> {
-    const session = this.sessions.get(sessionId);
-    if (!session) {
-      throw new Error(`Session not found: ${sessionId}`);
-    }
-
-    // Update session with resolved identity
-    session.userDid = userDid;
-    session.identityState = "authenticated";
-    if (oauthIdentity) {
-      session.oauthIdentity = oauthIdentity;
-    }
-
-    // Update the sessions map
-    this.sessions.set(sessionId, session);
-
-    // Also update UserDidManager cache if available
-    if (this.userDidManager) {
-      await this.userDidManager.setUserDidForSession(sessionId, userDid, oauthIdentity);
-    }
-
-    if (this.config.audit?.enabled) {
-      console.log("[MCP-I] Session identity updated (Phase 5):", {
-        sessionId: sessionId.substring(0, 8) + "...",
-        userDid: userDid.substring(0, 20) + "...",
-        provider: oauthIdentity?.provider,
-        identityState: "authenticated",
-      });
-    }
-  }
-
-  /**
-   * Get session by ID
-   */
-  getSession(sessionId: string): any | undefined {
-    return this.sessions.get(sessionId);
-  }
-
-  /**
-   * 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");
-  }
-}