@kya-os/mcp-i-cloudflare 1.5.8-canary.6 → 1.5.8-canary.61

package/dist/adapter.js

@@ -13,6 +13,8 @@ import { WELL_KNOWN_CORS_HEADERS, MCP_CORS_HEADERS, PREFLIGHT_CORS_HEADERS, } fr
 import { KVProofArchive } from "./storage/kv-proof-archive";
 import { STORAGE_KEYS } from "./constants/storage-keys";
 import { DEFAULT_SESSION_CACHE_TTL } from "./constants";
+import { normalizeCloudflareEnv } from "./helpers/env-mapper";
+import { AdminService } from "./services/admin.service";
 const INITIALIZE_CONTEXT_TTL_MS = 60_000;
 /**
  * Lightweight MCP protocol implementation for Cloudflare Workers
@@ -77,60 +79,147 @@ class CloudflareMCPServer {
             }
             // Call tool with identity/proof wrapping
             if (method === "tools/call") {
+                // Entry point logging for debugging
+                console.log("🔵 [CloudflareMCPServer] handleRequest: tools/call", {
+                    toolName: params.name,
+                    hasParams: !!params,
+                    paramsKeys: params ? Object.keys(params) : [],
+                });
                 const toolName = params.name;
                 const tool = this.tools.get(toolName);
                 if (!tool) {
                     throw new Error(`Tool not found: ${toolName}`);
                 }
                 // Get current session if available (stateful environments like Node.js)
-                let session = await this.runtime.getCurrentSession();
+                // Wrap in try-catch to catch any exceptions
+                let session = null;
+                try {
+                    session = await this.runtime.getCurrentSession();
+                    console.log("[CloudflareMCPServer] Session check:", {
+                        hasSession: !!session,
+                        sessionId: session?.id?.slice(0, 20) + "..." || "none",
+                        hasDelegationToken: !!session?.delegationToken,
+                        hasDelegationStorage: !!this.delegationStorage,
+                        method: "tools/call",
+                        toolName,
+                    });
+                }
+                catch (error) {
+                    console.error("[CloudflareMCPServer] Error in getCurrentSession:", error);
+                    // Continue with null session (will create ephemeral)
+                }
                 // For stateless environments (Cloudflare Workers), create ephemeral session
                 if (!session) {
+                    // Extract session_id from params if available (from consent flow)
+                    // This allows us to retrieve delegation tokens stored with the original session_id
+                    const providedSessionId = params.session_id || params.sessionId;
                     const timestamp = Date.now();
                     const randomSuffix = Math.random().toString(36).substring(2, 10);
                     const agentDid = (await this.runtime.getIdentity()).did;
-                    const sessionId = `ephemeral-${timestamp}-${randomSuffix}`;
+                    // Use provided session_id if available, otherwise create ephemeral
+                    const sessionId = providedSessionId || `ephemeral-${timestamp}-${randomSuffix}`;
+                    console.log("[CloudflareMCPServer] Creating session:", {
+                        sessionId: sessionId.slice(0, 20) + "...",
+                        isProvided: !!providedSessionId,
+                        isEphemeral: !providedSessionId,
+                    });
+                    // Extract OAuth identity from request or session cache for persistent userDid lookup
+                    let oauthIdentity = undefined;
+                    if (meta?.request) {
+                        oauthIdentity = this.extractOAuthIdentityFromRequest(meta.request);
+                        if (oauthIdentity) {
+                            console.log("[CloudflareMCPServer] Extracted OAuth identity from request:", {
+                                provider: oauthIdentity.provider,
+                                subject: oauthIdentity.subject.substring(0, 20) + "...",
+                            });
+                        }
+                    }
+                    // If OAuth identity not in request, try to get from session cache
+                    if (!oauthIdentity && sessionId && this.delegationStorage) {
+                        try {
+                            const sessionKey = STORAGE_KEYS.session(sessionId);
+                            const sessionData = (await this.delegationStorage.get(sessionKey, "json"));
+                            if (sessionData?.oauthIdentity?.provider) {
+                                // Note: We only have subjectHash in session cache (PII protection)
+                                // We can't fully reconstruct OAuth identity, but we can use it to lookup userDid
+                                console.log("[CloudflareMCPServer] Found OAuth identity in session cache:", {
+                                    provider: sessionData.oauthIdentity.provider,
+                                    hasSubjectHash: !!sessionData.oauthIdentity.subjectHash,
+                                });
+                                // OAuth identity from session cache is incomplete (subjectHash only), so we'll use it for userDid lookup via storage
+                            }
+                        }
+                        catch (error) {
+                            console.warn("[CloudflareMCPServer] Failed to get OAuth identity from session:", error);
+                            // Non-fatal - continue without OAuth identity
+                        }
+                    }
                     // Check KV storage for stored delegation token if not provided in params
                     let delegationToken = params.delegationToken;
                     if (!delegationToken && this.delegationStorage) {
                         try {
-                            // Get userDID from params or session if available
-                            // TODO: Properly map credentials to userDID for multi-user scenarios
-                            // Currently, we use agent-scoped keys which can cause conflicts when multiple
-                            // users delegate to the same agent. The ideal key structure should be:
-                            // - `user:${userDid}:agent:${agentDid}:delegation` (user+agent scoped - most specific)
-                            // - `agent:${agentDid}:delegation` (agent-scoped fallback for single-user agents)
-                            //
-                            // To implement this properly:
-                            // 1. Capture userDID in consent approval flow (from OAuth or session)
-                            // 2. Store tokens with userDID in the key: `user:${userDid}:agent:${agentDid}:delegation`
-                            // 3. Retrieve tokens by userDID + agentDID combination
-                            // 4. Fall back to agent-scoped key for backward compatibility
-                            const userDid = params.clientDid || params.userDid; // Try to get userDID from request
-                            // PRIORITY 1: Try agent-scoped token FIRST (stable across sessions)
-                            // This is the most reliable lookup since sessions are ephemeral in Cloudflare Workers
-                            // The consent service stores tokens with this key format
-                            const agentKey = `agent:${agentDid}:delegation`;
-                            const agentToken = await this.delegationStorage.get(agentKey);
-                            if (agentToken) {
-                                delegationToken = agentToken;
-                                console.log("[CloudflareMCPServer] ✅ Delegation token retrieved from agent-scoped key:", {
-                                    agentDid: agentDid.slice(0, 20) + "...",
-                                    key: agentKey,
-                                    tokenLength: agentToken.length,
-                                });
-                                // Cache it for this session for faster future lookups
-                                if (sessionId) {
-                                    await this.delegationStorage.put(`session:${sessionId}`, agentToken, {
-                                        expirationTtl: 1800, // 30 minutes
-                                    });
+                            // Get userDID from params first
+                            let userDid = params.clientDid || params.userDid;
+                            // ✅ PRIORITY 1: If OAuth identity available, use it to lookup persistent userDid
+                            if (!userDid && oauthIdentity && this.delegationStorage) {
+                                try {
+                                    const oauthKey = STORAGE_KEYS.oauthIdentity(oauthIdentity.provider, oauthIdentity.subject);
+                                    const mappedUserDid = await this.delegationStorage.get(oauthKey, "text");
+                                    if (mappedUserDid) {
+                                        userDid = mappedUserDid;
+                                        console.log("[CloudflareMCPServer] ✅ Retrieved persistent userDid from OAuth mapping:", {
+                                            provider: oauthIdentity.provider,
+                                            userDid: userDid.slice(0, 20) + "...",
+                                        });
+                                    }
+                                }
+                                catch (error) {
+                                    console.warn("[CloudflareMCPServer] Failed to lookup userDid from OAuth mapping:", error);
+                                    // Non-fatal - continue with session cache lookup
                                 }
                             }
-                            // PRIORITY 2: Try user+agent scoped token (if userDID is available)
-                            // This is the preferred approach for multi-user scenarios
-                            if (!delegationToken && userDid) {
-                                const userAgentKey = `delegation:user:${userDid}:agent:${agentDid}`;
-                                const userAgentToken = await this.delegationStorage.get(userAgentKey);
+                            // ✅ PRIORITY 2: If userDid not in params or OAuth mapping, try to retrieve from session cache
+                            if (!userDid && sessionId) {
+                                try {
+                                    const sessionKey = STORAGE_KEYS.session(sessionId);
+                                    const sessionData = (await this.delegationStorage.get(sessionKey, "json"));
+                                    if (sessionData?.userDid) {
+                                        userDid = sessionData.userDid;
+                                        console.log("[CloudflareMCPServer] ✅ Retrieved userDid from session cache:", {
+                                            userDid: userDid.slice(0, 20) + "...",
+                                            sessionId: sessionId.slice(0, 20) + "...",
+                                        });
+                                    }
+                                }
+                                catch (error) {
+                                    console.warn("[CloudflareMCPServer] Failed to get userDid from session:", error);
+                                    // Non-fatal - continue without userDid
+                                }
+                            }
+                            console.log("[CloudflareMCPServer] 🔍 Starting delegation token lookup from KV:", {
+                                agentDid: agentDid.slice(0, 20) + "...",
+                                userDid: userDid?.slice(0, 20) + "..." || "none",
+                                sessionId: sessionId?.slice(0, 20) + "..." || "none",
+                                hasDelegationStorage: !!this.delegationStorage,
+                            });
+                            // PRIORITY 1: Try user+agent scoped token (user-specific, most secure)
+                            // This is the preferred approach for multi-user scenarios with proper user isolation
+                            if (userDid) {
+                                const userAgentKey = STORAGE_KEYS.delegation(userDid, agentDid);
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 1: Checking user+agent scoped key:", {
+                                    key: userAgentKey,
+                                    userDid: userDid.slice(0, 20) + "...",
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                });
+                                const userAgentToken = await this.delegationStorage.get(userAgentKey, "text");
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 1: User+agent scoped lookup result:", {
+                                    key: userAgentKey,
+                                    found: !!userAgentToken,
+                                    tokenLength: userAgentToken?.length || 0,
+                                    tokenPreview: userAgentToken
+                                        ? userAgentToken.substring(0, 20) + "..."
+                                        : null,
+                                });
                                 if (userAgentToken) {
                                     delegationToken = userAgentToken;
                                     console.log("[CloudflareMCPServer] ✅ Delegation token retrieved from user+agent scoped key:", {
@@ -140,19 +229,42 @@ class CloudflareMCPServer {
                                         tokenLength: userAgentToken.length,
                                     });
                                     // Cache it for this session for faster future lookups
-                                    if (sessionId) {
-                                        await this.delegationStorage.put(`session:${sessionId}`, userAgentToken, {
+                                    // Store full session data object to match consent service format
+                                    if (this.delegationStorage && sessionId) {
+                                        const sessionKey = STORAGE_KEYS.session(sessionId);
+                                        // Read existing session data to preserve userDid and other fields
+                                        const existingSession = (await this.delegationStorage.get(sessionKey, "json"));
+                                        await this.delegationStorage.put(sessionKey, JSON.stringify({
+                                            ...existingSession,
+                                            userDid,
+                                            agentDid,
+                                            delegationToken: userAgentToken,
+                                            cachedAt: Date.now(),
+                                        }), {
                                             expirationTtl: 1800, // 30 minutes
                                         });
                                     }
                                 }
                             }
-                            // PRIORITY 3: Try session-scoped token (if session ID was persisted)
+                            // PRIORITY 2: Try session-scoped token (if session ID was persisted)
                             // Note: Sessions are ephemeral in Cloudflare Workers, so this is mainly
                             // useful for caching tokens within a single request chain
                             if (!delegationToken && sessionId) {
                                 const sessionKey = STORAGE_KEYS.session(sessionId);
-                                const sessionData = await this.delegationStorage.get(sessionKey, "json");
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 2: Checking session-scoped key:", {
+                                    key: sessionKey,
+                                    sessionId: sessionId.slice(0, 20) + "...",
+                                });
+                                const sessionData = (await this.delegationStorage.get(sessionKey, "json"));
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 2: Session-scoped lookup result:", {
+                                    key: sessionKey,
+                                    found: !!sessionData,
+                                    hasDelegationToken: !!sessionData?.delegationToken,
+                                    tokenLength: sessionData?.delegationToken?.length || 0,
+                                    tokenPreview: sessionData?.delegationToken
+                                        ? sessionData.delegationToken.substring(0, 20) + "..."
+                                        : null,
+                                });
                                 if (sessionData?.delegationToken) {
                                     delegationToken = sessionData.delegationToken;
                                     console.log("[CloudflareMCPServer] ✅ Delegation token retrieved from session cache:", {
@@ -161,16 +273,73 @@ class CloudflareMCPServer {
                                     });
                                 }
                             }
+                            // PRIORITY 3: Try agent-scoped token (legacy fallback - DEPRECATED)
+                            // Only use when userDid is unavailable (backward compatibility)
+                            // WARNING: This allows cross-user delegation sharing - migrate to user+agent scoped tokens
+                            if (!delegationToken && !userDid) {
+                                const agentKey = STORAGE_KEYS.legacyDelegation(agentDid);
+                                console.warn("[CloudflareMCPServer] ⚠️ DEPRECATION: Using agent-scoped token (legacy format). Migrate to user+agent scoped tokens for proper user isolation.", {
+                                    key: agentKey,
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                    reason: "userDid unavailable",
+                                });
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 3: Checking agent-scoped key (legacy):", {
+                                    key: agentKey,
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                });
+                                const agentToken = await this.delegationStorage.get(agentKey, "text");
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 3: Agent-scoped lookup result:", {
+                                    key: agentKey,
+                                    found: !!agentToken,
+                                    tokenLength: agentToken?.length || 0,
+                                    tokenPreview: agentToken
+                                        ? agentToken.substring(0, 20) + "..."
+                                        : null,
+                                });
+                                if (agentToken) {
+                                    delegationToken = agentToken;
+                                    console.log("[CloudflareMCPServer] ✅ Delegation token retrieved from agent-scoped key (legacy):", {
+                                        agentDid: agentDid.slice(0, 20) + "...",
+                                        key: agentKey,
+                                        tokenLength: agentToken.length,
+                                    });
+                                    // Cache it for this session for faster future lookups
+                                    // Store full session data object to match consent service format
+                                    if (this.delegationStorage && sessionId) {
+                                        const sessionKey = STORAGE_KEYS.session(sessionId);
+                                        // Read existing session data to preserve userDid and other fields
+                                        const existingSession = (await this.delegationStorage.get(sessionKey, "json"));
+                                        await this.delegationStorage.put(sessionKey, JSON.stringify({
+                                            ...existingSession,
+                                            userDid,
+                                            agentDid,
+                                            delegationToken: agentToken,
+                                            cachedAt: Date.now(),
+                                        }), {
+                                            expirationTtl: 1800, // 30 minutes
+                                        });
+                                    }
+                                }
+                            }
                             if (!delegationToken) {
+                                const checkedKeys = [];
+                                // Only include agent-scoped key if it was checked (when userDid unavailable)
+                                if (!userDid) {
+                                    checkedKeys.push(STORAGE_KEYS.legacyDelegation(agentDid));
+                                }
+                                // Always include user+agent scoped key if userDid is available
+                                if (userDid) {
+                                    checkedKeys.push(STORAGE_KEYS.delegation(userDid, agentDid));
+                                }
+                                // Always include session-scoped key if sessionId is available
+                                if (sessionId) {
+                                    checkedKeys.push(STORAGE_KEYS.session(sessionId));
+                                }
                                 console.log("[CloudflareMCPServer] ⚠️ No delegation token found in KV storage:", {
                                     agentDid: agentDid.slice(0, 20) + "...",
                                     userDid: userDid?.slice(0, 20) + "..." || "none",
                                     sessionId: sessionId?.slice(0, 20) + "..." || "none",
-                                    checkedKeys: [
-                                        agentKey,
-                                        userDid ? `delegation:user:${userDid}:agent:${agentDid}` : null,
-                                        sessionId ? STORAGE_KEYS.session(sessionId) : null,
-                                    ].filter(Boolean),
+                                    checkedKeys: checkedKeys.filter(Boolean),
                                 });
                             }
                         }
@@ -193,9 +362,195 @@ class CloudflareMCPServer {
                         serverOrigin: this.requestOrigin,
                         // These fields are for ephemeral sessions - won't persist
                     };
+                    // ✅ CRITICAL: Log delegation token status before processToolCall
+                    console.log("[CloudflareMCPServer] ✅ Session created with delegation token status:", {
+                        sessionId: sessionId.slice(0, 20) + "...",
+                        hasDelegationToken: !!delegationToken,
+                        delegationTokenLength: delegationToken?.length || 0,
+                        delegationTokenSource: params.delegationToken
+                            ? "params"
+                            : delegationToken
+                                ? "kv-storage"
+                                : "none",
+                        agentDid: agentDid.slice(0, 20) + "...",
+                    });
                 }
                 else {
-                    // For existing sessions, update delegation fields if provided
+                    // For existing sessions, check KV storage for delegation token if not already set
+                    // This ensures newly created delegations are found even for existing sessions
+                    console.log("[CloudflareMCPServer] Existing session detected, checking KV storage:", {
+                        hasSession: !!session,
+                        hasDelegationToken: !!session?.delegationToken,
+                        hasDelegationStorage: !!this.delegationStorage,
+                        sessionId: session?.id?.slice(0, 20) + "...",
+                        sessionKeys: Object.keys(session || {}),
+                    });
+                    if (!session.delegationToken && this.delegationStorage) {
+                        console.log("[CloudflareMCPServer] ⚠️ Session has no delegationToken, attempting KV lookup...");
+                        try {
+                            const agentDid = (await this.runtime.getIdentity()).did;
+                            // ✅ CRITICAL: Retrieve userDid from session cache if not in session object
+                            // Check session cache first, then params, then session object
+                            let userDid = session.userDid ||
+                                params.clientDid ||
+                                params.userDid ||
+                                session.clientDid;
+                            const sessionId = session.id;
+                            // If userDid still not found, try retrieving from session cache
+                            if (!userDid && sessionId && this.delegationStorage) {
+                                try {
+                                    const sessionKey = STORAGE_KEYS.session(sessionId);
+                                    const sessionData = (await this.delegationStorage.get(sessionKey, "json"));
+                                    if (sessionData?.userDid) {
+                                        userDid = sessionData.userDid;
+                                        // Update session object with retrieved userDid
+                                        session.userDid = userDid;
+                                        console.log("[CloudflareMCPServer] ✅ Retrieved userDid from session cache for delegation lookup:", {
+                                            userDid: userDid.slice(0, 20) + "...",
+                                            sessionId: sessionId.slice(0, 20) + "...",
+                                        });
+                                    }
+                                }
+                                catch (error) {
+                                    console.warn("[CloudflareMCPServer] Failed to get userDid from session cache:", error);
+                                }
+                            }
+                            console.log("[CloudflareMCPServer] 🔍 Looking up delegation token for existing session:", {
+                                sessionId: sessionId?.slice(0, 20) + "...",
+                                userDid: userDid?.slice(0, 20) + "...",
+                                agentDid: agentDid?.slice(0, 20) + "...",
+                            });
+                            // PRIORITY 1: Try user+agent scoped token (user-specific, most secure)
+                            // This is the preferred approach for multi-user scenarios with proper user isolation
+                            let delegationToken = undefined;
+                            if (userDid) {
+                                const userAgentKey = STORAGE_KEYS.delegation(userDid, agentDid);
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 1: Checking user+agent scoped key (existing session):", {
+                                    key: userAgentKey,
+                                    userDid: userDid.slice(0, 20) + "...",
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                });
+                                const userAgentToken = await this.delegationStorage.get(userAgentKey, "text");
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 1: User+agent scoped lookup result:", {
+                                    key: userAgentKey,
+                                    found: !!userAgentToken,
+                                    tokenLength: userAgentToken?.length || 0,
+                                });
+                                if (userAgentToken) {
+                                    delegationToken = userAgentToken;
+                                }
+                            }
+                            // PRIORITY 2: Try session-scoped token (if session ID was persisted)
+                            if (!delegationToken && sessionId) {
+                                const sessionKey = STORAGE_KEYS.session(sessionId);
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 2: Checking session-scoped key (existing session):", {
+                                    key: sessionKey,
+                                    sessionId: sessionId.slice(0, 20) + "...",
+                                });
+                                const sessionData = (await this.delegationStorage.get(sessionKey, "json"));
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 2: Session-scoped lookup result:", {
+                                    key: sessionKey,
+                                    found: !!sessionData,
+                                    hasDelegationToken: !!sessionData?.delegationToken,
+                                    tokenLength: sessionData?.delegationToken?.length || 0,
+                                });
+                                if (sessionData?.delegationToken) {
+                                    delegationToken = sessionData.delegationToken;
+                                }
+                            }
+                            // PRIORITY 3: Try agent-scoped token (legacy fallback - DEPRECATED)
+                            // Only use when userDid is unavailable (backward compatibility)
+                            if (!delegationToken && !userDid) {
+                                const agentKey = STORAGE_KEYS.legacyDelegation(agentDid);
+                                console.warn("[CloudflareMCPServer] ⚠️ DEPRECATION: Using agent-scoped token (legacy format). Migrate to user+agent scoped tokens for proper user isolation.", {
+                                    key: agentKey,
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                    reason: "userDid unavailable",
+                                });
+                                console.log("[CloudflareMCPServer] 🔍 PRIORITY 3: Checking agent-scoped key (legacy, existing session):", {
+                                    key: agentKey,
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                });
+                                try {
+                                    const agentToken = await this.delegationStorage.get(agentKey, "text");
+                                    console.log("[CloudflareMCPServer] 🔍 PRIORITY 3: Agent-scoped lookup result:", {
+                                        key: agentKey,
+                                        found: !!agentToken,
+                                        tokenLength: agentToken?.length || 0,
+                                    });
+                                    if (agentToken) {
+                                        delegationToken = agentToken;
+                                        console.log("[CloudflareMCPServer] ✅ Delegation token retrieved from agent-scoped key (legacy, existing session):", {
+                                            agentDid: agentDid.slice(0, 20) + "...",
+                                            key: agentKey,
+                                            tokenLength: agentToken.length,
+                                        });
+                                    }
+                                }
+                                catch (error) {
+                                    console.error("[CloudflareMCPServer] Error retrieving agent token:", error);
+                                }
+                            }
+                            // ✅ CRITICAL: Set delegation token on session if found
+                            if (delegationToken) {
+                                session = {
+                                    ...session,
+                                    delegationToken,
+                                };
+                                console.log("[CloudflareMCPServer] ✅ Delegation token set on existing session:", {
+                                    sessionId: sessionId?.slice(0, 20) + "..." || "none",
+                                    tokenLength: delegationToken.length,
+                                    sessionHasToken: !!session.delegationToken,
+                                    source: "kv-storage",
+                                });
+                            }
+                            else {
+                                const checkedKeys = [];
+                                // Only include agent-scoped key if it was checked (when userDid unavailable)
+                                if (!userDid) {
+                                    checkedKeys.push(STORAGE_KEYS.legacyDelegation(agentDid));
+                                }
+                                // Always include user+agent scoped key if userDid is available
+                                if (userDid) {
+                                    checkedKeys.push(STORAGE_KEYS.delegation(userDid, agentDid));
+                                }
+                                // Always include session-scoped key if sessionId is available
+                                if (sessionId) {
+                                    checkedKeys.push(STORAGE_KEYS.session(sessionId));
+                                }
+                                console.log("[CloudflareMCPServer] ⚠️ No delegation token found in KV storage for existing session:", {
+                                    sessionId: sessionId?.slice(0, 20) + "..." || "none",
+                                    checkedKeys: checkedKeys.filter(Boolean),
+                                });
+                            }
+                            // Final check - log if we still don't have a token
+                            if (!session.delegationToken) {
+                                console.log("[CloudflareMCPServer] ❌ FINAL CHECK: Still no delegation token after all KV lookups:", {
+                                    sessionId: session?.id?.slice(0, 20) + "..." || "none",
+                                    userDid: userDid?.slice(0, 20) + "..." || "none",
+                                    agentDid: agentDid.slice(0, 20) + "...",
+                                    checkedKeys: [
+                                        sessionId ? STORAGE_KEYS.session(sessionId) : null,
+                                        userDid
+                                            ? STORAGE_KEYS.delegation(userDid, agentDid)
+                                            : null,
+                                        STORAGE_KEYS.legacyDelegation(agentDid),
+                                    ].filter(Boolean),
+                                });
+                            }
+                            else {
+                                console.log("[CloudflareMCPServer] ✅ FINAL CHECK: Delegation token found:", {
+                                    tokenLength: session.delegationToken.length,
+                                    sessionHasToken: !!session.delegationToken,
+                                });
+                            }
+                        }
+                        catch (error) {
+                            // Log but don't fail - delegation lookup is best-effort
+                            console.error("[CloudflareMCPServer] Failed to retrieve delegation token from KV (existing session):", error);
+                        }
+                    }
+                    // Update delegation fields if provided in params (takes precedence)
                     if (params.delegationToken) {
                         session.delegationToken = params.delegationToken;
                     }
@@ -227,6 +582,59 @@ class CloudflareMCPServer {
                 session.toolName = toolName;
                 session.toolParams = params.arguments || {};
                 session.scopeId = scopeId; // ✅ ADDED: Pass scopeId for tool auto-discovery
+                // ✅ CRITICAL: Verify delegation token is set on session before processToolCall
+                // Also do a final KV lookup if token is still missing (defensive check)
+                // Use same 3-priority lookup: user+agent scoped, then session-scoped, then agent-scoped (last resort)
+                if (!session?.delegationToken && this.delegationStorage) {
+                    try {
+                        const agentDid = (await this.runtime.getIdentity()).did;
+                        const userDid = session.userDid || params.clientDid || params.userDid;
+                        let finalToken = undefined;
+                        // PRIORITY 1: User+agent scoped token
+                        if (userDid) {
+                            const userAgentKey = STORAGE_KEYS.delegation(userDid, agentDid);
+                            const token = await this.delegationStorage.get(userAgentKey, "text");
+                            finalToken = token || undefined; // Convert null to undefined
+                        }
+                        // PRIORITY 2: Session-scoped token
+                        if (!finalToken && session.id) {
+                            const sessionKey = STORAGE_KEYS.session(session.id);
+                            const sessionData = (await this.delegationStorage.get(sessionKey, "json"));
+                            finalToken = sessionData?.delegationToken;
+                        }
+                        // PRIORITY 3: Agent-scoped token (legacy fallback - only if userDid unavailable)
+                        if (!finalToken && !userDid) {
+                            const agentKey = STORAGE_KEYS.legacyDelegation(agentDid);
+                            const token = await this.delegationStorage.get(agentKey, "text");
+                            finalToken = token || undefined; // Convert null to undefined
+                        }
+                        if (finalToken) {
+                            session.delegationToken = finalToken;
+                            console.log("[CloudflareMCPServer] ✅ Final KV lookup succeeded, token set on session:", {
+                                toolName,
+                                agentDid: agentDid.slice(0, 20) + "...",
+                                userDid: userDid?.slice(0, 20) + "..." || "none",
+                                tokenLength: finalToken.length,
+                                source: userDid
+                                    ? session.id
+                                        ? "session-scoped"
+                                        : "user+agent-scoped"
+                                    : "agent-scoped (legacy)",
+                            });
+                        }
+                    }
+                    catch (error) {
+                        console.error("[CloudflareMCPServer] Final KV lookup failed:", error);
+                    }
+                }
+                console.log("[CloudflareMCPServer] ✅ About to call processToolCall with session:", {
+                    toolName,
+                    sessionId: session?.id?.slice(0, 20) + "..." || "none",
+                    hasDelegationToken: !!session?.delegationToken,
+                    delegationTokenLength: session?.delegationToken?.length || 0,
+                    hasConsentProof: !!session?.consentProof,
+                    agentDid: session?.agentDid?.slice(0, 20) + "..." || "none",
+                });
                 // ✅ Use processToolCall which handles delegation checks AND proof generation
                 // This ensures delegation is checked BEFORE tool execution
                 // If delegation is required but not provided, this will throw DelegationRequiredError
@@ -277,31 +685,27 @@ class CloudflareMCPServer {
                             normalizedClientInfo.capabilities;
                     }
                 }
-                // Phase 4 PR #5: Extract OAuth identity and lookup persistent User DID BEFORE handshake
-                let userDid = undefined;
-                if (this.delegationStorage && meta?.request) {
-                    const oauthIdentity = this.extractOAuthIdentityFromRequest(meta.request);
+                // Phase 4 PR #5: Extract OAuth identity BEFORE handshake and pass to runtime
+                let oauthIdentity = undefined;
+                if (meta?.request) {
+                    oauthIdentity = this.extractOAuthIdentityFromRequest(meta.request);
                     if (oauthIdentity) {
-                        try {
-                            const oauthKey = STORAGE_KEYS.oauthIdentity(oauthIdentity.provider, oauthIdentity.subject);
-                            const mappedUserDid = await this.delegationStorage.get(oauthKey, "text");
-                            if (mappedUserDid) {
-                                userDid = mappedUserDid;
-                                console.log("[Adapter] Found persistent User DID for return user:", {
-                                    provider: oauthIdentity.provider,
-                                    userDid: userDid.substring(0, 20) + "...",
-                                });
-                            }
-                        }
-                        catch (error) {
-                            console.warn("[Adapter] Failed to lookup persistent User DID:", error);
-                            // Non-fatal - continue with handshake
-                        }
+                        console.log("[Adapter] Extracted OAuth identity for handshake:", {
+                            provider: oauthIdentity.provider,
+                            subject: oauthIdentity.subject.substring(0, 20) + "...",
+                        });
+                        // Add OAuth identity to handshake payload for persistent user DID lookup
+                        // Type assertion needed because HandshakeRequest doesn't include oauthIdentity,
+                        // but handleHandshake accepts it via intersection type
+                        handshakePayload.oauthIdentity = oauthIdentity;
                     }
                 }
                 const handshakeResult = await this.runtime.handleHandshake(handshakePayload);
-                // Phase 4 PR #5: Store User DID and clientId in session AFTER handshake
-                if (userDid && this.delegationStorage && handshakeResult.sessionId) {
+                // Get userDid from handshake result (may have been retrieved via OAuth mapping)
+                const userDid = handshakeResult.userDid;
+                // Phase 4 PR #5: Store User DID, OAuth identity (with redacted subject), and clientId in session AFTER handshake
+                // Only store if userDid is available (from OAuth mapping or handshake result)
+                if (this.delegationStorage && handshakeResult.sessionId && userDid) {
                     try {
                         const sessionKey = STORAGE_KEYS.session(handshakeResult.sessionId);
                         const existingSession = (await this.delegationStorage.get(sessionKey, "json"));
@@ -309,16 +713,31 @@ class CloudflareMCPServer {
                         const clientId = handshakePayload.clientInfo?.clientId;
                         // Get agentDid from runtime identity
                         const agentDid = (await this.runtime.getIdentity()).did;
+                        // Store OAuth identity with redacted subject for PII protection
+                        const oauthIdentityForStorage = oauthIdentity
+                            ? {
+                                provider: oauthIdentity.provider,
+                                subjectHash: oauthIdentity.subject.substring(0, 8), // Redact full subject
+                                // Don't store email, name, or full subject for PII protection
+                            }
+                            : undefined;
                         await this.delegationStorage.put(sessionKey, JSON.stringify({
                             ...(existingSession || {}),
                             userDid,
                             agentDid,
                             ...(clientId && { clientId }),
+                            ...(oauthIdentityForStorage && {
+                                oauthIdentity: oauthIdentityForStorage,
+                            }),
                         }), { expirationTtl: DEFAULT_SESSION_CACHE_TTL });
-                        console.log("[Adapter] Stored User DID, agentDid, and clientId in session for return user");
+                        console.log("[Adapter] Stored User DID, agentDid, clientId, and OAuth identity (redacted) in session", {
+                            hasUserDid: !!userDid,
+                            hasOAuth: !!oauthIdentity,
+                            provider: oauthIdentity?.provider,
+                        });
                     }
                     catch (error) {
-                        console.warn("[Adapter] Failed to store User DID in session:", error);
+                        console.warn("[Adapter] Failed to store session data:", error);
                         // Non-fatal - continue
                     }
                 }
@@ -356,6 +775,31 @@ class CloudflareMCPServer {
                     },
                 };
             }
+            // Check if this is an OAuthRequiredError - include OAuth URL in response
+            if (error &&
+                (error.name === "OAuthRequiredError" ||
+                    error.constructor?.name === "OAuthRequiredError")) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: {
+                        code: -32002, // Custom error code for OAuth required
+                        message: error.oauthUrl
+                            ? `${error.message || `OAuth required for tool "${error.toolName || "unknown"}"`}. <authorization_url>${error.oauthUrl}</authorization_url>`
+                            : error.message ||
+                                `OAuth required for tool "${error.toolName || "unknown"}"`,
+                        data: {
+                            toolName: error.toolName,
+                            requiredScopes: error.requiredScopes || [],
+                            provider: error.provider,
+                            oauthUrl: error.oauthUrl,
+                            resumeToken: error.resumeToken,
+                            // MCP-I specific: provide authorization URL for client to display
+                            authorizationUrl: error.oauthUrl,
+                        },
+                    },
+                };
+            }
             // Generic error handler
             let errorMessage = "Internal error";
             if (error) {
@@ -466,8 +910,7 @@ class CloudflareMCPServer {
         const name = typeof nameValue === "string" && nameValue.trim().length > 0
             ? nameValue.trim()
             : "unknown";
-        const clientId = handshakeClientId ||
-            crypto.randomUUID();
+        const clientId = handshakeClientId || crypto.randomUUID();
         const capabilities = this.isRecord(request.clientCapabilities)
             ? request.clientCapabilities
             : initializeContext?.capabilities;
@@ -548,16 +991,131 @@ class CloudflareMCPServer {
                 return null;
             const cookieValue = oauthCookie.substring(equalsIndex + 1);
             const parsed = JSON.parse(decodeURIComponent(cookieValue));
-            // Validate required fields
-            if (parsed && parsed.provider && parsed.subject) {
-                return parsed;
+            // ✅ SECURITY: Validate OAuth identity format and content
+            const validationResult = this.validateOAuthIdentity(parsed);
+            if (!validationResult.valid) {
+                console.warn("[Adapter] ⚠️ OAuth identity validation failed:", validationResult.reason, { parsed });
+                return null;
             }
+            return parsed;
         }
         catch (error) {
             console.warn("[Adapter] Failed to extract OAuth identity from cookies:", error);
         }
         return null;
     }
+    /**
+     * Validate OAuth identity format and content
+     *
+     * Ensures:
+     * - Provider is non-empty string (1-50 chars)
+     * - Subject is non-empty string (1-255 chars)
+     * - Provider matches expected format (alphanumeric, hyphens, underscores)
+     * - Subject matches expected format (non-empty, reasonable length)
+     *
+     * @param identity - Parsed OAuth identity object
+     * @returns Validation result
+     */
+    validateOAuthIdentity(identity) {
+        // Check if identity is an object
+        if (!identity || typeof identity !== "object") {
+            return { valid: false, reason: "OAuth identity must be an object" };
+        }
+        const oauth = identity;
+        // Validate provider
+        if (!oauth.provider || typeof oauth.provider !== "string") {
+            return {
+                valid: false,
+                reason: "OAuth provider is required and must be a string",
+            };
+        }
+        const provider = oauth.provider.trim();
+        if (provider.length === 0) {
+            return { valid: false, reason: "OAuth provider cannot be empty" };
+        }
+        if (provider.length > 50) {
+            return {
+                valid: false,
+                reason: "OAuth provider must be 50 characters or less",
+            };
+        }
+        // Provider format: alphanumeric, hyphens, underscores, dots (e.g., "google", "microsoft", "github", "custom-provider")
+        const providerPattern = /^[a-zA-Z0-9._-]+$/;
+        if (!providerPattern.test(provider)) {
+            return {
+                valid: false,
+                reason: `OAuth provider must match pattern [a-zA-Z0-9._-]: "${provider}"`,
+            };
+        }
+        // Validate subject
+        if (!oauth.subject || typeof oauth.subject !== "string") {
+            return {
+                valid: false,
+                reason: "OAuth subject is required and must be a string",
+            };
+        }
+        const subject = oauth.subject.trim();
+        if (subject.length === 0) {
+            return { valid: false, reason: "OAuth subject cannot be empty" };
+        }
+        if (subject.length > 255) {
+            return {
+                valid: false,
+                reason: "OAuth subject must be 255 characters or less",
+            };
+        }
+        // Subject format: non-empty, reasonable characters (allows most Unicode, but prevents control chars)
+        // OAuth subjects can be numeric IDs, email-like strings, or other identifiers
+        const subjectPattern = /^[\S]+$/; // At least one non-whitespace character
+        if (!subjectPattern.test(subject)) {
+            return {
+                valid: false,
+                reason: `OAuth subject contains invalid characters: "${subject.substring(0, 20)}..."`,
+            };
+        }
+        // Validate optional email if present
+        if (oauth.email !== undefined) {
+            if (typeof oauth.email !== "string") {
+                return {
+                    valid: false,
+                    reason: "OAuth email must be a string if provided",
+                };
+            }
+            const email = oauth.email.trim();
+            if (email.length > 0) {
+                // Basic email format validation
+                const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+                if (!emailPattern.test(email)) {
+                    return {
+                        valid: false,
+                        reason: `OAuth email format invalid: "${email}"`,
+                    };
+                }
+                if (email.length > 255) {
+                    return {
+                        valid: false,
+                        reason: "OAuth email must be 255 characters or less",
+                    };
+                }
+            }
+        }
+        // Validate optional name if present
+        if (oauth.name !== undefined) {
+            if (typeof oauth.name !== "string") {
+                return {
+                    valid: false,
+                    reason: "OAuth name must be a string if provided",
+                };
+            }
+            if (oauth.name.length > 255) {
+                return {
+                    valid: false,
+                    reason: "OAuth name must be 255 characters or less",
+                };
+            }
+        }
+        return { valid: true };
+    }
 }
 function buildRequestMeta(request) {
     const ip = request.headers.get("cf-connecting-ip") ??
@@ -582,25 +1140,39 @@ function buildRequestMeta(request) {
  *
  * Supports SSE (Server-Sent Events) and HTTP JSON-RPC transports for compatibility
  * with Claude Desktop, Cursor, MCP Inspector, and other MCP clients.
+ *
+ * Automatically handles prefixed KV bindings via `envPrefix` parameter or auto-detection.
  */
 export function createMCPICloudflareAdapter(config) {
-    // Create the runtime with Cloudflare providers
-    const runtime = createCloudflareRuntime(config);
+    // Normalize environment to handle prefixed KV bindings
+    // This ensures consistent KV access regardless of prefix usage
+    const mappedEnv = normalizeCloudflareEnv(config.env, config.envPrefix);
+    // Create the runtime with normalized environment
+    const runtime = createCloudflareRuntime({
+        ...config,
+        env: mappedEnv,
+    });
     // Server info
     const serverInfo = config.serverInfo || {
         name: "MCP-I Cloudflare Server",
         version: "1.0.0",
     };
     // Initialize proof archive if PROOF_ARCHIVE KV is available
-    const env = config.env;
-    const proofArchive = env.PROOF_ARCHIVE
-        ? new KVProofArchive(env.PROOF_ARCHIVE)
+    const proofArchive = mappedEnv.PROOF_ARCHIVE
+        ? new KVProofArchive(mappedEnv.PROOF_ARCHIVE)
         : undefined;
-    // Get delegation storage from env if available
-    const delegationStorage = env.DELEGATION_STORAGE;
+    // Get delegation storage from normalized env if available
+    const delegationStorage = mappedEnv.DELEGATION_STORAGE;
+    // Initialize AdminService (if API key is present)
+    // This enables cache clearing and other admin operations
+    let adminService;
+    if (mappedEnv.AGENTSHIELD_API_KEY) {
+        adminService = new AdminService(mappedEnv);
+    }
     // Create lightweight MCP server
     const server = new CloudflareMCPServer(runtime, serverInfo, config.tools || [], proofArchive, delegationStorage);
     // Return fetch handler
+    // Note: mappedEnv is captured in closure for admin endpoints
     return {
         server,
         runtime,
@@ -782,6 +1354,20 @@ export function createMCPICloudflareAdapter(config) {
             }
             // Admin endpoints for viewing nonces and proofs
             if (url.pathname.startsWith("/admin/")) {
+                // Handle clear-cache (POST) - Delegate to AdminService
+                if (url.pathname === "/admin/clear-cache" &&
+                    request.method === "POST") {
+                    if (adminService) {
+                        return adminService.handle(request);
+                    }
+                    return new Response(JSON.stringify({
+                        success: false,
+                        error: "Admin service not initialized (missing AGENTSHIELD_API_KEY)",
+                    }), {
+                        status: 403,
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
                 // Only allow in development or if explicitly configured
                 if (config.environment === "production") {
                     return new Response(JSON.stringify({
@@ -791,15 +1377,18 @@ export function createMCPICloudflareAdapter(config) {
                         headers: { "Content-Type": "application/json" },
                     });
                 }
-                const env = config.env;
+                // Use normalized environment (handles prefixed KV bindings)
+                // mappedEnv is already normalized in createMCPICloudflareAdapter
                 // GET /admin/nonces - List active nonces
                 if (url.pathname === "/admin/nonces") {
                     try {
                         // Use KV list to get nonce keys
-                        const noncesList = await env.NONCE_CACHE.list({ prefix: "nonce:" });
+                        const noncesList = await mappedEnv.NONCE_CACHE.list({
+                            prefix: "nonce:",
+                        });
                         const nonces = [];
                         for (const key of noncesList.keys) {
-                            const value = await env.NONCE_CACHE.get(key.name);
+                            const value = await mappedEnv.NONCE_CACHE.get(key.name);
                             if (value) {
                                 nonces.push({
                                     nonce: key.name.replace("nonce:", ""),
@@ -825,8 +1414,8 @@ export function createMCPICloudflareAdapter(config) {
                     }
                 }
                 // Initialize proof archive if available
-                const proofArchive = env.PROOF_ARCHIVE
-                    ? new KVProofArchive(env.PROOF_ARCHIVE)
+                const proofArchive = mappedEnv.PROOF_ARCHIVE
+                    ? new KVProofArchive(mappedEnv.PROOF_ARCHIVE)
                     : null;
                 if (!proofArchive) {
                     return new Response(JSON.stringify({
@@ -899,7 +1488,7 @@ export function createMCPICloudflareAdapter(config) {
                 if (url.pathname === "/admin/stats") {
                     try {
                         const [noncesList, proofStats] = await Promise.all([
-                            env.NONCE_CACHE.list({ prefix: "nonce:" }),
+                            mappedEnv.NONCE_CACHE.list({ prefix: "nonce:" }),
                             proofArchive.getStats(),
                         ]);
                         return new Response(JSON.stringify({