@kya-os/mcp-i-cloudflare 1.5.8-canary.7 → 1.5.8-canary.71

package/dist/agent.js

@@ -10,8 +10,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CloudflareRuntime } from "./runtime";
 import { createCloudflareRuntime } from "./index";
 import { mapPrefixedEnv } from "./helpers/env-mapper";
-// Global registry for agent options (set by createMCPIApp)
-const agentOptionsRegistry = new Map();
+import { STORAGE_KEYS } from "./constants/storage-keys";
+import { z } from "zod";
+import { OAuthConfigService, OAuthService, IdpTokenResolver, ToolContextBuilder, DelegationRequiredError, } from "@kya-os/mcp-i-core";
+import { KVOAuthConfigCache } from "./cache/kv-oauth-config-cache";
+import { IdpTokenStorage } from "./services/idp-token-storage";
+import { OAuthSecurityService } from "./services/oauth-security.service";
 /**
  * Base class for MCP agents with MCP-I features
  *
@@ -21,45 +25,45 @@ const agentOptionsRegistry = new Map();
  * - Session management
  * - Durable Object routing
  *
- * Users extend this class and implement `registerTools()` to add their custom tools.
+ * Users extend this class and implement:
+ * - `getAgentName()`: Return the agent name
+ * - `getAgentVersion()`: Return the agent version (optional)
+ * - `getEnvPrefix()`: Return the KV environment prefix (optional)
+ * - `getRuntimeConfig()`: Return the runtime configuration
+ * - `registerTools()`: Register tools with the MCP server
  */
 export class MCPICloudflareAgent extends McpAgent {
-    // @ts-ignore - Type incompatibility between different versions of @modelcontextprotocol/sdk
-    // Runtime behavior is correct, this is a type-only issue
     // Initialize server as class field (before constructor) so parent class can access it
+    // Note: SDK 1.x uses single parameter constructor (server info only)
     server = new McpServer({
         name: "MCP-I Agent",
         version: "1.0.0",
     });
     mcpiRuntime;
     env;
-    options;
     constructor(state, env) {
         // Call super() with just state and env (agents@0.2.21+ only accepts 2 parameters)
         // The config is no longer passed to the constructor - it's set via the server property
         super(state, env);
-        // Get options from registry AFTER calling super() (can now access 'this')
-        const AgentClass = new.target;
-        const options = agentOptionsRegistry.get(AgentClass);
-        // Now we can safely access 'this' and set properties
-        if (!options) {
-            throw new Error(`Agent options not found. Make sure to call createMCPIApp() before instantiating ${AgentClass.name}.`);
-        }
         this.env = env;
-        this.options = options;
-        // Update server with correct config from options (override the default)
+        // Get agent configuration from subclass methods
+        const agentName = this.getAgentName();
+        const agentVersion = this.getAgentVersion();
+        const envPrefix = this.getEnvPrefix();
+        // Update server with correct config
+        // Note: SDK 1.x uses single parameter constructor (server info only)
         this.server = new McpServer({
-            name: this.options.name,
-            version: this.options.version || "1.0.0",
+            name: agentName,
+            version: agentVersion || "1.0.0",
         });
         // Map prefixed environment to standard CloudflareEnv
-        const mappedEnv = this.options.envPrefix
-            ? mapPrefixedEnv(env, this.options.envPrefix)
+        const mappedEnv = envPrefix
+            ? mapPrefixedEnv(env, envPrefix)
             : env;
-        // Add DurableObjectState to mapped env
+        // Add DurableObjectState to mapped env for identity persistence
         mappedEnv._durableObjectState = state;
-        // Load runtime configuration
-        const runtimeConfig = this.options.getRuntimeConfig(mappedEnv);
+        // Load runtime configuration from subclass
+        const runtimeConfig = this.getRuntimeConfigInternal(mappedEnv);
         // Create tool protection service if configured
         const toolProtectionService = runtimeConfig.toolProtection &&
             mappedEnv.TOOL_PROTECTION_KV &&
@@ -73,10 +77,13 @@ export class MCPICloudflareAgent extends McpAgent {
                     mappedEnv.AGENTSHIELD_PROJECT_ID,
                 cacheTtl: runtimeConfig.toolProtection.agentShield?.cacheTtl || 300000,
                 debug: runtimeConfig.environment === "development",
+                // Wrap fallback ToolProtectionMap into ToolProtectionConfig format
+                // Handle both wrapped and unwrapped formats for backward compatibility
                 fallbackConfig: runtimeConfig.toolProtection.fallback
-                    ? {
-                        toolProtections: runtimeConfig.toolProtection.fallback,
-                    }
+                    ? runtimeConfig.toolProtection.fallback.toolProtections !==
+                        undefined
+                        ? runtimeConfig.toolProtection.fallback // Already wrapped
+                        : { toolProtections: runtimeConfig.toolProtection.fallback } // Wrap it
                     : undefined,
             })
             : undefined;
@@ -94,40 +101,185 @@ export class MCPICloudflareAgent extends McpAgent {
         });
     }
     /**
-     * Register options for an agent class
-     * Called internally by createMCPIApp
+     * Get agent version
+     * Subclasses can override this to provide a custom version
+     */
+    getAgentVersion() {
+        return "1.0.0";
+    }
+    /**
+     * Get environment prefix for KV bindings
+     * Subclasses can override this for multi-agent deployments
      */
-    static registerOptions(AgentClass, options) {
-        agentOptionsRegistry.set(AgentClass, options);
+    getEnvPrefix() {
+        return undefined;
     }
     /**
      * Initialize the agent
      * Call this after construction to set up the runtime and register tools
      */
     async init() {
-        await this.mcpiRuntime?.initialize();
-        const identity = await this.mcpiRuntime?.getIdentity();
-        console.log("[MCP-I] Initialized with DID:", identity?.did);
-        // Register tools (implemented by subclasses)
-        await this.registerTools();
+        try {
+            await this.mcpiRuntime?.initialize();
+            const identity = await this.mcpiRuntime?.getIdentity();
+            console.log("[MCP-I] Initialized with DID:", identity?.did);
+            // Ensure server is initialized before registering tools
+            if (!this.server) {
+                throw new Error("Server not initialized. This should not happen - server is initialized in constructor.");
+            }
+            // Register tools (implemented by subclasses)
+            await this.registerTools();
+        }
+        catch (error) {
+            console.error("[MCPICloudflareAgent] Initialization failed:", error);
+            throw error;
+        }
+    }
+    /**
+     * Register a tool with automatic session ID extraction and proof generation
+     *
+     * This helper method automatically extracts `sessionId` from `ToolExtraArguments`
+     * and passes it to `executeToolWithProof`, eliminating the need for manual extraction
+     * in every tool handler.
+     *
+     * @example
+     * ```typescript
+     * // For JSON Schema format (from template):
+     * this.registerToolWithProof(
+     *   greetTool.name,
+     *   greetTool.description,
+     *   greetTool.inputSchema, // Full JSON Schema object
+     *   greetTool.handler
+     * );
+     *
+     * // For Zod schema format (from examples):
+     * this.registerToolWithProof(
+     *   greetTool.name,
+     *   greetTool.description,
+     *   greetTool.inputSchema.shape, // Zod schema shape
+     *   greetTool.handler
+     * );
+     * ```
+     *
+     * @param name - Tool name
+     * @param description - Tool description
+     * @param schema - Tool input schema (JSON Schema object OR Zod schema shape)
+     * @param handler - Tool handler function that receives args and returns result
+     */
+    registerToolWithProof(name, description, schema, // Accept JSON Schema object or Zod schema shape
+    handler) {
+        // Safety check: ensure server is initialized
+        if (!this.server) {
+            throw new Error(`Cannot register tool "${name}": server not initialized. Make sure to call init() before registering tools.`);
+        }
+        try {
+            // Normalize schema format for MCP SDK
+            // MCP SDK expects Zod schema shape (Record<string, ZodType>), not JSON Schema
+            // Convert JSON Schema to Zod schema shape if needed
+            let zodSchemaShape = {};
+            if (schema && typeof schema === "object") {
+                // Check if it's already a Zod schema shape (has ZodType instances)
+                if (schema.type === "object" && schema.properties) {
+                    // It's a JSON Schema object - convert to Zod schema shape
+                    const jsonSchema = schema;
+                    const requiredFields = new Set(jsonSchema.required || []);
+                    zodSchemaShape = Object.fromEntries(Object.entries(jsonSchema.properties).map(([key, prop]) => {
+                        // Convert JSON Schema property to Zod type
+                        let zodType;
+                        if (prop.type === "string") {
+                            zodType = z.string();
+                            if (prop.description) {
+                                zodType = zodType.describe(prop.description);
+                            }
+                        }
+                        else if (prop.type === "number") {
+                            zodType = z.number();
+                            if (prop.description) {
+                                zodType = zodType.describe(prop.description);
+                            }
+                        }
+                        else if (prop.type === "boolean") {
+                            zodType = z.boolean();
+                            if (prop.description) {
+                                zodType = zodType.describe(prop.description);
+                            }
+                        }
+                        else if (prop.type === "array") {
+                            zodType = z.array(z.any());
+                            if (prop.description) {
+                                zodType = zodType.describe(prop.description);
+                            }
+                        }
+                        else {
+                            // Fallback to any for unknown types
+                            zodType = z.any();
+                            if (prop.description) {
+                                zodType = zodType.describe(prop.description);
+                            }
+                        }
+                        // Make optional if not in required array
+                        if (!requiredFields.has(key)) {
+                            zodType = zodType.optional();
+                        }
+                        return [key, zodType];
+                    }));
+                }
+                else {
+                    // Assume it's already a Zod schema shape or compatible object
+                    zodSchemaShape = schema;
+                }
+            }
+            this.server.tool(name, description, zodSchemaShape, async (args, extra) => {
+                // ✅ Automatically extract sessionId from ToolExtraArguments
+                // This ensures delegation tokens stored with the original session ID
+                // can be retrieved on subsequent tool calls
+                // Note: extra is typed as 'any' to match MCP SDK's ToolExtraArguments type
+                const sessionId = extra?.sessionId;
+                return this.executeToolWithProof(name, args, handler, sessionId);
+            });
+        }
+        catch (error) {
+            console.error(`[MCPICloudflareAgent] Failed to register tool "${name}":`, error);
+            throw error;
+        }
     }
     /**
      * Execute a tool with automatic proof generation
      * Use this helper method when registering tools to ensure proofs are generated
+     *
+     * @param toolName - Name of the tool being executed
+     * @param args - Tool arguments
+     * @param handler - Tool handler function
+     * @param providedSessionId - Optional session ID from MCP request (extracted from ToolExtraArguments.sessionId)
+     *                            If provided, uses this session ID for delegation token lookup.
+     *                            If not provided, falls back to getSessionId() or generates ephemeral ID.
      */
-    async executeToolWithProof(toolName, args, handler) {
+    async executeToolWithProof(toolName, args, handler, providedSessionId) {
         if (!this.mcpiRuntime) {
             throw new Error("MCP-I runtime not initialized. Call init() first.");
         }
         // Create session
+        // ✅ CRITICAL: Use provided sessionId if available (from MCP request params)
+        // This ensures delegation tokens stored with the original session ID can be retrieved
         const timestamp = Date.now();
-        const sessionId = this.getSessionId() ||
+        const sessionId = providedSessionId ||
+            this.getSessionId() ||
             `ephemeral-${timestamp}-${Math.random().toString(36).substring(2, 10)}`;
+        // Log session ID source for debugging
+        const envPrefix = this.getEnvPrefix();
+        const mappedEnv = envPrefix
+            ? mapPrefixedEnv(this.env, envPrefix)
+            : this.env;
+        if (this.getRuntimeConfigInternal(mappedEnv).environment === "development") {
+            console.log("[MCPICloudflareAgent] Session ID source:", {
+                provided: !!providedSessionId,
+                fromGetSessionId: !!this.getSessionId(),
+                isEphemeral: !providedSessionId && !this.getSessionId(),
+                sessionId: sessionId.slice(0, 20) + "...",
+            });
+        }
         // Get server URL from env var (MCP_SERVER_URL) for consent URL building
         // In production, this should be set to the deployed worker URL
-        const mappedEnv = this.options?.envPrefix
-            ? mapPrefixedEnv(this.env, this.options.envPrefix)
-            : this.env;
         let serverUrl = mappedEnv.MCP_SERVER_URL;
         // Ensure URL has protocol (https://) if provided
         if (serverUrl &&
@@ -136,6 +288,92 @@ export class MCPICloudflareAgent extends McpAgent {
             // Auto-add https:// if protocol missing
             serverUrl = `https://${serverUrl}`;
         }
+        // ✅ Look up delegation token from KV storage (3-priority system)
+        let delegationToken;
+        let userDid; // Extract userDid for IDP token resolution
+        const delegationStorage = mappedEnv.DELEGATION_STORAGE;
+        if (delegationStorage) {
+            try {
+                const agentDid = (await this.mcpiRuntime.getIdentity()).did;
+                console.log("[MCPICloudflareAgent] 🔍 Starting delegation token lookup:", {
+                    sessionId: sessionId.slice(0, 20) + "...",
+                    agentDid: agentDid.slice(0, 20) + "...",
+                    hasDelegationStorage: !!delegationStorage,
+                });
+                // PRIORITY 1: User+Agent scoped token (user-specific, most secure)
+                // Try to get userDid from session cache
+                const sessionKey = STORAGE_KEYS.session(sessionId);
+                const sessionData = (await delegationStorage.get(sessionKey, "json"));
+                userDid = sessionData?.userDid;
+                if (userDid) {
+                    const userAgentKey = STORAGE_KEYS.delegation(userDid, agentDid);
+                    console.log("[MCPICloudflareAgent] 🔍 PRIORITY 1: Checking user+agent scoped key:", {
+                        key: userAgentKey,
+                        userDid: userDid.slice(0, 20) + "...",
+                        agentDid: agentDid.slice(0, 20) + "...",
+                    });
+                    const userAgentToken = await delegationStorage.get(userAgentKey, "text");
+                    console.log("[MCPICloudflareAgent] 🔍 PRIORITY 1: User+agent scoped lookup result:", {
+                        found: !!userAgentToken,
+                        tokenLength: userAgentToken?.length || 0,
+                    });
+                    if (userAgentToken) {
+                        delegationToken = userAgentToken;
+                    }
+                }
+                // PRIORITY 2: Session-scoped token (if session ID persists)
+                if (!delegationToken) {
+                    console.log("[MCPICloudflareAgent] 🔍 PRIORITY 2: Checking session-scoped key:", {
+                        key: sessionKey,
+                        sessionId: sessionId.slice(0, 20) + "...",
+                    });
+                    const sessionTokenData = (await delegationStorage.get(sessionKey, "json"));
+                    console.log("[MCPICloudflareAgent] 🔍 PRIORITY 2: Session-scoped lookup result:", {
+                        found: !!sessionTokenData,
+                        hasDelegationToken: !!sessionTokenData?.delegationToken,
+                        tokenLength: sessionTokenData?.delegationToken?.length || 0,
+                    });
+                    if (sessionTokenData?.delegationToken) {
+                        delegationToken = sessionTokenData.delegationToken;
+                    }
+                }
+                // PRIORITY 3: 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("[MCPICloudflareAgent] ⚠️ 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("[MCPICloudflareAgent] 🔍 PRIORITY 3: Checking agent-scoped key (legacy):", {
+                        key: agentKey,
+                        agentDid: agentDid.slice(0, 20) + "...",
+                    });
+                    delegationToken = await delegationStorage.get(agentKey, "text");
+                    console.log("[MCPICloudflareAgent] 🔍 PRIORITY 3: Agent-scoped lookup result:", {
+                        found: !!delegationToken,
+                        tokenLength: delegationToken?.length || 0,
+                    });
+                }
+                if (delegationToken) {
+                    console.log("[MCPICloudflareAgent] ✅ Delegation token retrieved:", {
+                        sessionId: sessionId.slice(0, 20) + "...",
+                        tokenLength: delegationToken.length,
+                        source: "kv-storage",
+                    });
+                }
+                else {
+                    console.log("[MCPICloudflareAgent] ⚠️ No delegation token found in KV storage:", {
+                        sessionId: sessionId.slice(0, 20) + "...",
+                        agentDid: agentDid.slice(0, 20) + "...",
+                    });
+                }
+            }
+            catch (error) {
+                console.warn("[MCPICloudflareAgent] Failed to retrieve delegation token:", error);
+            }
+        }
         const session = {
             id: sessionId,
             audience: "https://kya.vouched.id",
@@ -143,11 +381,254 @@ export class MCPICloudflareAgent extends McpAgent {
             createdAt: timestamp,
             expiresAt: timestamp + 30 * 60 * 1000, // 30 minutes
             serverOrigin: serverUrl, // Use MCP_SERVER_URL for consent URL building
+            delegationToken, // ✅ Include token in session if found
+        };
+        // ✅ NEW: Build tool execution context with IDP token (Phase 1 - MH-7)
+        let toolContext;
+        try {
+            toolContext = await this.buildToolContext(toolName, userDid, sessionId, delegationToken, mappedEnv);
+        }
+        catch (error) {
+            // Handle OAuthRequiredError - build OAuth URL and throw DelegationRequiredError
+            // Use property checks instead of instanceof for Cloudflare Workers compatibility
+            if (error instanceof Error &&
+                (error.name === "OAuthRequiredError" ||
+                    error.constructor?.name === "OAuthRequiredError" ||
+                    ("oauthUrl" in error &&
+                        "provider" in error &&
+                        "requiredScopes" in error))) {
+                try {
+                    // Type assertion for OAuthRequiredError properties
+                    const oauthError = error;
+                    const oauthUrl = await this.buildOAuthUrlForError(oauthError, sessionId, mappedEnv);
+                    // Generate resume token using runtime's internal method
+                    // The runtime will generate it when DelegationRequiredError is thrown
+                    const resumeToken = `resume_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+                    // Throw DelegationRequiredError with OAuth URL
+                    throw new DelegationRequiredError(oauthError.toolName, oauthError.requiredScopes, oauthUrl, // Use OAuth URL as consent URL
+                    undefined, // interceptedCall
+                    resumeToken);
+                }
+                catch (oauthError) {
+                    // If OAuth URL building fails, re-throw the original error
+                    throw oauthError instanceof DelegationRequiredError
+                        ? oauthError
+                        : error;
+                }
+            }
+            // Log other errors but don't fail tool execution (backward compatibility)
+            console.warn("[MCPICloudflareAgent] Failed to build tool context:", error);
+        }
+        // Wrap handler to pass context as optional second parameter
+        // For backward compatibility, handlers can accept (args) or (args, context)
+        // If handler doesn't accept context, it will be ignored
+        const handlerWithContext = async (handlerArgs) => {
+            // Try to call handler with context if available
+            // TypeScript function types don't preserve length, so we try both signatures
+            try {
+                // Try calling with context (for handlers that accept it)
+                if (toolContext) {
+                    return handler(handlerArgs, toolContext);
+                }
+                else {
+                    return handler(handlerArgs);
+                }
+            }
+            catch (error) {
+                // If handler doesn't accept context parameter, fall back to args-only call
+                // This maintains backward compatibility
+                return handler(handlerArgs);
+            }
         };
         // Execute tool with automatic proof generation
-        const result = await this.mcpiRuntime.processToolCall(toolName, args, handler, session);
+        const result = await this.mcpiRuntime.processToolCall(toolName, args, handlerWithContext, session);
         return result;
     }
+    /**
+     * Build tool execution context with IDP token (Phase 1 - MH-7)
+     *
+     * @private
+     */
+    async buildToolContext(toolName, userDid, sessionId, delegationToken, env) {
+        // Only build context if userDid is available and services are configured
+        if (!userDid || !env.AGENTSHIELD_API_KEY || !env.DELEGATION_STORAGE) {
+            return undefined;
+        }
+        // Check if tool protection service is available
+        const toolProtectionService = this.mcpiRuntime.config
+            ?.toolProtectionService;
+        if (!toolProtectionService) {
+            return undefined;
+        }
+        try {
+            // Get tool protection configuration
+            const agentDid = (await this.mcpiRuntime.getIdentity()).did;
+            const protection = await toolProtectionService.checkToolProtection(toolName, agentDid);
+            // Only build context if tool requires OAuth
+            if (!protection?.requiredScopes?.length) {
+                return undefined;
+            }
+            // Get project ID from tool protection service
+            const projectId = toolProtectionService.getProjectId();
+            if (!projectId) {
+                return undefined;
+            }
+            // Initialize OAuth services lazily
+            const fetchProvider = this.mcpiRuntime.fetch;
+            if (!fetchProvider) {
+                return undefined;
+            }
+            // Use KV cache for OAuth config if available, otherwise in-memory
+            const oauthConfigCache = env.TOOL_PROTECTION_KV
+                ? new KVOAuthConfigCache({ kv: env.TOOL_PROTECTION_KV })
+                : undefined;
+            const oauthConfigService = new OAuthConfigService({
+                baseUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+                apiKey: env.AGENTSHIELD_API_KEY,
+                fetchProvider,
+                cache: oauthConfigCache,
+            });
+            // Phase 2: Initialize provider registry and resolver
+            const { OAuthProviderRegistry, ProviderResolver } = await import("@kya-os/mcp-i-core");
+            const providerRegistry = new OAuthProviderRegistry(oauthConfigService);
+            const providerResolver = new ProviderResolver(providerRegistry, oauthConfigService);
+            const oauthService = new OAuthService({
+                configService: oauthConfigService,
+                fetchProvider,
+                agentShieldApiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+                agentShieldApiKey: env.AGENTSHIELD_API_KEY,
+                projectId,
+            });
+            const oauthSecurityService = new OAuthSecurityService(env.DELEGATION_STORAGE, env.OAUTH_ENCRYPTION_SECRET);
+            // Only create IdpTokenStorage if DELEGATION_STORAGE is available
+            if (!env.DELEGATION_STORAGE) {
+                console.warn("[MCPICloudflareAgent] DELEGATION_STORAGE not configured, skipping IDP token storage");
+                return undefined;
+            }
+            const idpTokenStorage = new IdpTokenStorage({
+                storage: env.DELEGATION_STORAGE,
+                oauthSecurityService,
+            });
+            const tokenResolver = new IdpTokenResolver({
+                tokenStorage: idpTokenStorage,
+                oauthService,
+            });
+            const contextBuilder = new ToolContextBuilder({
+                tokenResolver,
+                configService: oauthConfigService,
+                providerResolver: providerResolver, // Phase 2: Pass ProviderResolver (type assertion for dist/src compatibility)
+                projectId,
+            });
+            // Build context
+            return await contextBuilder.buildContext(toolName, userDid, sessionId, delegationToken, protection);
+        }
+        catch (error) {
+            // Re-throw OAuthRequiredError so it can be handled by executeToolWithProof
+            // Use property checks instead of instanceof for Cloudflare Workers compatibility
+            if (error instanceof Error &&
+                (error.name === "OAuthRequiredError" ||
+                    error.constructor?.name === "OAuthRequiredError" ||
+                    ("oauthUrl" in error &&
+                        "provider" in error &&
+                        "requiredScopes" in error))) {
+                throw error;
+            }
+            console.warn("[MCPICloudflareAgent] Failed to build tool context:", error);
+            return undefined;
+        }
+    }
+    /**
+     * Build OAuth URL for OAuthRequiredError
+     *
+     * Creates OAuth authorization URL with PKCE challenge for secure token exchange.
+     *
+     * @private
+     */
+    async buildOAuthUrlForError(error, sessionId, env) {
+        const agentShieldUrl = env.AGENTSHIELD_API_URL || "https://kya.vouched.id";
+        const toolProtectionService = this.mcpiRuntime.config
+            ?.toolProtectionService;
+        const projectId = toolProtectionService?.getProjectId();
+        if (!projectId) {
+            throw new Error("Project ID not available for OAuth URL building");
+        }
+        // Get server URL
+        let serverUrl = env.MCP_SERVER_URL;
+        if (serverUrl &&
+            !serverUrl.startsWith("http://") &&
+            !serverUrl.startsWith("https://")) {
+            serverUrl = `https://${serverUrl}`;
+        }
+        if (!serverUrl) {
+            throw new Error("MCP_SERVER_URL not configured for OAuth callback");
+        }
+        // TypeScript: projectId is guaranteed to be defined after the check above
+        // Use non-null assertion since we've already validated it
+        const safeProjectId = projectId;
+        const agentDid = (await this.mcpiRuntime.getIdentity()).did;
+        // Generate PKCE challenge if OAuthSecurityService is available
+        let codeChallenge;
+        let stateParam;
+        if (env.DELEGATION_STORAGE && env.OAUTH_ENCRYPTION_SECRET) {
+            try {
+                const oauthSecurityService = new OAuthSecurityService(env.DELEGATION_STORAGE, env.OAUTH_ENCRYPTION_SECRET);
+                const pkceChallenge = await oauthSecurityService.generatePKCEChallenge();
+                codeChallenge = pkceChallenge.challenge;
+                // Build state data
+                const stateData = {
+                    project_id: safeProjectId,
+                    agent_did: agentDid,
+                    session_id: sessionId || "",
+                    scopes: error.requiredScopes,
+                    storedAt: Date.now(),
+                    code_verifier: pkceChallenge.verifier,
+                    code_challenge: pkceChallenge.challenge,
+                    redirect_uri: `${serverUrl}/oauth/callback`,
+                };
+                // Store state securely
+                const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+                const stateValue = btoa(String.fromCharCode(...randomBytes))
+                    .replace(/\+/g, "-")
+                    .replace(/\//g, "_")
+                    .replace(/=/g, "");
+                await oauthSecurityService.storeOAuthState(stateValue, stateData, 600);
+                stateParam = stateValue;
+            }
+            catch (err) {
+                console.warn("[MCPICloudflareAgent] Failed to generate PKCE challenge, using insecure state:", err);
+                // Fallback to insecure state encoding
+                const stateData = {
+                    project_id: safeProjectId,
+                    agent_did: agentDid,
+                    session_id: sessionId || "",
+                    scopes: error.requiredScopes,
+                };
+                stateParam = btoa(JSON.stringify(stateData));
+            }
+        }
+        else {
+            // Fallback to insecure state encoding
+            const stateData = {
+                project_id: safeProjectId,
+                agent_did: agentDid,
+                session_id: sessionId || "",
+                scopes: error.requiredScopes,
+            };
+            stateParam = btoa(JSON.stringify(stateData));
+        }
+        // Build OAuth authorization URL
+        const oauthUrl = new URL(`${agentShieldUrl}/bouncer/oauth/authorize`);
+        oauthUrl.searchParams.set("response_type", "code");
+        oauthUrl.searchParams.set("client_id", safeProjectId);
+        oauthUrl.searchParams.set("redirect_uri", `${serverUrl}/oauth/callback`);
+        oauthUrl.searchParams.set("scope", error.requiredScopes.join(" "));
+        oauthUrl.searchParams.set("state", stateParam);
+        if (codeChallenge) {
+            oauthUrl.searchParams.set("code_challenge", codeChallenge);
+            oauthUrl.searchParams.set("code_challenge_method", "S256");
+        }
+        return oauthUrl.toString();
+    }
     /**
      * Get Durable Object instance ID based on routing strategy
      */