@kya-os/mcp-i-cloudflare 1.14.7 → 1.15.0

package/dist/agent.js

@@ -14,6 +14,7 @@ import { createCloudflareRuntime } from "./index";
 import { mapPrefixedEnv } from "./helpers/env-mapper";
 import { makeEnvSecretResolver } from "./utils/env-secret-resolver.js";
 import { handlePickupInternal } from "./delegation-http/anchor-do";
+import { NATIVE_OAUTH_INTERNAL_PREFIX } from "./delegation-http/native-oauth-state-do";
 import { augmentKyaOsIdentityWellKnown } from "./delegation-http/well-known-capability";
 import { resolveCloudflareAuditAssurance } from "./audit/assurance";
 import { createCloudflareAuditRuntimeFromEnv } from "./audit/deployment-binding";
@@ -41,7 +42,8 @@ import { calculateDOInstanceId, parseDORoutingStrategy, parseDOShardCount, } fro
 import { defaultProviderRegistry, } from "@kya-os/provider-registry";
 import { hasApiKeyAuthorization, AuthRequiredError, } from "@kya-os/contracts/tool-protection";
 import { VaultResolver } from "./services/vault-resolver";
-import { invokeToolHandlerOnce } from "./runtime/invoke-tool-handler";
+import { invokeToolHandlerOnce, withVerifiedDelegation, } from "./runtime/invoke-tool-handler";
+import { withCheckpointNames } from "@kya-os/contracts/config";
 // CRITICAL: Force OAuth registry evaluation at module load time
 // This creates an observable side effect that esbuild cannot tree-shake
 // Without this, esbuild may eliminate oauth-service-registry.ts entirely
@@ -77,6 +79,7 @@ export class MCPICloudflareAgent extends McpAgent {
     mcpiRuntime;
     env;
     providerRegistry;
+    _runtimeConfig;
     _environment = "production";
     _autoDetectedOrigin; // Auto-detected server origin from request URL
     _clientMessagesConfig; // Client-specific delegation messages
@@ -86,8 +89,9 @@ export class MCPICloudflareAgent extends McpAgent {
     constructor(state, env, providerRegistry = defaultProviderRegistry) {
         // 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);
-        this.env = env;
+        const current = withCheckpointNames(env);
+        super(state, current);
+        this.env = current;
         this.providerRegistry = providerRegistry;
         // Get agent configuration from subclass methods
         const agentName = this.getAgentName();
@@ -99,10 +103,15 @@ export class MCPICloudflareAgent extends McpAgent {
             name: agentName,
             version: agentVersion || "1.0.0",
         });
-        // Map prefixed environment to standard CloudflareEnv
+        // Map prefixed environment to standard CloudflareEnv. Unprefixed, this is
+        // a shallow copy: workerd hands the SAME env object to this Durable
+        // Object and to the worker's stateless fetch handler, so tagging it
+        // directly would leak this DO's state into the app-level runtime, whose
+        // identity provider would then write to it from another request
+        // ("Cannot perform I/O on behalf of a different request").
         const mappedEnv = envPrefix
-            ? mapPrefixedEnv(env, envPrefix)
-            : env;
+            ? mapPrefixedEnv(current, envPrefix)
+            : { ...current };
         // Add DurableObjectState to mapped env for identity persistence
         mappedEnv._durableObjectState = state;
         // Load runtime configuration from subclass
@@ -125,18 +134,24 @@ export class MCPICloudflareAgent extends McpAgent {
         }
         // Store environment for logging checks
         this._environment = runtimeConfig.environment || "production";
+        // Discovery must use the same effective audit trail as the initialized
+        // runtime, including managed bindings absent from the template defaults.
+        this._runtimeConfig = runtimeConfig;
         // Create tool protection service if configured
         const toolProtectionService = runtimeConfig.toolProtection &&
             mappedEnv.TOOL_PROTECTION_KV &&
-            mappedEnv.AGENTSHIELD_API_KEY
+            mappedEnv.CHECKPOINT_API_KEY
             ? CloudflareRuntime.createToolProtectionService(mappedEnv.TOOL_PROTECTION_KV, {
-                apiUrl: runtimeConfig.toolProtection.agentShield?.apiUrl ||
-                    mappedEnv.AGENTSHIELD_API_URL ||
+                apiUrl: (runtimeConfig.toolProtection.checkpoint ??
+                    runtimeConfig.toolProtection.agentShield)?.apiUrl ||
+                    mappedEnv.CHECKPOINT_API_URL ||
                     "https://kya.vouched.id",
-                apiKey: mappedEnv.AGENTSHIELD_API_KEY,
-                projectId: runtimeConfig.toolProtection.agentShield?.projectId ||
-                    mappedEnv.AGENTSHIELD_PROJECT_ID,
-                cacheTtl: runtimeConfig.toolProtection.agentShield?.cacheTtl || 300000,
+                apiKey: mappedEnv.CHECKPOINT_API_KEY,
+                projectId: (runtimeConfig.toolProtection.checkpoint ??
+                    runtimeConfig.toolProtection.agentShield)?.projectId ||
+                    mappedEnv.CHECKPOINT_PROJECT_ID,
+                cacheTtl: (runtimeConfig.toolProtection.checkpoint ??
+                    runtimeConfig.toolProtection.agentShield)?.cacheTtl || 300000,
                 debug: runtimeConfig.environment === "development",
                 // Wrap localConfig ToolProtectionMap into ToolProtectionConfig format
                 // The ToolProtectionSourceConfig.localConfig is a BaseToolProtectionMap (Record<string, ToolProtection>)
@@ -226,8 +241,8 @@ export class MCPICloudflareAgent extends McpAgent {
             const clientIdentity = await resolveClientIdentity(clientInfo, ktaApiUrl);
             // Store client identity for use in sessions/proofs
             await this.ctx.storage.put("clientIdentity", clientIdentity);
-            // Register session with AgentShield (fire-and-forget) - always in production too
-            await this.registerSessionWithAgentShield(clientInfo, clientIdentity, protocolVersion);
+            // Register session with Checkpoint (fire-and-forget) - always in production too
+            await this.registerSessionWithCheckpoint(clientInfo, clientIdentity, protocolVersion);
             // Skip balloon logging in production (only skip the visual output)
             if (this._environment !== "development")
                 return;
@@ -395,10 +410,10 @@ export class MCPICloudflareAgent extends McpAgent {
         }
     }
     /**
-     * Register session with AgentShield for dashboard visibility
+     * Register session with Checkpoint for dashboard visibility
      * This is a fire-and-forget operation - failures are logged but don't block
      */
-    async registerSessionWithAgentShield(clientInfo, clientIdentity, protocolVersion) {
+    async registerSessionWithCheckpoint(clientInfo, clientIdentity, protocolVersion) {
         try {
             const envPrefix = this.getEnvPrefix();
             const mappedEnv = envPrefix
@@ -422,9 +437,9 @@ export class MCPICloudflareAgent extends McpAgent {
             // ✅ CRITICAL: Initialize session storage with ephemeral identity FIRST
             // This ensures every session has a userDid before any delegation operations
             await this.initializeSessionStorage(sessionId);
-            // Check if we have the required config for AgentShield registration
-            if (!mappedEnv.AGENTSHIELD_API_KEY || !mappedEnv.AGENTSHIELD_PROJECT_ID) {
-                // Skip AgentShield registration - but session storage was still initialized above
+            // Check if we have the required config for Checkpoint registration
+            if (!mappedEnv.CHECKPOINT_API_KEY || !mappedEnv.CHECKPOINT_PROJECT_ID) {
+                // Skip Checkpoint registration - but session storage was still initialized above
                 return;
             }
             // Get agent DID
@@ -441,21 +456,21 @@ export class MCPICloudflareAgent extends McpAgent {
                 fetch: (url, options) => fetch(url, options),
             };
             const service = new SessionRegistrationService({
-                baseUrl: mappedEnv.AGENTSHIELD_API_URL || "https://kya.vouched.id",
-                apiKey: mappedEnv.AGENTSHIELD_API_KEY,
+                baseUrl: mappedEnv.CHECKPOINT_API_URL || "https://kya.vouched.id",
+                apiKey: mappedEnv.CHECKPOINT_API_KEY,
                 fetchProvider,
                 logger: this._environment === "development"
                     ? (msg, data) => logger.debug(msg, data)
                     : undefined,
             });
             // Register session (fire-and-forget)
-            // Include agent_name for AgentShield dashboard display
+            // Include agent_name for Checkpoint dashboard display
             const agentName = this.getAgentName() || mappedEnv.MCP_SERVER_NAME || undefined;
             service.registerSessionAsync({
                 session_id: sessionId,
                 agent_did: identity.did,
                 agent_name: agentName, // Human-readable name for dashboard
-                project_id: mappedEnv.AGENTSHIELD_PROJECT_ID,
+                project_id: mappedEnv.CHECKPOINT_PROJECT_ID,
                 created_at: Date.now(),
                 client_info: {
                     name: clientInfo?.name || "Unidentified",
@@ -532,6 +547,23 @@ export class MCPICloudflareAgent extends McpAgent {
     setClientMessagesConfig(config) {
         this._clientMessagesConfig = config;
     }
+    /**
+     * The delegation verifier the runtime uses for protected tool calls.
+     *
+     * Subclasses can ask the same verifier a question the runtime would ask,
+     * with the same credentials and base URL, instead of building their own
+     * client. Undefined when no CHECKPOINT_API_KEY is configured (the runtime
+     * then has no remote verifier either).
+     *
+     * @example
+     * ```typescript
+     * const verifier = this.getDelegationVerifier();
+     * const result = await verifier?.verifyDelegation({ agent_did, scopes, delegation_token });
+     * ```
+     */
+    getDelegationVerifier() {
+        return this.mcpiRuntime?.getAccessControlService();
+    }
     /**
      * Whether to attach a popup-launch hint when this client supports it.
      * Subclasses may override; defaults to `true` so popup-aware clients
@@ -1403,7 +1435,7 @@ export class MCPICloudflareAgent extends McpAgent {
                     ? "MCP_SERVER_URL env var"
                     : this._autoDetectedOrigin
                         ? "auto-detected from request"
-                        : "none (will use AgentShield fallback)",
+                        : "none (will use Checkpoint fallback)",
                 serverUrl: serverUrl?.slice(0, 50) || "undefined",
             });
         }
@@ -1537,11 +1569,11 @@ export class MCPICloudflareAgent extends McpAgent {
             agentDid: getMcpRequestHolder()?.did ?? (await this.mcpiRuntime.getIdentity()).did,
             // Trusted per-request proof result; never a client-supplied DID label.
             verifiedInvokerDid: getMcpRequestHolder()?.did,
-            agentName: this.getAgentName() || mappedEnv.MCP_SERVER_NAME || "Unknown Agent", // Human-readable agent name for AgentShield dashboard
+            agentName: this.getAgentName() || mappedEnv.MCP_SERVER_NAME || "Unknown Agent", // Human-readable agent name for Checkpoint dashboard
             createdAt: timestamp,
             expiresAt: timestamp + 30 * 60 * 1000, // 30 minutes
             serverOrigin: serverUrl, // Use MCP_SERVER_URL for consent URL building
-            projectId: mappedEnv.AGENTSHIELD_PROJECT_ID || "", // For inline consent UI approve POST
+            projectId: mappedEnv.CHECKPOINT_PROJECT_ID || "", // For inline consent UI approve POST
             delegationToken, // ✅ Include token in session if found
             delegationId, // ✅ Include delegationId for proof submission attribution
             userDid, // ✅ FIX: Include userDid in session for ToolExecutionContext propagation
@@ -1765,8 +1797,10 @@ export class MCPICloudflareAgent extends McpAgent {
         // For backward compatibility, handlers can accept (args) or (args, context)
         // JavaScript handlers safely ignore extra arguments. Never retry a handler
         // after it throws: doing so can duplicate irreversible tool side effects.
-        const handlerWithContext = async (handlerArgs) => {
-            return invokeToolHandlerOnce(handler, handlerArgs, toolContext);
+        // The runtime passes `verified` only from THIS call's successful verify, so
+        // the grant a handler enforces is never read from storage or the token.
+        const handlerWithContext = async (handlerArgs, verified) => {
+            return invokeToolHandlerOnce(handler, handlerArgs, withVerifiedDelegation(toolContext, verified, { sessionId, userDid }));
         };
         // Execute tool with automatic proof generation
         // If inline credential UI was prepared, return it directly (no error throw needed)
@@ -1819,6 +1853,9 @@ export class MCPICloudflareAgent extends McpAgent {
                     consentUrl: delegationError.consentUrl,
                     scopes,
                     clientId,
+                    // A verifier refusal (revoked, expired, wrong agent) gets its
+                    // configured per-code line; without one the text stays as today.
+                    denial: delegationError.denial,
                 });
                 // Popup launch — only attached as a hint in `_meta` so popup-aware
                 // clients (today: `.mcpb`-installed Claude Desktop) can open the
@@ -1942,9 +1979,9 @@ export class MCPICloudflareAgent extends McpAgent {
      * @private
      */
     async buildToolContext(toolName, userDid, sessionId, delegationToken, delegationAuthorizationType, env) {
-        // Only build context if userDid is available and AgentShield API is configured.
+        // Only build context if userDid is available and Checkpoint API is configured.
         // Note: DELEGATION_STORAGE is only required for password/OAuth paths, not apikey vault.
-        if (!userDid || !env.AGENTSHIELD_API_KEY) {
+        if (!userDid || !env.CHECKPOINT_API_KEY) {
             return undefined;
         }
         // Check if tool protection service is available
@@ -2128,7 +2165,7 @@ export class MCPICloudflareAgent extends McpAgent {
                     return undefined;
                 }
             }
-            // For API key vault tools, resolve per-user secrets from AgentShield vault.
+            // For API key vault tools, resolve per-user secrets from Checkpoint vault.
             // This follows the same early-return pattern as isPasswordAuth above.
             if (hasApiKeyAuthorization(protection)) {
                 const projectId = toolProtectionService.getProjectId();
@@ -2169,8 +2206,8 @@ export class MCPICloudflareAgent extends McpAgent {
                         pkcs8.set(rawKey, pkcs8Header.length);
                         const identityKey = await crypto.subtle.importKey("pkcs8", pkcs8.buffer, { name: "Ed25519", namedCurve: "Ed25519" }, false, ["sign"]);
                         this._vaultResolver = new VaultResolver({
-                            apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
-                            apiKey: env.AGENTSHIELD_API_KEY,
+                            apiUrl: env.CHECKPOINT_API_URL || "https://kya.vouched.id",
+                            apiKey: env.CHECKPOINT_API_KEY,
                             identityKey,
                             agentDid: identity.did,
                         });
@@ -2195,7 +2232,7 @@ export class MCPICloudflareAgent extends McpAgent {
                             return undefined;
                         }
                         // No vault secrets AND no static env — throw structured error
-                        const apiUrl = env.AGENTSHIELD_API_URL || "https://kya.vouched.id";
+                        const apiUrl = env.CHECKPOINT_API_URL || "https://kya.vouched.id";
                         // Use /dashboard/projects/{id} path — works without orgId and
                         // the dashboard redirects to the correct org-scoped route.
                         const configUrl = `${apiUrl}/dashboard/projects/${projectId}/settings`;
@@ -2256,8 +2293,8 @@ export class MCPICloudflareAgent extends McpAgent {
                 ? new KVOAuthConfigCache({ kv: env.TOOL_PROTECTION_KV })
                 : undefined;
             const oauthConfigService = new ConfigService({
-                baseUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
-                apiKey: env.AGENTSHIELD_API_KEY,
+                baseUrl: env.CHECKPOINT_API_URL || "https://kya.vouched.id",
+                apiKey: env.CHECKPOINT_API_KEY,
                 fetchProvider,
                 cache: oauthConfigCache,
             });
@@ -2266,8 +2303,8 @@ export class MCPICloudflareAgent extends McpAgent {
             const oauthService = new OAuthService({
                 configService: oauthConfigService,
                 fetchProvider,
-                agentShieldApiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
-                agentShieldApiKey: env.AGENTSHIELD_API_KEY,
+                checkpointApiUrl: env.CHECKPOINT_API_URL || "https://kya.vouched.id",
+                checkpointApiKey: env.CHECKPOINT_API_KEY,
                 projectId,
                 // WFP fix (see makeEnvSecretResolver): resolve the client secret from the
                 // RAW worker env. We pass `this.env`, NOT the `env` param — `env` here is
@@ -2381,9 +2418,9 @@ export class MCPICloudflareAgent extends McpAgent {
         const agentDid = getMcpRequestHolder()?.did ?? (await this.mcpiRuntime.getIdentity()).did;
         // Determine the OAuth provider from the error or discover from config
         let provider = error.provider;
-        // If no provider specified, try to discover from AgentShield config
+        // If no provider specified, try to discover from Checkpoint config
         if (!provider) {
-            const agentShieldUrl = env.AGENTSHIELD_API_URL || "https://kya.vouched.id";
+            const checkpointUrl = env.CHECKPOINT_API_URL || "https://kya.vouched.id";
             const oauthServices = isOAuthServicesAvailable()
                 ? getOAuthServices()
                 : null;
@@ -2394,13 +2431,13 @@ export class MCPICloudflareAgent extends McpAgent {
                         kv: env.TOOL_PROTECTION_KV,
                     });
                     const configService = new OAuthConfigService({
-                        baseUrl: agentShieldUrl,
-                        apiKey: env.AGENTSHIELD_API_KEY || "",
+                        baseUrl: checkpointUrl,
+                        apiKey: env.CHECKPOINT_API_KEY || "",
                         fetchProvider: new WorkersFetchProvider(),
                         cache: oauthConfigCache,
                     });
                     const registry = new OAuthProviderRegistry(configService);
-                    await registry.loadFromAgentShield(projectId);
+                    await registry.loadFromCheckpoint(projectId);
                     const discoveredProvider = registry.getConfiguredProvider();
                     if (discoveredProvider) {
                         provider = discoveredProvider;
@@ -2515,6 +2552,11 @@ export class MCPICloudflareAgent extends McpAgent {
      */
     async fetch(request) {
         const url = new URL(request.url);
+        // Native state moved to its own binding/class. Refuse obsolete internal
+        // dispatch without initializing MCP or touching the shared Agent scheduler.
+        if (url.pathname.startsWith(NATIVE_OAUTH_INTERNAL_PREFIX)) {
+            return new Response(null, { status: 404 });
+        }
         // draft-kya-http-02 §13 pickup-anchor dispatch.
         // These requests target dedicated `pickup:<sid>` durable-object instances and
         // must run BEFORE any origin detection, handshake-session side effects, or
@@ -2712,7 +2754,7 @@ export class MCPICloudflareAgent extends McpAgent {
                         : this.env;
                     const runtimeConfig = this.getRuntimeConfigInternal(mappedEnv);
                     const httpChallengeCfg = resolveHttpChallengeConfig(runtimeConfig, mappedEnv);
-                    const augmented = augmentKyaOsIdentityWellKnown(wellKnownPath, result, httpChallengeCfg, isAnchorRegistrationEnabled(httpChallengeCfg, mappedEnv), resolveCloudflareAuditAssurance(runtimeConfig));
+                    const augmented = augmentKyaOsIdentityWellKnown(wellKnownPath, result, httpChallengeCfg, isAnchorRegistrationEnabled(httpChallengeCfg, mappedEnv), resolveCloudflareAuditAssurance(this._runtimeConfig));
                     return new Response(JSON.stringify(augmented), {
                         status: 200,
                         headers: { "Content-Type": "application/json" },
@@ -2997,7 +3039,7 @@ export class MCPICloudflareAgent extends McpAgent {
                 ?.toolProtectionService;
             // Also clear consent config cache
             try {
-                const projectId = this.env.AGENTSHIELD_PROJECT_ID;
+                const projectId = this.env.CHECKPOINT_PROJECT_ID;
                 if (projectId && this.env.TOOL_PROTECTION_KV) {
                     // Clear the consent config cache key directly
                     const consentCacheKey = `consent:config:${projectId}`;