@kya-os/mcp-i-core 1.4.19 → 1.6.0

package/dist/runtime/base.d.ts

@@ -8,9 +8,13 @@
 import { CryptoProvider, ClockProvider, FetchProvider, StorageProvider, NonceCacheProvider, IdentityProvider, AgentIdentity } from "../providers/base";
 import { type Ed25519JWK } from "../services/crypto.service.js";
 import { ProofVerifier } from "../services/proof-verifier.js";
+import type { DetachedProof } from "@kya-os/contracts/proof";
+import type { HandshakeRequest } from "@kya-os/contracts/handshake";
 import type { MCPIdentity, WellKnownConfig, WellKnownResponse } from "@kya-os/contracts/well-known";
 import type { AccessControlApiService } from "../services/access-control.service.js";
 import type { ProviderRuntimeConfig } from "../config";
+import { type OAuthIdentity } from "../identity/user-did-manager";
+import type { IAuditLogger } from "./audit-logger.js";
 /**
  * Interface for runtime instances that have AccessControlApiService available
  * This allows type-safe access to the access control service without using `as any`
@@ -20,6 +24,65 @@ import type { ProviderRuntimeConfig } from "../config";
 export interface RuntimeWithAccessControl {
     accessControlService?: AccessControlApiService;
 }
+type RuntimeRecord = Record<string, unknown>;
+type RuntimeHandshakeRequest = Partial<HandshakeRequest> & RuntimeRecord & {
+    audience?: string;
+    agentDid?: string;
+    clientInfo?: RuntimeRecord;
+    clientProtocolVersion?: unknown;
+    clientCapabilities?: unknown;
+    clientDid?: string;
+    oauthIdentity?: OAuthIdentity | null;
+};
+interface RuntimeHandshakeResponse {
+    sessionId: string;
+    agentDid: string;
+    timestamp: number;
+    capabilities: string[];
+    userDid?: string;
+    signature: string;
+}
+interface RuntimeSessionContext {
+    id?: string;
+    audience?: string;
+    createdAt?: number;
+    expiresAt?: number;
+    clientDid?: string;
+    userDid?: string;
+    agentDid?: string;
+    serverDid?: string;
+    nonce?: string;
+    delegationToken?: string;
+    consentProof?: string;
+    projectId?: string;
+    serverOrigin?: string;
+    userAgent?: string;
+    clientId?: string;
+    agentName?: string;
+    clientInfo?: Record<string, unknown>;
+    identityState?: "anonymous" | "authenticated";
+    oauthIdentity?: OAuthIdentity;
+    canonicalPayload?: string;
+    [key: string]: unknown;
+}
+interface StoredRuntimeSession extends RuntimeSessionContext {
+    id: string;
+    createdAt: number;
+    expiresAt: number;
+}
+interface LegacyProof {
+    timestamp: number;
+    nonce: string;
+    did: string;
+    signature: string;
+    algorithm: "Ed25519";
+    sessionId?: string;
+    audience?: string;
+}
+type RuntimeProof = LegacyProof | DetachedProof;
+type RuntimeAuditLogger = IAuditLogger | {
+    log: (event: string, data: unknown) => void;
+};
 export declare class MCPIRuntimeBase {
     protected crypto: CryptoProvider;
     protected clock: ClockProvider;
@@ -36,6 +99,12 @@ export declare class MCPIRuntimeBase {
     private cryptoService?;
     protected proofVerifier?: ProofVerifier;
     protected accessControlService?: AccessControlApiService;
+    /**
+     * Cached flag indicating whether @modelcontextprotocol/ext-apps is available.
+     * Set by subclasses after a successful dynamic import (avoids require() vs ESM issues).
+     * When undefined, falls back to synchronous require() probe.
+     */
+    private _extAppsAvailable?;
     constructor(config: ProviderRuntimeConfig);
     /**
      * Initialize the runtime
@@ -56,9 +125,7 @@ export declare class MCPIRuntimeBase {
      * @param request - Handshake request object (may include oauthIdentity for persistent user DID lookup)
      * @returns Handshake response with session ID and agent DID
      */
-    handleHandshake(request: any & {
-        oauthIdentity?: import("../identity/user-did-manager").OAuthIdentity | null;
-    }): Promise<any>;
+    handleHandshake(request: RuntimeHandshakeRequest): Promise<RuntimeHandshakeResponse>;
     /**
      * Update session identity after OAuth resolution (Phase 5)
      *
@@ -78,7 +145,7 @@ export declare class MCPIRuntimeBase {
     /**
      * Get session by ID
      */
-    getSession(sessionId: string): any | undefined;
+    getSession(sessionId: string): StoredRuntimeSession | undefined;
     /**
      * Extract the correct provider for consent URL from tool protection config
      *
@@ -101,7 +168,7 @@ export declare class MCPIRuntimeBase {
      * @param handler - Tool execution handler
      * @param session - Session context (expected fields: id, audience, nonce?, delegationToken?, consentProof?)
      */
-    processToolCall(toolName: string, args: any, handler: (args: any) => Promise<any>, session?: any): Promise<any>;
+    processToolCall<TArgs = unknown, TResult = unknown>(toolName: string, args: TArgs, handler: (args: TArgs) => Promise<TResult>, session?: RuntimeSessionContext): Promise<TResult | RuntimeRecord>;
     /**
      * Resume a tool call after authorization
      *
@@ -110,9 +177,12 @@ export declare class MCPIRuntimeBase {
      * @param delegationToken - Delegation token from authorization
      * @returns Tool execution result
      */
-    resumeToolCall(resumeToken: string, handler: (args: any) => Promise<any>, delegationToken?: string): Promise<any>;
+    resumeToolCall(resumeToken: string, handler: (args: unknown) => Promise<unknown>, delegationToken?: string): Promise<unknown>;
     /**
      * Generate a resume token for intercepted tool call
+     *
+     * Uses cryptographically secure random bytes for token generation.
+     * The token is used as an opaque lookup key in the interceptedCalls Map.
      */
     private generateResumeToken;
     /**
@@ -139,7 +209,50 @@ export declare class MCPIRuntimeBase {
      * @param provider - Provider name (e.g., "github", "credentials") to select specific auth method
      * @returns Full consent URL with snake_case parameters
      */
-    protected buildConsentUrl(toolName: string, scopes: string[], session?: any, resumeToken?: string, projectId?: string, provider?: string): string;
+    /**
+     * MCP Apps UI consent resource URI.
+     * Single shared resource for all consent flows - tool-specific data
+     * is passed via structuredContent in the tool result.
+     */
+    protected static readonly CONSENT_UI_RESOURCE_URI = "ui://mcpi-consent/authorize";
+    /**
+     * Check if the connected MCP client supports MCP Apps UI rendering.
+     * Returns false if @modelcontextprotocol/ext-apps is not installed
+     * or the client didn't advertise the io.modelcontextprotocol/ui capability.
+     *
+     * Override in subclasses to provide client capabilities from the MCP session.
+     */
+    protected hasUICapability(clientCapabilities?: Record<string, unknown>): boolean;
+    /**
+     * Mark the ext-apps SDK as available.
+     * Called by subclasses after a successful dynamic import() of the SDK,
+     * which avoids the CJS require() vs ESM incompatibility that causes
+     * the synchronous probe to fail in Cloudflare Workers.
+     */
+    setExtAppsAvailable(available: boolean): void;
+    /**
+     * Check if the MCP Apps inline consent UI is enabled.
+     * Requires BOTH conditions:
+     *   1. The SDK is available (set via setExtAppsAvailable(true) after dynamic import)
+     *   2. The config flag is enabled (config.inlineConsent === true OR MCPI_INLINE_CONSENT env var)
+     * This allows merging the feature while keeping it off by default.
+     */
+    protected isExtAppsAvailable(): boolean;
+    /**
+     * Build an MCP Apps-compatible tool result that renders an inline consent UI.
+     * Returns null when the host doesn't support MCP Apps or the SDK is unavailable,
+     * allowing callers to fall back to DelegationRequiredError.
+     *
+     * @param toolName - Tool requiring delegation
+     * @param scopes - Required scopes
+     * @param session - Current session context
+     * @param resumeToken - Token to resume after delegation
+     * @param projectId - AgentShield project ID
+     * @param serverUrl - Server URL for consent approval POST
+     * @param clientCapabilities - MCP client capabilities from the session
+     */
+    buildConsentUIResult(toolName: string, scopes: string[], session?: Record<string, unknown>, resumeToken?: string, projectId?: string, serverUrl?: string, clientCapabilities?: Record<string, unknown>, authMode?: "consent-only" | "credentials", provider?: string): Record<string, unknown> | null;
+    protected buildConsentUrl(toolName: string, scopes: string[], session?: RuntimeSessionContext, resumeToken?: string, projectId?: string, provider?: string): string;
     /**
      * Issue a new nonce and register it in the cache
      * Use this to get a nonce for the session context before calling processToolCall
@@ -148,7 +261,7 @@ export declare class MCPIRuntimeBase {
     /**
      * Create cryptographic proof for data
      */
-    createProof(data: any, session?: any): Promise<any>;
+    createProof(data: unknown, session?: RuntimeSessionContext): Promise<RuntimeProof>;
     /**
      * Verify a proof
      *
@@ -159,7 +272,7 @@ export declare class MCPIRuntimeBase {
      * @param proofOrSession - Either proof object (old format) or session context (new format)
      * @returns true if proof is valid, false otherwise
      */
-    verifyProof(dataOrProof: any, proofOrSession?: any): Promise<boolean>;
+    verifyProof(dataOrProof: unknown, proofOrSession?: unknown): Promise<boolean>;
     /**
      * Legacy proof verification (backward compatibility)
      * @internal
@@ -180,11 +293,11 @@ export declare class MCPIRuntimeBase {
     /**
      * Get current session
      */
-    getCurrentSession(): Promise<any>;
+    getCurrentSession(): Promise<StoredRuntimeSession | null>;
     /**
      * Get the last generated proof for out-of-band transport
      */
-    getLastProof(): any;
+    getLastProof(): RuntimeProof | undefined;
     /**
      * Create well-known handler for identity verification
      */
@@ -192,11 +305,11 @@ export declare class MCPIRuntimeBase {
     /**
      * Create debug endpoint (development only)
      */
-    createDebugEndpoint(): any;
+    createDebugEndpoint(): (() => Promise<RuntimeRecord>) | null;
     /**
      * Get audit logger
      */
-    getAuditLogger(): any;
+    getAuditLogger(): RuntimeAuditLogger | undefined;
     /**
      * Rotate keys
      */
@@ -258,4 +371,5 @@ export declare class MCPIRuntimeBase {
     private base64ToBytes;
     private bytesToHex;
 }
+export {};
 //# sourceMappingURL=base.d.ts.map

package/dist/runtime/base.js

@@ -13,6 +13,7 @@ const crypto_service_js_1 = require("../services/crypto.service.js");
 const access_control_service_js_1 = require("../services/access-control.service.js");
 const agentshield_api_1 = require("@kya-os/contracts/agentshield-api");
 const user_did_manager_1 = require("../identity/user-did-manager");
+const isRecord = (value) => typeof value === "object" && value !== null;
 class MCPIRuntimeBase {
     crypto;
     clock;
@@ -29,6 +30,12 @@ class MCPIRuntimeBase {
     cryptoService;
     proofVerifier; // Optional ProofVerifier (injected by subclasses)
     accessControlService; // Optional AccessControlApiService (injected by subclasses)
+    /**
+     * Cached flag indicating whether @modelcontextprotocol/ext-apps is available.
+     * Set by subclasses after a successful dynamic import (avoids require() vs ESM issues).
+     * When undefined, falls back to synchronous require() probe.
+     */
+    _extAppsAvailable;
     constructor(config) {
         this.config = config;
         this.crypto = config.cryptoProvider;
@@ -63,9 +70,9 @@ class MCPIRuntimeBase {
             });
         }
         // Initialize nonce cache if it has an initialize method
-        if ("initialize" in this.nonceCache &&
-            typeof this.nonceCache.initialize === "function") {
-            await this.nonceCache.initialize();
+        const nonceCacheWithInitialize = this.nonceCache;
+        if (typeof nonceCacheWithInitialize.initialize === "function") {
+            await nonceCacheWithInitialize.initialize();
         }
         // Log initialization if audit is enabled
         if (this.config.audit?.enabled) {
@@ -301,7 +308,7 @@ class MCPIRuntimeBase {
                         expiresAt: this.clock.calculateExpiry(1800), // 30 minutes
                     };
                     // Generate resume token
-                    const resumeToken = this.generateResumeToken(interceptedCall);
+                    const resumeToken = await this.generateResumeToken(interceptedCall);
                     // Build consent URL with resume token
                     // Note: projectId is not available in base class - subclasses should override buildConsentUrl
                     // Pass oauthProvider to ensure correct auth method is selected (e.g., "credentials" vs "github")
@@ -323,6 +330,16 @@ class MCPIRuntimeBase {
                             consentUrl,
                         });
                     }
+                    // Try MCP Apps inline consent UI before falling back to error
+                    // Client capabilities are stored under session.clientInfo.capabilities (set during handleHandshake)
+                    const clientInfo = session?.clientInfo;
+                    const clientCaps = isRecord(clientInfo?.capabilities)
+                        ? clientInfo.capabilities
+                        : undefined;
+                    const uiResult = this.buildConsentUIResult(toolName, protection.requiredScopes, session, resumeToken, session?.projectId || undefined, session?.serverOrigin || undefined, clientCaps);
+                    if (uiResult) {
+                        return uiResult;
+                    }
                     throw error;
                 }
                 // Delegation provided - verify it with AccessControlApiService
@@ -414,7 +431,7 @@ class MCPIRuntimeBase {
                                 timestamp: this.clock.now(),
                                 expiresAt: this.clock.calculateExpiry(1800), // 30 minutes
                             };
-                            const resumeToken = this.generateResumeToken(interceptedCall);
+                            const resumeToken = await this.generateResumeToken(interceptedCall);
                             const consentUrl = this.buildConsentUrl(toolName, protection.requiredScopes, session, resumeToken, undefined, // projectId - handled by subclass override
                             this.getConsentProvider(protection) // Provider from tool config (supports both password and oauth auth)
                             );
@@ -464,7 +481,7 @@ class MCPIRuntimeBase {
                                     timestamp: this.clock.now(),
                                     expiresAt: this.clock.calculateExpiry(1800), // 30 minutes
                                 };
-                                const resumeToken = this.generateResumeToken(interceptedCall);
+                                const resumeToken = await this.generateResumeToken(interceptedCall);
                                 const consentUrl = this.buildConsentUrl(toolName, protection.requiredScopes, session, resumeToken, undefined, // projectId - handled by subclass override
                                 this.getConsentProvider(protection) // Provider from tool config (supports both password and oauth auth)
                                 );
@@ -528,7 +545,7 @@ class MCPIRuntimeBase {
                                     timestamp: this.clock.now(),
                                     expiresAt: this.clock.calculateExpiry(1800),
                                 };
-                                const resumeToken = this.generateResumeToken(interceptedCall);
+                                const resumeToken = await this.generateResumeToken(interceptedCall);
                                 const consentUrl = this.buildConsentUrl(toolName, protection.requiredScopes, session, resumeToken, undefined, this.getConsentProvider(protection));
                                 this.interceptedCalls.set(resumeToken, interceptedCall);
                                 this.cleanupExpiredInterceptedCalls();
@@ -536,7 +553,14 @@ class MCPIRuntimeBase {
                             }
                             // Both tool and delegation have authorization - compare them
                             if (!(0, access_control_service_js_1.authorizationMatches)(delegationAuth, toolAuth)) {
-                                const authMismatchReason = `Authorization method mismatch: delegation has ${delegationAuth.type}${delegationAuth.provider ? `:${delegationAuth.provider}` : ""}${delegationAuth.credentialType ? `:${delegationAuth.credentialType}` : ""} but tool requires ${toolAuth.type}${toolAuth.provider ? `:${toolAuth.provider}` : ""}${toolAuth.credentialType ? `:${toolAuth.credentialType}` : ""}`;
+                                const toolAuthRecord = toolAuth;
+                                const toolAuthProvider = typeof toolAuthRecord.provider === "string"
+                                    ? `:${toolAuthRecord.provider}`
+                                    : "";
+                                const toolAuthCredentialType = typeof toolAuthRecord.credentialType === "string"
+                                    ? `:${toolAuthRecord.credentialType}`
+                                    : "";
+                                const authMismatchReason = `Authorization method mismatch: delegation has ${delegationAuth.type}${delegationAuth.provider ? `:${delegationAuth.provider}` : ""}${delegationAuth.credentialType ? `:${delegationAuth.credentialType}` : ""} but tool requires ${toolAuth.type}${toolAuthProvider}${toolAuthCredentialType}`;
                                 if (this.config.audit?.enabled) {
                                     console.error("[MCP-I] ❌ Authorization method validation FAILED", {
                                         tool: toolName,
@@ -554,7 +578,7 @@ class MCPIRuntimeBase {
                                     timestamp: this.clock.now(),
                                     expiresAt: this.clock.calculateExpiry(1800),
                                 };
-                                const resumeToken = this.generateResumeToken(interceptedCall);
+                                const resumeToken = await this.generateResumeToken(interceptedCall);
                                 const consentUrl = this.buildConsentUrl(toolName, protection.requiredScopes, session, resumeToken, undefined, this.getConsentProvider(protection));
                                 this.interceptedCalls.set(resumeToken, interceptedCall);
                                 this.cleanupExpiredInterceptedCalls();
@@ -608,7 +632,7 @@ class MCPIRuntimeBase {
                                 timestamp: this.clock.now(),
                                 expiresAt: this.clock.calculateExpiry(1800),
                             };
-                            const resumeToken = this.generateResumeToken(interceptedCall);
+                            const resumeToken = await this.generateResumeToken(interceptedCall);
                             const consentUrl = this.buildConsentUrl(toolName, protection.requiredScopes, session, resumeToken, undefined, // projectId - handled by subclass override
                             this.getConsentProvider(protection) // Provider from tool config (supports both password and oauth auth)
                             );
@@ -621,8 +645,8 @@ class MCPIRuntimeBase {
                             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,
+                                error: error instanceof Error ? error.message : String(error),
+                                errorStack: error instanceof Error ? error.stack : undefined,
                             });
                         }
                         // Fail securely - require delegation on unexpected errors
@@ -633,7 +657,7 @@ class MCPIRuntimeBase {
                             timestamp: this.clock.now(),
                             expiresAt: this.clock.calculateExpiry(1800),
                         };
-                        const resumeToken = this.generateResumeToken(interceptedCall);
+                        const resumeToken = await this.generateResumeToken(interceptedCall);
                         const consentUrl = this.buildConsentUrl(toolName, protection.requiredScopes, session, resumeToken, undefined, // projectId - handled by subclass override
                         this.getConsentProvider(protection) // Provider from tool config (supports both password and oauth auth)
                         );
@@ -707,23 +731,13 @@ class MCPIRuntimeBase {
     }
     /**
      * Generate a resume token for intercepted tool call
+     *
+     * Uses cryptographically secure random bytes for token generation.
+     * The token is used as an opaque lookup key in the interceptedCalls Map.
      */
-    generateResumeToken(call) {
-        // 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)}`;
+    async generateResumeToken(_call) {
+        const bytes = await this.crypto.randomBytes(16);
+        return `resume_${this.bytesToHex(bytes)}`;
     }
     /**
      * Clean up expired intercepted calls
@@ -756,6 +770,114 @@ class MCPIRuntimeBase {
      * @param provider - Provider name (e.g., "github", "credentials") to select specific auth method
      * @returns Full consent URL with snake_case parameters
      */
+    /**
+     * MCP Apps UI consent resource URI.
+     * Single shared resource for all consent flows - tool-specific data
+     * is passed via structuredContent in the tool result.
+     */
+    static CONSENT_UI_RESOURCE_URI = "ui://mcpi-consent/authorize";
+    /**
+     * Check if the connected MCP client supports MCP Apps UI rendering.
+     * Returns false if @modelcontextprotocol/ext-apps is not installed
+     * or the client didn't advertise the io.modelcontextprotocol/ui capability.
+     *
+     * Override in subclasses to provide client capabilities from the MCP session.
+     */
+    hasUICapability(clientCapabilities) {
+        if (!clientCapabilities) {
+            console.error("[MCP-I] hasUICapability: no clientCapabilities provided");
+            return false;
+        }
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { getUiCapability, RESOURCE_MIME_TYPE } = require("@modelcontextprotocol/ext-apps/server");
+            const uiCap = getUiCapability(clientCapabilities);
+            const hasUI = uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE) ?? false;
+            console.error("[MCP-I] hasUICapability check:", {
+                hasUI,
+                uiCap: uiCap ? JSON.stringify(uiCap) : "null",
+                capabilityKeys: Object.keys(clientCapabilities),
+            });
+            return hasUI;
+        }
+        catch {
+            // ext-apps not installed - graceful degradation
+            console.error("[MCP-I] hasUICapability: ext-apps not available");
+            return false;
+        }
+    }
+    /**
+     * Mark the ext-apps SDK as available.
+     * Called by subclasses after a successful dynamic import() of the SDK,
+     * which avoids the CJS require() vs ESM incompatibility that causes
+     * the synchronous probe to fail in Cloudflare Workers.
+     */
+    setExtAppsAvailable(available) {
+        this._extAppsAvailable = available;
+    }
+    /**
+     * Check if the MCP Apps inline consent UI is enabled.
+     * Requires BOTH conditions:
+     *   1. The SDK is available (set via setExtAppsAvailable(true) after dynamic import)
+     *   2. The config flag is enabled (config.inlineConsent === true OR MCPI_INLINE_CONSENT env var)
+     * This allows merging the feature while keeping it off by default.
+     */
+    isExtAppsAvailable() {
+        return this._extAppsAvailable === true && this.config.inlineConsent === true;
+    }
+    /**
+     * Build an MCP Apps-compatible tool result that renders an inline consent UI.
+     * Returns null when the host doesn't support MCP Apps or the SDK is unavailable,
+     * allowing callers to fall back to DelegationRequiredError.
+     *
+     * @param toolName - Tool requiring delegation
+     * @param scopes - Required scopes
+     * @param session - Current session context
+     * @param resumeToken - Token to resume after delegation
+     * @param projectId - AgentShield project ID
+     * @param serverUrl - Server URL for consent approval POST
+     * @param clientCapabilities - MCP client capabilities from the session
+     */
+    buildConsentUIResult(toolName, scopes, session, resumeToken, projectId, serverUrl, clientCapabilities, authMode = "consent-only", provider) {
+        // Per the MCP Apps spec, always return UI metadata when the SDK is available.
+        // Clients that support MCP Apps will render the inline iframe;
+        // clients that don't will use the text content as fallback.
+        // The capability check is logged but not gating.
+        this.hasUICapability(clientCapabilities);
+        if (!this.isExtAppsAvailable())
+            return null;
+        // Build fallback URL for graceful degradation within the UI itself
+        const consentUrl = this.buildConsentUrl(toolName, scopes, session, resumeToken, projectId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Authorization required for tool "${toolName}". Please approve in the consent form below, or open this link to authorize in your browser: ${consentUrl}`,
+                },
+            ],
+            structuredContent: {
+                type: "consent_required",
+                authMode,
+                tool: toolName,
+                scopes,
+                agentDid: session?.agentDid || "",
+                agentName: session?.agentName || "",
+                sessionId: session?.id || "",
+                projectId: projectId || "",
+                resumeToken: resumeToken || "",
+                serverUrl: serverUrl || "",
+                consentUrl,
+                ...(provider ? { provider } : {}),
+            },
+            _meta: {
+                ui: {
+                    resourceUri: MCPIRuntimeBase.CONSENT_UI_RESOURCE_URI,
+                },
+                // Legacy flat format for backward compatibility with older clients
+                "ui/resourceUri": MCPIRuntimeBase.CONSENT_UI_RESOURCE_URI,
+            },
+        };
+    }
     buildConsentUrl(toolName, scopes, session, resumeToken, projectId, provider) {
         // Default implementation - override in subclasses
         // This URL should point to AgentShield's consent page
@@ -858,7 +980,9 @@ class MCPIRuntimeBase {
             "meta" in dataOrProof) {
             // New DetachedProof format
             const detachedProof = dataOrProof;
-            const session = proofOrSession;
+            const session = isRecord(proofOrSession)
+                ? proofOrSession
+                : undefined;
             // Use ProofVerifier if available
             if (this.proofVerifier) {
                 try {
@@ -886,12 +1010,12 @@ class MCPIRuntimeBase {
             else {
                 // Fallback to old verification if ProofVerifier not available
                 console.warn("[MCPIRuntimeBase] ProofVerifier not available, using fallback verification");
-                return this.verifyProofLegacy(dataOrProof, proofOrSession);
+                return this.verifyProofLegacy(dataOrProof, isRecord(proofOrSession) ? proofOrSession : {});
             }
         }
         else {
             // Old format (data, proof)
-            return this.verifyProofLegacy(dataOrProof, proofOrSession);
+            return this.verifyProofLegacy(dataOrProof, isRecord(proofOrSession) ? proofOrSession : {});
         }
     }
     /**
@@ -900,33 +1024,41 @@ class MCPIRuntimeBase {
      */
     async verifyProofLegacy(data, proof) {
         try {
+            const nonce = typeof proof.nonce === "string" ? proof.nonce : undefined;
+            const did = typeof proof.did === "string" ? proof.did : undefined;
+            const timestamp = typeof proof.timestamp === "number" ? proof.timestamp : undefined;
+            const signature = typeof proof.signature === "string" ? proof.signature : undefined;
+            const sessionId = typeof proof.sessionId === "string" ? proof.sessionId : undefined;
+            if (!nonce || !did || !timestamp || !signature) {
+                return false;
+            }
             // 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)) {
+            if (await this.nonceCache.has(nonce, did)) {
                 return false;
             }
             // Check timestamp is within skew
-            if (!this.clock.isWithinSkew(proof.timestamp, this.config.session?.timestampSkewSeconds || 120)) {
+            if (!this.clock.isWithinSkew(timestamp, this.config.session?.timestampSkewSeconds || 300)) {
                 return false;
             }
             // Resolve DID to get public key
-            const didDoc = await this.fetch.resolveDID(proof.did);
+            const didDoc = await this.fetch.resolveDID(did);
             const publicKey = this.extractPublicKey(didDoc);
             // Verify signature
             const proofData = {
                 data,
-                timestamp: proof.timestamp,
-                nonce: proof.nonce,
-                did: proof.did,
-                sessionId: proof.sessionId,
+                timestamp,
+                nonce,
+                did,
+                sessionId,
             };
             const dataBytes = new TextEncoder().encode(JSON.stringify(proofData));
-            const signatureBytes = this.base64ToBytes(proof.signature);
+            const signatureBytes = this.base64ToBytes(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);
+                await this.nonceCache.add(nonce, ttlSeconds, did);
             }
             return isValid;
         }
@@ -1296,13 +1428,18 @@ class MCPIRuntimeBase {
         };
     }
     extractPublicKey(didDoc) {
-        const method = didDoc.verificationMethod?.[0];
+        const verificationMethods = isRecord(didDoc)
+            ? didDoc.verificationMethod
+            : undefined;
+        const method = Array.isArray(verificationMethods)
+            ? verificationMethods[0]
+            : undefined;
         if (method?.publicKeyBase64) {
-            return method.publicKeyBase64;
+            return String(method.publicKeyBase64);
         }
         if (method?.publicKeyMultibase) {
             // Convert multibase to base64
-            return method.publicKeyMultibase; // Simplified
+            return String(method.publicKeyMultibase); // Simplified
         }
         throw new Error("Public key not found in DID document");
     }
@@ -1310,14 +1447,22 @@ class MCPIRuntimeBase {
      * Extract public key JWK from DID document
      */
     extractPublicKeyJwk(didDoc, kid) {
+        const verificationMethods = isRecord(didDoc)
+            ? didDoc.verificationMethod
+            : undefined;
+        const verificationMethodList = Array.isArray(verificationMethods)
+            ? verificationMethods
+            : [];
         // Try to find Ed25519 public key matching kid if provided
-        const verificationMethod = didDoc.verificationMethod?.find((vm) => {
-            const matchesType = vm.type === "Ed25519VerificationKey2020" ||
-                vm.type === "JsonWebKey2020";
-            const matchesKid = !kid || vm.id === kid || vm.id.endsWith(`#${kid}`);
+        const verificationMethod = verificationMethodList.find((vm) => {
+            const vmType = typeof vm.type === "string" ? vm.type : undefined;
+            const vmId = typeof vm.id === "string" ? vm.id : undefined;
+            const matchesType = vmType === "Ed25519VerificationKey2020" ||
+                vmType === "JsonWebKey2020";
+            const matchesKid = !kid || vmId === kid || vmId?.endsWith(`#${kid}`);
             return matchesType && matchesKid;
-        }) || didDoc.verificationMethod?.[0]; // Fallback to first method
-        if (verificationMethod?.publicKeyJwk) {
+        }) || verificationMethodList[0]; // Fallback to first method
+        if (verificationMethod && isRecord(verificationMethod.publicKeyJwk)) {
             const jwk = verificationMethod.publicKeyJwk;
             // Ensure it's Ed25519 format
             if (jwk.kty === "OKP" && jwk.crv === "Ed25519") {

package/dist/runtime/ext-apps-constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP Apps Extension Constants
+ *
+ * Shared constants for the MCP Apps consent UI integration.
+ * Kept separate from the runtime class so consumers can import
+ * without pulling in the full MCPIRuntimeBase dependency.
+ */
+/**
+ * URI for the shared consent UI resource.
+ * All consent-requiring tools reference this single resource;
+ * tool-specific data is passed via structuredContent.
+ */
+export declare const CONSENT_UI_RESOURCE_URI = "ui://mcpi-consent/authorize";
+//# sourceMappingURL=ext-apps-constants.d.ts.map