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

package/dist/services/consent.service.js

@@ -8,19 +8,20 @@
  */
 import { ConsentConfigService } from "./consent-config.service";
 import { TemplateRenderer } from "./consent-templates/template-renderer";
-import { DEFAULT_AGENTSHIELD_URL, DEFAULT_SESSION_CACHE_TTL, KEY_PAIR_TTL_SECONDS, CONSENT_PROVIDER_TYPES, } from "../constants";
+import { DEFAULT_CHECKPOINT_URL, DEFAULT_SESSION_CACHE_TTL, KEY_PAIR_TTL_SECONDS, CONSENT_PROVIDER_TYPES, } from "../constants";
 import { STORAGE_KEYS, isPendingDelegationId } from "../constants/storage-keys";
 import { loadDay0Config, getDelegationFieldName } from "../utils/day0-config";
 import { buildProviderAuthorizeUrl } from "../runtime/oidc/authorize-url.js";
 import { resolveIdpScopes } from "../runtime/oidc/idp-scopes.js";
 import { validateConsentApprovalRequest, } from "@kya-os/contracts/consent";
-import { AGENTSHIELD_ENDPOINTS, createDelegationAPIResponseSchema, createDelegationResponseSchema, } from "@kya-os/contracts/agentshield-api";
+import { CHECKPOINT_ENDPOINTS, createDelegationAPIResponseSchema, createDelegationResponseSchema, } from "@kya-os/contracts/checkpoint-api";
 import { createUnsignedVCJWT, completeVCJWT, parseVCJWT, generateDidKeyFromBase64, createDelegationVerifier, createDidKeyResolver, logger, base64urlEncodeFromBytes, base64urlDecodeToBytes, bytesToBase64, wrapDelegationAsVC, } from "@kya-os/mcp";
 import { fetchRemoteConfig, normalizeAuthType, } from "@kya-os/mcp-i-runtime"; // product-layer symbols stay on OLD (C2 #2918)
 import { WebCryptoProvider } from "../providers/crypto";
 import { ConsentAuditService } from "./consent-audit.service";
 import { CloudflareProofGenerator } from "../proof-generator";
 import { ProofService } from "./proof.service";
+import { withMandateConstraints } from "./delegation-mandate";
 import { createCredentialAuthHandler } from "./credential-auth.handler";
 import { IdpTokenStorage } from "./idp-token-storage";
 import { OAuthSecurityService } from "./oauth-security.service";
@@ -54,6 +55,10 @@ function friendlyAgentNameFromDid(did) {
         .replace(/[-_]+/g, " ")
         .replace(/\b\w/g, (c) => c.toUpperCase());
 }
+const MANDATE_ERROR = {
+    error: "Delegation limits could not be resolved",
+    error_code: "mandate_error",
+};
 export class ConsentService {
     configService;
     renderer;
@@ -66,19 +71,56 @@ export class ConsentService {
     // Phase 2: Provider resolution services (optional for backward compatibility)
     providerResolver;
     providerRegistry;
+    delegationMandate;
     /**
      * ✅ FIXED: Constructor takes env: CloudflareEnv, not config
      * Phase 2: Optional providerResolver and providerRegistry for tool-specific providers
      */
-    constructor(env, runtime, providerResolver, providerRegistry) {
+    constructor(env, runtime, providerResolver, providerRegistry, options = {}) {
         this.env = env;
         this.runtime = runtime;
         this.configService = new ConsentConfigService(env);
         this.renderer = new TemplateRenderer({ useCSR: true });
         this.providerResolver = providerResolver;
         this.providerRegistry = providerRegistry;
+        this.delegationMandate = options.delegationMandate;
         // No initialization here - keep constructor synchronous
     }
+    /**
+     * Ask the server's mandate provider about these scopes.
+     *
+     * Keyed on scopes (what the grant authorizes), never on a tool name, so a
+     * request naming a different tool with the same scopes gets the same
+     * limits. The provider gets the runtime identity DID, so a mandate can name
+     * this server as the merchant without trusting any request field.
+     *
+     * Without a provider this always returns `{ ok: true, mandate: undefined }`.
+     * With one, a missing identity or a throw returns `{ ok: false }`.
+     */
+    async resolveMandate(scopes, projectId) {
+        const provider = this.delegationMandate;
+        if (!provider)
+            return { ok: true, mandate: undefined };
+        try {
+            const serverDid = (await this.runtime?.getIdentity())?.did;
+            if (!serverDid) {
+                logger.error("[ConsentService] Delegation mandate configured but the server identity is unavailable");
+                return { ok: false };
+            }
+            const mandate = provider({ scopes: [...scopes], serverDid, projectId });
+            return { ok: true, mandate };
+        }
+        catch (error) {
+            logger.error("[ConsentService] Delegation mandate provider failed:", error);
+            return { ok: false };
+        }
+    }
+    mandateErrorResponse() {
+        return new Response(JSON.stringify({ success: false, ...MANDATE_ERROR }), {
+            status: 500,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
     /**
      * Get or initialize audit service (lazy initialization)
      *
@@ -182,7 +224,7 @@ export class ConsentService {
         }
     }
     /**
-     * Fetch CloudflareRuntimeConfig from remote API (AgentShield)
+     * Fetch CloudflareRuntimeConfig from remote API (Checkpoint)
      *
      * ⚠️ CRITICAL: Config MUST be fetched from remote API, not constructed from env.
      *
@@ -193,7 +235,7 @@ export class ConsentService {
      * @returns Runtime config or undefined if unavailable
      */
     async getConfigFromRemoteAPI(projectId) {
-        if (!this.env.AGENTSHIELD_API_KEY) {
+        if (!this.env.CHECKPOINT_API_KEY) {
             logger.warn("[ConsentService] No API key for runtime config fetch");
             return undefined;
         }
@@ -212,15 +254,15 @@ export class ConsentService {
                 }
                 : undefined;
             const config = await fetchRemoteConfig({
-                apiUrl: this.env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
-                apiKey: this.env.AGENTSHIELD_API_KEY,
+                apiUrl: this.env.CHECKPOINT_API_URL || "https://kya.vouched.id",
+                apiKey: this.env.CHECKPOINT_API_KEY,
                 projectId, // ✅ Use projectId from consent request
                 cacheTtl: 300000, // 5 minutes
                 fetchProvider: fetch,
             }, cache);
             // Populate serverDid from runtime identity if missing or empty
-            // This prevents AgentShield validation errors (serverDid must be at least 1 character)
-            // Note: MCPIConfig.identity is RuntimeIdentityConfig (no serverDid), but AgentShield
+            // This prevents Checkpoint validation errors (serverDid must be at least 1 character)
+            // Note: MCPIConfig.identity is RuntimeIdentityConfig (no serverDid), but Checkpoint
             // may return MCPIServerConfig format (has serverDid). We need to handle both.
             if (config && config.identity) {
                 const identityConfig = config.identity; // Type assertion for serverDid field
@@ -374,11 +416,11 @@ export class ConsentService {
     /**
      * Update session with resolved identity (Phase 5)
      *
-     * Called after AgentShield identity/resolve returns a persistent user DID.
+     * Called after Checkpoint identity/resolve returns a persistent user DID.
      * Stores the DID in session storage and creates OAuth mapping.
      *
      * @param sessionId - Session ID
-     * @param userDid - Persistent user DID from AgentShield
+     * @param userDid - Persistent user DID from Checkpoint
      * @param oauthIdentity - OAuth identity for creating persistent mapping
      */
     async updateSessionWithIdentity(sessionId, userDid, oauthIdentity) {
@@ -537,8 +579,8 @@ export class ConsentService {
      * GENERATES a new key pair if one doesn't exist.
      *
      * NOTE: The generated key pair has its own did:key which may differ
-     * from AgentShield's persistentUserDid. Both are tied to the same
-     * OAuth identity. See docs/proposals/VC/AGENTSHIELD_SIGNING_ENDPOINT.md
+     * from Checkpoint's persistentUserDid. Both are tied to the same
+     * OAuth identity. See docs/proposals/VC/CHECKPOINT_SIGNING_ENDPOINT.md
      * for the future cleaner architecture.
      *
      * @param sessionId - Session ID for caching
@@ -889,7 +931,7 @@ export class ConsentService {
      *
      * Determines if OAuth flow should be used instead of direct delegation creation.
      * OAuth is required if:
-     * - Project has OAuth provider configured in AgentShield
+     * - Project has OAuth provider configured in Checkpoint
      * - No OAuth identity is present in the request
      *
      * @param projectId - Project ID to check
@@ -960,14 +1002,14 @@ export class ConsentService {
         }
         // Check project config to see if OAuth is configured
         try {
-            const agentShieldUrl = this.env.AGENTSHIELD_API_URL || DEFAULT_AGENTSHIELD_URL;
-            const apiKey = this.env.AGENTSHIELD_API_KEY;
+            const checkpointUrl = this.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_URL;
+            const apiKey = this.env.CHECKPOINT_API_KEY;
             if (!apiKey) {
                 // No API key - can't check, assume OAuth not required
                 return false;
             }
             // Fetch project config to check for OAuth provider
-            const configUrl = `${agentShieldUrl}/api/v1/bouncer/projects/${projectId}/config`;
+            const configUrl = `${checkpointUrl}/api/v1/bouncer/projects/${projectId}/config`;
             const response = await fetch(configUrl, {
                 headers: {
                     Authorization: `Bearer ${apiKey}`,
@@ -1007,15 +1049,15 @@ export class ConsentService {
      * @param serverUrl - Server URL for callback
      * @param provider - Optional provider name (resolved if not provided)
      * @param oauthSecurityService - Optional OAuthSecurityService for CSRF protection
-     * @param agentName - Optional human-readable agent name for AgentShield dashboard display
+     * @param agentName - Optional human-readable agent name for Checkpoint dashboard display
      * @param tool - Optional tool name to preserve through OAuth flow for clickwrap redirect
      * @returns OAuth authorization URL
      */
     async buildOAuthUrl(projectId, agentDid, sessionId, scopes, serverUrl, provider, // Phase 2: Optional provider name (resolved if not provided)
-    oauthSecurityService, agentName, // Human-readable agent name for AgentShield dashboard
+    oauthSecurityService, agentName, // Human-readable agent name for Checkpoint dashboard
     tool // Tool name to preserve through OAuth callback for clickwrap redirect
     ) {
-        const agentShieldUrl = this.env.AGENTSHIELD_API_URL || DEFAULT_AGENTSHIELD_URL;
+        const checkpointUrl = this.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_URL;
         // Generate a temporary delegation ID for state (will be created after OAuth)
         const delegationId = `temp-${Date.now()}`;
         // ✅ Phase 1: Generate PKCE challenge if OAuthSecurityService is available
@@ -1086,17 +1128,17 @@ export class ConsentService {
             stateParam = btoa(JSON.stringify(stateData));
         }
         // Phase 3: Resolve provider config and extract custom parameters
-        // Load providers from AgentShield API if not already loaded
+        // Load providers from Checkpoint API if not already loaded
         let providerConfig = null;
         if (provider && this.providerRegistry) {
             // Lazy load providers if registry is empty (first request for this project)
             if (this.providerRegistry.getProviderNames().length === 0) {
-                logger.debug("[ConsentService] Loading providers from AgentShield", {
+                logger.debug("[ConsentService] Loading providers from Checkpoint", {
                     projectId,
                     provider,
                 });
                 try {
-                    await this.providerRegistry.loadFromAgentShield(projectId);
+                    await this.providerRegistry.loadFromCheckpoint(projectId);
                     logger.debug("[ConsentService] Providers loaded successfully", {
                         projectId,
                         providers: this.providerRegistry.getProviderNames(),
@@ -1104,7 +1146,7 @@ export class ConsentService {
                     });
                 }
                 catch (loadError) {
-                    logger.warn("[ConsentService] Failed to load providers from AgentShield", {
+                    logger.warn("[ConsentService] Failed to load providers from Checkpoint", {
                         projectId,
                         error: loadError instanceof Error
                             ? loadError.message
@@ -1136,7 +1178,7 @@ export class ConsentService {
                             : "using direct PKCE mode",
         });
         // Direct OAuth Mode: Use provider's authorization URL directly for PKCE-capable providers
-        // This bypasses AgentShield bouncer and redirects straight to GitHub/Google/etc.
+        // This bypasses Checkpoint bouncer and redirects straight to GitHub/Google/etc.
         //
         // Flow: User → GitHub OAuth → MCP-I /oauth/callback → Success page
         //
@@ -1145,7 +1187,7 @@ export class ConsentService {
         // - proxyMode: false = no client secret needed, direct exchange with provider
         //
         // When proxyMode is true (e.g., GitHub OAuth Apps with client_secret), we must
-        // use AgentShield bouncer to exchange tokens because it has the client_secret.
+        // use Checkpoint bouncer to exchange tokens because it has the client_secret.
         // See oauth-service.ts lines 82, 372 for the same pattern.
         //
         // Examples: GitHub Apps (PKCE, no proxy), Google (PKCE, no proxy)
@@ -1153,7 +1195,7 @@ export class ConsentService {
         if (providerConfig &&
             providerConfig.supportsPKCE &&
             !providerConfig.proxyMode) {
-            // Use providerConfig.clientId from AgentShield dashboard config
+            // Use providerConfig.clientId from Checkpoint dashboard config
             const oauthClientId = providerConfig.clientId || projectId;
             // The `scopes` argument holds MCP-I delegation scopes (e.g. "greet:execute"),
             // which the identity provider has never heard of. Only the provider's own
@@ -1194,11 +1236,11 @@ export class ConsentService {
                 }
             }
         }
-        // Build OAuth authorization URL (AgentShield bouncer endpoint)
-        // NOTE: This is a legacy proxy mode path that requires AgentShield to act as an OAuth proxy.
+        // Build OAuth authorization URL (Checkpoint bouncer endpoint)
+        // NOTE: This is a legacy proxy mode path that requires Checkpoint to act as an OAuth proxy.
         // Most providers (GitHub, Google) use direct PKCE mode instead (see buildDirectOAuthUrl).
         // If this path is hit and results in a 404, check if the provider supports PKCE.
-        const oauthUrl = new URL(`${agentShieldUrl}/bouncer/oauth/authorize`);
+        const oauthUrl = new URL(`${checkpointUrl}/bouncer/oauth/authorize`);
         oauthUrl.searchParams.set("response_type", "code");
         oauthUrl.searchParams.set("client_id", projectId); // Use projectId as client_id
         oauthUrl.searchParams.set("redirect_uri", `${serverUrl}/oauth/callback`);
@@ -1206,14 +1248,14 @@ export class ConsentService {
         // delegation scopes, not what belongs in the IdP-facing `scope` param.
         oauthUrl.searchParams.set("scope", resolveIdpScopes(providerConfig).join(" "));
         oauthUrl.searchParams.set("state", stateParam);
-        // ✅ Pass provider to AgentShield bouncer so it selects the correct auth method
+        // ✅ Pass provider to Checkpoint bouncer so it selects the correct auth method
         // This is critical when multiple providers are configured for a project
         // e.g., "credentials" for credential login or "github" for GitHub OAuth
-        // Without this, AgentShield picks the first provider which may be incorrect
+        // Without this, Checkpoint picks the first provider which may be incorrect
         if (provider) {
             oauthUrl.searchParams.set("provider", provider);
         }
-        // ✅ Add agent_name for AgentShield dashboard display
+        // ✅ Add agent_name for Checkpoint dashboard display
         // This provides a human-readable name instead of just the agent DID
         if (agentName) {
             oauthUrl.searchParams.set("agent_name", agentName);
@@ -1232,7 +1274,7 @@ export class ConsentService {
         return oauthUrl.toString();
     }
     /**
-     * Build direct OAuth URL (bypasses AgentShield bouncer endpoint)
+     * Build direct OAuth URL (bypasses Checkpoint bouncer endpoint)
      *
      * Used for custom providers that need direct OAuth URLs (e.g., self-hosted OAuth servers).
      * Triggered when providerConfig.proxyMode === true && !providerConfig.supportsPKCE
@@ -1264,7 +1306,7 @@ export class ConsentService {
      * Link OAuth identity to User DID
      *
      * Maps OAuth provider identity (provider + subject) to a persistent User DID.
-     * Phase 5: Requires existing userDid from AgentShield /identity/resolve endpoint.
+     * Phase 5: Requires existing userDid from Checkpoint /identity/resolve endpoint.
      * Throws error if session has no user DID (enforces OAuth → identity flow).
      *
      * @param oauthIdentity - OAuth provider identity
@@ -1297,8 +1339,8 @@ export class ConsentService {
         // Phase 5: Check for existing user DID in session
         const userDid = await this.getUserDidForSession(sessionId);
         if (!userDid) {
-            // Phase 5: No existing DID - user must complete OAuth via AgentShield first
-            throw new Error("[ConsentService] No user DID found for session - OAuth identity resolution required via AgentShield");
+            // Phase 5: No existing DID - user must complete OAuth via Checkpoint first
+            throw new Error("[ConsentService] No user DID found for session - OAuth identity resolution required via Checkpoint");
         }
         // Store OAuth identity mapping (persistent - 90 days)
         try {
@@ -1323,14 +1365,14 @@ export class ConsentService {
         return userDid;
     }
     /**
-     * Cache an externally-resolved User DID (from AgentShield identity resolution)
+     * Cache an externally-resolved User DID (from Checkpoint identity resolution)
      *
-     * Phase 5: When AgentShield provides a persistent user_did, we cache the
+     * Phase 5: When Checkpoint provides a persistent user_did, we cache the
      * OAuth identity → userDid mapping in KV so future lookups don't require
-     * calling AgentShield again.
+     * calling Checkpoint again.
      *
      * @param oauthIdentity - OAuth identity from provider
-     * @param userDid - Persistent user DID from AgentShield
+     * @param userDid - Persistent user DID from Checkpoint
      * @returns void
      */
     async cacheExternalUserDid(oauthIdentity, userDid) {
@@ -1351,7 +1393,7 @@ export class ConsentService {
                         existingUserDid: existingUserDid.substring(0, 30) + "...",
                         newUserDid: userDid.substring(0, 30) + "...",
                     });
-                    // Don't overwrite - AgentShield is source of truth
+                    // Don't overwrite - Checkpoint is source of truth
                 }
                 return;
             }
@@ -1370,11 +1412,11 @@ export class ConsentService {
             await this.env.DELEGATION_STORAGE.put(oauthIdentityKey, JSON.stringify(oauthIdentity), {
                 expirationTtl: 90 * 24 * 60 * 60, // 90 days
             });
-            logger.debug("[ConsentService] Cached external User DID from AgentShield:", {
+            logger.debug("[ConsentService] Cached external User DID from Checkpoint:", {
                 provider: oauthIdentity.provider,
                 subject: oauthIdentity.subject.substring(0, 20) + "...",
                 userDid: userDid.substring(0, 30) + "...",
-                source: "agentshield_identity_resolution",
+                source: "checkpoint_identity_resolution",
             });
         }
         catch (error) {
@@ -1530,7 +1572,7 @@ export class ConsentService {
             // e.g., ?provider_type=password indicates credential auth is expected
             const urlProviderType = params.get("provider_type");
             // ✅ Extract agent_name from URL query param (passed from buildConsentUrl)
-            // Human-readable name for AgentShield dashboard display
+            // Human-readable name for Checkpoint dashboard display
             const agentName = params.get("agent_name");
             // ✅ Extract credential auth params for 3-screen flow (Auth → Clickwrap → Success)
             // These are set when credential auth completes and redirects to clickwrap page
@@ -1542,7 +1584,7 @@ export class ConsentService {
             // This ensures storeDelegationToken can use the correct user+agent key immediately
             const userDidFromParams = params.get("user_did");
             // ✅ Extract user info from credential provider for delegation metadata
-            // These are used for human-readable display in AgentShield dashboard
+            // These are used for human-readable display in Checkpoint dashboard
             const credentialUserEmail = params.get("credential_user_email");
             const credentialProviderUserId = params.get("credential_provider_user_id");
             // ✅ Extract mode param for post-auth clickwrap detection
@@ -1584,6 +1626,13 @@ export class ConsentService {
             const scopes = scopesParam
                 ? scopesParam.split(",").map((s) => s.trim())
                 : [];
+            // Resolve the server-bound mandate before anything renders: with a
+            // provider configured, a failure must never produce an approvable page.
+            const mandateResolution = await this.resolveMandate(scopes, projectId);
+            if (!mandateResolution.ok) {
+                return this.mandateErrorResponse();
+            }
+            const mandate = mandateResolution.mandate;
             // Get tool description (try to fetch from runtime or use default)
             let toolDescription = `Execute ${tool}`;
             if (this.runtime) {
@@ -1596,7 +1645,7 @@ export class ConsentService {
                     // Fallback to default
                 }
             }
-            // Get consent config from AgentShield or defaults
+            // Get consent config from Checkpoint or defaults
             const consentConfig = await this.configService.getConsentConfig(projectId);
             // Build server URL from request origin
             // Priority: 1) env var, 2) request origin, 3) error if neither available
@@ -1835,7 +1884,7 @@ export class ConsentService {
                 // Note: We're building it here, but we'll pass it to the renderer
                 // instead of redirecting immediately, so the user sees the consent page first.
                 resolvedOAuthUrl = await this.buildOAuthUrl(projectId, agentDid, sessionId, scopes, serverUrl, provider, // Pass resolved provider for direct OAuth mode (PKCE)
-                oauthSecurityService, agentName || undefined, // Human-readable agent name for AgentShield dashboard
+                oauthSecurityService, agentName || undefined, // Human-readable agent name for Checkpoint dashboard
                 tool || undefined // Tool name to preserve through OAuth callback for clickwrap redirect
                 );
                 isOAuthRequired = true;
@@ -1937,7 +1986,7 @@ export class ConsentService {
             // Build consent page config
             // ✅ CRITICAL: Pass the FULL consent config (ui, credentials, etc.) not just branding/terms
             // Type assertion to handle updated schema before rebuild
-            // The remote consent config (from agent-shield) carries fields that
+            // The remote consent config (from checkpoint) carries fields that
             // aren't in the trimmed contracts ConsentPageConfig type. Read them off
             // a Record<string, unknown> view so we can plumb them through without
             // touching contracts.
@@ -2058,8 +2107,13 @@ export class ConsentService {
                 ui: consentConfig.ui,
                 // ✅ FIX: Pass credentials config (username/password labels, forgot password, etc.)
                 credentials: consentConfig.credentials,
-                // ✅ FIX: Pass expiration days
-                expirationDays: consentConfig.expirationDays,
+                // ✅ FIX: Pass expiration days. A mandate's fixed lifetime wins, and is
+                // also stated as fixedExpiryDays so the footer says "N days after
+                // approval" instead of the (false, for these grants) inactivity copy.
+                expirationDays: mandate?.expiresInDays ?? consentConfig.expirationDays,
+                ...(mandate?.expiresInDays !== undefined
+                    ? { fixedExpiryDays: mandate.expiresInDays }
+                    : {}),
                 // Pass OAuth details for client-side handling
                 oauthRequired: isOAuthRequired,
                 oauthUrl: resolvedOAuthUrl,
@@ -2083,12 +2137,14 @@ export class ConsentService {
                 // from the bouncer config; falls back to the @kya-os/consent default
                 // registry resolved from the URL's scopes, so the new layout renders
                 // even when the dashboard hasn't pushed capability metadata yet.
-                capabilities: resolvedCapabilities,
+                // A mandate's capabilities describe the limits the grant will carry,
+                // so they replace remote and registry rows.
+                capabilities: mandate?.capabilities ?? resolvedCapabilities,
                 agentMetadata: resolvedAgentMetadata,
                 consentTheme: remoteConsentTheme,
                 orgName: resolvedOrgName,
                 headlineVerb: remoteHeadlineVerb,
-                revocationPath: remoteRevocationPath,
+                revocationPath: mandate?.revocationPath ?? remoteRevocationPath,
                 inactivityDays: remoteInactivityDays,
                 howItWorksUrl: remoteHowItWorksUrl,
                 // Bind operator-authored Cedar fragment placeholders at render time
@@ -2109,7 +2165,7 @@ export class ConsentService {
             // 2. Must NOT be in post-credential clickwrap mode (would cause infinite loop)
             if (credentialProviderConfig && !isPostCredentialClickwrap) {
                 // Determine authorization type from tool protection config
-                // Default to 'password' for credential flows (matches AgentShield expectations)
+                // Default to 'password' for credential flows (matches Checkpoint expectations)
                 // The authorization.type from tool protection tells us what type of auth the tool expects
                 const authorizationType = protection?.authorization?.type ?? "password";
                 logger.debug("[ConsentService] Credential provider detected, rendering credential page", {
@@ -3269,7 +3325,7 @@ export class ConsentService {
     /**
      * Handle consent approval
      *
-     * Validates request, creates delegation via AgentShield API,
+     * Validates request, creates delegation via Checkpoint API,
      * stores token in KV, and returns success response.
      *
      * @param request - Approval request
@@ -3303,7 +3359,7 @@ export class ConsentService {
             let trustedUserDid;
             // CRED-003: Check for credential provider submission
             // Credential submissions include `provider_type: 'credential'` or 'password' and are handled separately
-            // IMPORTANT: AgentShield tool protection uses 'password' for credential-based auth validation,
+            // IMPORTANT: Checkpoint tool protection uses 'password' for credential-based auth validation,
             // but we also accept 'credential' for backward compatibility
             if (providerType === CONSENT_PROVIDER_TYPES.CREDENTIAL ||
                 providerType === CONSENT_PROVIDER_TYPES.PASSWORD) {
@@ -3632,7 +3688,7 @@ export class ConsentService {
                     headers: { "Content-Type": "application/json" },
                 });
             }
-            // Create delegation via AgentShield API
+            // Create delegation via Checkpoint API
             logger.debug("[ConsentService] Creating delegation...");
             const delegationResult = await this.createDelegation(approvalRequest, resolveExpirationDays(consentConfig.expirationDays), resolvedUserDid ?? null);
             if (!delegationResult.success) {
@@ -3732,14 +3788,21 @@ export class ConsentService {
         }
     }
     /**
-     * Create delegation via AgentShield API
+     * Create delegation via Checkpoint API
      *
      * @param request - Approval request
      * @returns Delegation creation result
      */
     async createDelegation(request, expirationDaysOverride, resolvedUserDid) {
-        const agentShieldUrl = this.env.AGENTSHIELD_API_URL || DEFAULT_AGENTSHIELD_URL;
-        const apiKey = this.env.AGENTSHIELD_API_KEY;
+        // Resolve the mandate from the APPROVED scopes first: nothing (no VC, no
+        // POST) may happen when a configured provider cannot answer.
+        const mandateResolution = await this.resolveMandate(request.scopes ?? [], request.project_id);
+        if (!mandateResolution.ok) {
+            return { success: false, ...MANDATE_ERROR };
+        }
+        const mandate = mandateResolution.mandate;
+        const checkpointUrl = this.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_URL;
+        const apiKey = this.env.CHECKPOINT_API_KEY;
         if (!apiKey) {
             logger.warn("[ConsentService] No API key configured, cannot create delegation");
             return {
@@ -3806,7 +3869,11 @@ export class ConsentService {
                     logger.debug("[ConsentService] No session_id provided - skipping User DID generation");
                 }
             }
-            const expiresInDays = expirationDaysOverride ?? DEFAULT_EXPIRATION_DAYS;
+            // A mandate's fixed lifetime is part of the grant the user saw, so it
+            // wins over the consent-config expiry.
+            const expiresInDays = mandate?.expiresInDays ??
+                expirationDaysOverride ??
+                DEFAULT_EXPIRATION_DAYS;
             // Phase 2 VC-Only: Issue Delegation VC if we have a session and userDid
             let credentialJwt;
             if (request.session_id && userDid) {
@@ -3827,6 +3894,8 @@ export class ConsentService {
                             scopes,
                             notAfter,
                             notBefore: nowSec,
+                            // The user signs the same limits Checkpoint is asked to hold.
+                            ...(mandate ? { crisp: mandate.constraints.crisp } : {}),
                         },
                         signature: "vc-jwt-signed", // Placeholder - actual signature is in the VC-JWT
                         status: "active",
@@ -3848,9 +3917,14 @@ export class ConsentService {
             }
             // Build delegation request with error-based format detection
             // Try full format first, fallback to simplified format on error
-            const delegationRequest = await this.buildDelegationRequest(request, userDid, expiresInDays, fieldName, credentialJwt);
+            const builtRequest = await this.buildDelegationRequest(request, userDid, expiresInDays, fieldName, credentialJwt);
+            // Every body tryAPICall may POST carries the mandate's constraints, so
+            // a format fallback can never create an unconstrained grant.
+            const delegationRequest = mandate
+                ? withMandateConstraints(builtRequest, mandate.constraints)
+                : builtRequest;
             logger.debug("[ConsentService] Creating delegation:", {
-                url: `${agentShieldUrl}${AGENTSHIELD_ENDPOINTS.DELEGATIONS_CREATE}`,
+                url: `${checkpointUrl}${CHECKPOINT_ENDPOINTS.DELEGATIONS_CREATE}`,
                 agentDid: request.agent_did.substring(0, 20) + "...",
                 scopes: request.scopes,
                 expiresInDays,
@@ -3859,12 +3933,12 @@ export class ConsentService {
                 hasUserDid: !!userDid,
             });
             // Error-based format detection: try request format, fallback on error
-            const response = await this.tryAPICall(agentShieldUrl, apiKey, delegationRequest);
+            const response = await this.tryAPICall(checkpointUrl, apiKey, delegationRequest);
             if (!response.success) {
                 return response;
             }
             const responseData = response.data;
-            // Canonical format per @kya-os/contracts/agentshield-api:
+            // Canonical format per @kya-os/contracts/checkpoint-api:
             // Wrapped: { success: true, data: { delegation_id: string, agent_did: string, ... } }
             // Unwrapped: { delegation_id: string, agent_did: string, ... }
             //
@@ -3877,7 +3951,7 @@ export class ConsentService {
                 const wrappedResponse = wrappedParse.data;
                 const delegationId = wrappedResponse.data.delegation_id;
                 // Extract delegation_token (JWT) if present in response
-                // AgentShield now returns delegation_token for stateless verification
+                // Checkpoint now returns delegation_token for stateless verification
                 const responseDataObj = wrappedResponse.data;
                 const delegationToken = responseDataObj.delegation_token;
                 logger.info("[ConsentService] ✅ Delegation created successfully:", {
@@ -4236,11 +4310,11 @@ export class ConsentService {
                 // Ignore cache errors
             }
         }
-        // If we have a cached preference, use it directly
-        if (cachedFormat === "full") {
-            return this.buildFullFormatRequest(request, userDid, expiresInDays, credentialJwt);
-        }
-        else if (cachedFormat === "simplified") {
+        // A cached "simplified" skips the full POST. A cached "full" gets the same
+        // try-both request as no cache: a stale or wrongly cached "full" must never
+        // remove the simplified fallback, because an API that rejects the full
+        // format would then fail every approval until the cache expired.
+        if (cachedFormat === "simplified") {
             return this.buildSimplifiedFormatRequest(request, userDid, expiresInDays, fieldName, credentialJwt);
         }
         // No cache - return request that will be tried with error-based detection
@@ -4257,7 +4331,7 @@ export class ConsentService {
      * Handle credential-based authentication submission
      *
      * Authenticates user credentials against customer's endpoint, resolves identity
-     * via AgentShield, stores token with usage metadata, and creates delegation.
+     * via Checkpoint, stores token with usage metadata, and creates delegation.
      *
      * @param body - Raw request body with credential fields
      * @param request - Original request (for URL derivation if MCP_SERVER_URL not set)
@@ -4327,7 +4401,7 @@ export class ConsentService {
             }
         }
         try {
-            // 1. Fetch credential provider config from AgentShield
+            // 1. Fetch credential provider config from Checkpoint
             const providerConfig = await this.getCredentialProviderConfig(project_id, provider);
             if (!providerConfig) {
                 logger.debug("[ConsentService] Credential provider config not found", {
@@ -4377,7 +4451,7 @@ export class ConsentService {
                 }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
             logger.info("[ConsentService] ✅ Credential authentication successful");
-            // 3. Resolve identity via AgentShield
+            // 3. Resolve identity via Checkpoint
             const identityResult = await this.resolveCredentialIdentity({
                 projectId: project_id,
                 provider: provider,
@@ -4578,7 +4652,7 @@ export class ConsentService {
             //   credential_provider_user_id → user_id (provider's internal ID for business reference)
             //   user_did → user_did (cryptographic identity, always present)
             if (authResult.userEmail) {
-                // Email for human-readable display in AgentShield dashboard
+                // Email for human-readable display in Checkpoint dashboard
                 clickwrapUrl.searchParams.set("credential_user_email", authResult.userEmail);
             }
             if (authResult.userId) {
@@ -4680,7 +4754,7 @@ export class ConsentService {
         return [];
     }
     /**
-     * Fetch credential provider config from AgentShield
+     * Fetch credential provider config from Checkpoint
      *
      * Uses the V1 /providers endpoint which returns all configured providers
      * including credential providers with type: 'credential'.
@@ -4688,17 +4762,17 @@ export class ConsentService {
      * @see OAuthConfigService.getOAuthConfig() for the same endpoint usage
      */
     async getCredentialProviderConfig(projectId, providerName) {
-        const agentShieldUrl = this.env.AGENTSHIELD_API_URL || DEFAULT_AGENTSHIELD_URL;
-        const apiKey = this.env.AGENTSHIELD_API_KEY;
+        const checkpointUrl = this.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_URL;
+        const apiKey = this.env.CHECKPOINT_API_KEY;
         if (!apiKey) {
-            logger.warn("[ConsentService] No AgentShield API key configured");
+            logger.warn("[ConsentService] No Checkpoint API key configured");
             return null;
         }
         try {
             // Use the /providers endpoint - same as OAuthConfigService.getOAuthConfig()
             // This endpoint was updated in fix/provider-config to read from oauthProviders JSONB
             // Authentication: Use Authorization: Bearer header for consistency with OAuthConfigService
-            const response = await fetch(`${agentShieldUrl}/api/v1/bouncer/projects/${encodeURIComponent(projectId)}/providers`, {
+            const response = await fetch(`${checkpointUrl}/api/v1/bouncer/projects/${encodeURIComponent(projectId)}/providers`, {
                 headers: {
                     Authorization: `Bearer ${apiKey}`,
                     "Content-Type": "application/json",
@@ -4726,13 +4800,13 @@ export class ConsentService {
             if (providerName in providers) {
                 const rawProvider = providers[providerName];
                 // AUTH-TYPE-UNIFICATION: 'password' is the canonical type for form-based auth
-                // AgentShield now returns type: 'password' (updated 2025-12-29)
+                // Checkpoint now returns type: 'password' (updated 2025-12-29)
                 // Also accept 'credential' for backward compatibility with existing configurations
                 // See: proposals/2025-01-delegation-schema-fix/AUTH-TYPE-UNIFICATION.md
                 if (rawProvider.type === CONSENT_PROVIDER_TYPES.PASSWORD ||
                     rawProvider.type === CONSENT_PROVIDER_TYPES.CREDENTIAL) {
                     // Map snake_case fields to camelCase (same pattern as OAuthConfigService)
-                    // AgentShield API may return snake_case fields from database
+                    // Checkpoint API may return snake_case fields from database
                     const provider = this.mapCredentialProviderFields(rawProvider, providerName);
                     if (!provider) {
                         logger.debug("[ConsentService] Credential provider validation failed:", {
@@ -4759,7 +4833,7 @@ export class ConsentService {
     /**
      * Map snake_case fields to camelCase for CredentialProviderConfig
      *
-     * AgentShield API may return snake_case fields from the database.
+     * Checkpoint API may return snake_case fields from the database.
      * This follows the same pattern as OAuthConfigService.getOAuthConfig().
      *
      * @param raw - Raw provider object from API response
@@ -4845,17 +4919,17 @@ export class ConsentService {
         };
     }
     /**
-     * Resolve identity via AgentShield for credential-based auth
+     * Resolve identity via Checkpoint for credential-based auth
      */
     async resolveCredentialIdentity(params) {
-        const agentShieldUrl = this.env.AGENTSHIELD_API_URL || DEFAULT_AGENTSHIELD_URL;
-        const apiKey = this.env.AGENTSHIELD_API_KEY;
+        const checkpointUrl = this.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_URL;
+        const apiKey = this.env.CHECKPOINT_API_KEY;
         if (!apiKey) {
-            logger.warn("[ConsentService] No AgentShield API key for identity resolution");
+            logger.warn("[ConsentService] No Checkpoint API key for identity resolution");
             return { success: false };
         }
         try {
-            const response = await fetch(`${agentShieldUrl}/api/v1/bouncer/identity/resolve`, {
+            const response = await fetch(`${checkpointUrl}/api/v1/bouncer/identity/resolve`, {
                 method: "POST",
                 headers: {
                     "X-API-Key": apiKey,
@@ -5289,12 +5363,12 @@ export class ConsentService {
         //
         // Fallback Strategy:
         // 1. If email available → user_identifier = email (preferred)
-        // 2. If no email → user_identifier = userDid (fallback so AgentShield has something to display)
-        // AgentShield will also check metadata.user_email for extraction
+        // 2. If no email → user_identifier = userDid (fallback so Checkpoint has something to display)
+        // Checkpoint will also check metadata.user_email for extraction
         if (userDid) {
             // user_did is the primary identifier - the actual DID
             result.user_did = userDid;
-            // user_identifier: Human-readable identifier (email/username) for AgentShield dashboard display
+            // user_identifier: Human-readable identifier (email/username) for Checkpoint dashboard display
             // user_id: Provider's internal ID (e.g., customer ID 696395) for business reference
             // user_did: Cryptographic DID for identity verification
             if (request.credential_user_email) {
@@ -5303,7 +5377,7 @@ export class ConsentService {
             }
             else {
                 // No email - fall back to DID so dashboard has something to display
-                // AgentShield will detect this is a DID and may display differently
+                // Checkpoint will detect this is a DID and may display differently
                 result.user_identifier = userDid;
             }
             // user_id is the provider's internal ID (separate from email)
@@ -5331,7 +5405,7 @@ export class ConsentService {
         }
         // MCP-I Compatibility: Include user_email and user_id in custom_fields (becomes metadata)
         // This matches buildSimplifiedFormatRequest behavior for consistency
-        // AgentShield extracts these from metadata when user_identifier is not provided
+        // Checkpoint extracts these from metadata when user_identifier is not provided
         //
         // user_email = human-readable email (for display)
         // user_id = provider's internal ID (for business reference)
@@ -5351,7 +5425,7 @@ export class ConsentService {
                 format_version: "full_v1",
                 ...(providerType ? { provider_type: providerType } : {}),
                 // MCP-I Compatibility: Include user_email and user_id in metadata
-                // AgentShield will extract these if user_identifier is not provided
+                // Checkpoint will extract these if user_identifier is not provided
                 // user_email = human-readable email (for display)
                 // user_id = provider's internal ID (for business reference, e.g., customer ID 696395)
                 ...(fullFormatUserEmail ? { user_email: fullFormatUserEmail } : {}),
@@ -5362,7 +5436,7 @@ export class ConsentService {
                 ...customFieldsFromRequest,
             };
             if (fullFormatUserEmail || fullFormatProviderUserId) {
-                logger.debug("[ConsentService] Full format: Including user info in custom_fields for AgentShield compatibility:", {
+                logger.debug("[ConsentService] Full format: Including user info in custom_fields for Checkpoint compatibility:", {
                     user_email: fullFormatUserEmail
                         ? fullFormatUserEmail.substring(0, 20) + "..."
                         : undefined,
@@ -5398,14 +5472,14 @@ export class ConsentService {
      * Build simplified format request with proper field name
      *
      * CRITICAL: This method MUST NOT include session_id or project_id in the request body.
-     * These fields are NOT part of AgentShield's createDelegationSchema:
-     * - project_id is extracted from API key context by AgentShield middleware
+     * These fields are NOT part of Checkpoint's createDelegationSchema:
+     * - project_id is extracted from API key context by Checkpoint middleware
      * - session_id is not needed for delegation creation
      *
      * Including these fields will cause validation errors (400 Bad Request).
      */
     buildSimplifiedFormatRequest(request, userDid, expiresInDays, fieldName, credentialJwt) {
-        // Build request with ONLY fields that are in AgentShield's schema
+        // Build request with ONLY fields that are in Checkpoint's schema
         // Defensive check: ensure scopes is always defined (should be guaranteed by validation)
         const scopes = request.scopes ?? [];
         const simplifiedRequest = {
@@ -5420,12 +5494,12 @@ export class ConsentService {
         //
         // Fallback Strategy:
         // 1. If email available → user_identifier = email (preferred)
-        // 2. If no email → user_identifier = userDid (fallback so AgentShield has something to display)
-        // AgentShield will also check metadata.user_email for extraction
+        // 2. If no email → user_identifier = userDid (fallback so Checkpoint has something to display)
+        // Checkpoint will also check metadata.user_email for extraction
         if (userDid) {
             // user_did is the primary identifier - the actual DID
             simplifiedRequest.user_did = userDid;
-            // user_identifier: Human-readable identifier (email/username) for AgentShield dashboard display
+            // user_identifier: Human-readable identifier (email/username) for Checkpoint dashboard display
             // user_id: Provider's internal ID (e.g., customer ID 696395) for business reference
             // user_did: Cryptographic DID for identity verification
             if (request.credential_user_email) {
@@ -5434,7 +5508,7 @@ export class ConsentService {
             }
             else {
                 // No email - fall back to DID so dashboard has something to display
-                // AgentShield will detect this is a DID and may display differently
+                // Checkpoint will detect this is a DID and may display differently
                 simplifiedRequest.user_identifier = userDid;
             }
             // user_id is the provider's internal ID (separate from email)
@@ -5465,7 +5539,7 @@ export class ConsentService {
             simplifiedRequest.credential_jwt = credentialJwt;
             logger.debug("[ConsentService] Including credential_jwt in delegation request");
         }
-        // AgentShield API only accepts "custom_fields", not "metadata"
+        // Checkpoint API only accepts "custom_fields", not "metadata"
         // Always use "custom_fields" regardless of Day0 config
         // Include provider_type and provider for dashboard authorization display
         //
@@ -5480,7 +5554,7 @@ export class ConsentService {
         const provider = customFieldsFromRequest.provider;
         const hasProviderInfo = providerType || provider;
         // MCP-I Compatibility: Include user_email and user_id in custom_fields (becomes metadata)
-        // AgentShield extracts these from metadata when user_identifier is a DID or not provided
+        // Checkpoint extracts these from metadata when user_identifier is a DID or not provided
         // This ensures human-readable identifiers are always available for dashboard display
         //
         // user_email = human-readable email (for display)
@@ -5490,8 +5564,8 @@ export class ConsentService {
             .credential_provider_user_id || null;
         if (userDid || hasProviderInfo || userEmail) {
             // Include issuer_did and subject_did in custom_fields when we have userDid
-            // Also include provider_type and provider for AgentShield dashboard
-            // CRITICAL: AgentShield derives authorization from metadata.provider_type:
+            // Also include provider_type and provider for Checkpoint dashboard
+            // CRITICAL: Checkpoint derives authorization from metadata.provider_type:
             // - provider_type === 'password' → authorization.type = 'password' (credential auth)
             // - provider_type === 'none' → authorization.type = 'none' (consent-only)
             // - oauth_provider present → authorization.type = 'oauth'
@@ -5504,10 +5578,10 @@ export class ConsentService {
                     }
                     : {}),
                 format_version: "simplified_v1",
-                // Include provider_type at the custom_fields level (where AgentShield reads it)
+                // Include provider_type at the custom_fields level (where Checkpoint reads it)
                 ...(providerType ? { provider_type: providerType } : {}),
                 // MCP-I Compatibility: Include user_email and user_id in metadata
-                // AgentShield will extract these if user_identifier is not provided or is a DID
+                // Checkpoint will extract these if user_identifier is not provided or is a DID
                 // user_email = human-readable email (for display)
                 // user_id = provider's internal ID (for business reference, e.g., customer ID 696395)
                 ...(userEmail ? { user_email: userEmail } : {}),
@@ -5525,7 +5599,7 @@ export class ConsentService {
                 });
             }
             if (userEmail || providerUserId) {
-                logger.debug("[ConsentService] Including user info in custom_fields for AgentShield compatibility:", {
+                logger.debug("[ConsentService] Including user info in custom_fields for Checkpoint compatibility:", {
                     user_email: userEmail
                         ? userEmail.substring(0, 20) + "..."
                         : undefined,
@@ -5550,35 +5624,39 @@ export class ConsentService {
     /**
      * Try API call with error-based format detection
      */
-    async tryAPICall(agentShieldUrl, apiKey, request) {
+    async tryAPICall(checkpointUrl, apiKey, request) {
         // Handle format detection
         if (request._tryFormats && request.fullFormat && request.simplifiedFormat) {
             // Try full format first
-            const fullResponse = await this.makeAPICall(agentShieldUrl, apiKey, request.fullFormat);
-            if (fullResponse.success ||
-                fullResponse.error_code !== "validation_error") {
-                // Full format worked or failed for non-format reasons
+            const fullResponse = await this.makeAPICall(checkpointUrl, apiKey, request.fullFormat);
+            if (fullResponse.success) {
                 await this.cacheFormatPreference("full");
                 return fullResponse;
             }
+            // A failure that says nothing about the format (5xx, 401, network) is
+            // returned as is and never cached, so the next approval tries both
+            // formats again instead of skipping the simplified fallback for an hour.
+            if (fullResponse.error_code !== "validation_error") {
+                return fullResponse;
+            }
             // Full format failed with validation error, try simplified
             logger.debug("[ConsentService] Full format failed, trying simplified format...");
-            const simplifiedResponse = await this.makeAPICall(agentShieldUrl, apiKey, request.simplifiedFormat);
+            const simplifiedResponse = await this.makeAPICall(checkpointUrl, apiKey, request.simplifiedFormat);
             if (simplifiedResponse.success) {
                 await this.cacheFormatPreference("simplified");
             }
             return simplifiedResponse;
         }
         // Direct call (format already determined)
-        return this.makeAPICall(agentShieldUrl, apiKey, request);
+        return this.makeAPICall(checkpointUrl, apiKey, request);
     }
     /**
      * Make API call and parse response
      *
-     * CRITICAL: This method ensures session_id and project_id are never sent to AgentShield.
+     * CRITICAL: This method ensures session_id and project_id are never sent to Checkpoint.
      * These fields are NOT part of the createDelegationSchema and will cause validation errors.
      */
-    async makeAPICall(agentShieldUrl, apiKey, requestBody) {
+    async makeAPICall(checkpointUrl, apiKey, requestBody) {
         try {
             // FINAL SAFEGUARD: Remove session_id and project_id if they somehow got added
             // This provides defense-in-depth protection
@@ -5591,7 +5669,7 @@ export class ConsentService {
                 logger.warn("[ConsentService] ⚠️ project_id detected in request body - removing (not in schema)");
                 delete sanitizedBody.project_id;
             }
-            const response = await fetch(`${agentShieldUrl}${AGENTSHIELD_ENDPOINTS.DELEGATIONS_CREATE}`, {
+            const response = await fetch(`${checkpointUrl}${CHECKPOINT_ENDPOINTS.DELEGATIONS_CREATE}`, {
                 method: "POST",
                 headers: {
                     Authorization: `Bearer ${apiKey}`,