@kya-os/mcp-i-cloudflare 1.13.2 → 1.13.3

package/dist/services/consent.service.js

@@ -16,7 +16,7 @@ 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 { createUnsignedVCJWT, completeVCJWT, parseVCJWT, generateDidKeyFromBase64, createDelegationVerifier, createDidKeyResolver, logger, base64urlEncodeFromBytes, base64urlDecodeToBytes, bytesToBase64, wrapDelegationAsVC, } from "@kya-os/mcp";
-import { fetchRemoteConfig, } from "@kya-os/mcp-i-runtime"; // product-layer symbols stay on OLD (C2 #2918)
+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";
@@ -146,7 +146,7 @@ export class ConsentService {
      * @returns true if DO storage succeeded (strongly consistent), false if fell back to KV only
      */
     async storeDelegationForOAuth(params, serverOrigin) {
-        return this.storeDelegationToken(params.sessionId, params.agentDid, params.delegationToken, params.delegationId, params.userDid, serverOrigin);
+        return this.storeDelegationToken(params.sessionId, params.agentDid, params.delegationToken, params.delegationId, params.userDid, serverOrigin, params.authorizationType);
     }
     /**
      * Initialize audit service - fetches config from remote API
@@ -2130,6 +2130,10 @@ export class ConsentService {
                     headers: {
                         "Content-Type": "text/html; charset=utf-8",
                         "Cache-Control": "no-cache, no-store, must-revalidate",
+                        // SECURITY (A2, spec §3.1): the identity assertion is delivered to
+                        // this page in the URL fragment; `no-referrer` guarantees the token
+                        // (and any query state) never leaks to a third party via `Referer`.
+                        "Referrer-Policy": "no-referrer",
                     },
                 });
             }
@@ -2140,6 +2144,10 @@ export class ConsentService {
                 headers: {
                     "Content-Type": "text/html; charset=utf-8",
                     "Cache-Control": "no-cache, no-store, must-revalidate",
+                    // SECURITY (A2, spec §3.1): the identity assertion is delivered to
+                    // this page in the URL fragment; `no-referrer` guarantees the token
+                    // (and any query state) never leaks to a third party via `Referer`.
+                    "Referrer-Policy": "no-referrer",
                 },
             });
         }
@@ -3241,6 +3249,23 @@ export class ConsentService {
         const normalized = String(raw).trim().toLowerCase();
         return normalized !== "false" && normalized !== "0";
     }
+    /**
+     * 403 returned by `handleApproval` when a credential/OAuth clickwrap mint is
+     * attempted without a valid, grant-bound identity assertion (A3, spec §3.2).
+     * A distinct `error_code` from the plain `identity_required` gate so callers
+     * and tests can tell "no server-signed proof of authentication" apart from
+     * "no identity resolved at all".
+     */
+    identityAssertionRequiredResponse() {
+        return new Response(JSON.stringify({
+            success: false,
+            error: "A valid identity assertion is required to approve this request",
+            error_code: "identity_assertion_required",
+        }), {
+            status: 403,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
     /**
      * Handle consent approval
      *
@@ -3266,6 +3291,16 @@ export class ConsentService {
             // - 'none': Consent-only mode (clickwrap) - user agrees without authentication
             const bodyObj = body;
             const providerType = bodyObj?.provider_type;
+            // SECURITY (A3, spec §3.1/§3.2, defect #2): the identity a delegation is
+            // minted under is authoritative ONLY from a trusted source resolved below
+            // — a server-signed identity assertion (credential/OAuth clickwrap) or the
+            // server-generated ephemeral / session-stored DID (pure consent-only).
+            // A caller-supplied `user_did` body field is NEVER an identity source.
+            // This holds the trusted value; it overwrites `bodyObj.user_did`
+            // unconditionally before validation so no downstream consumer can read a
+            // forged one. `undefined` for the plain authenticated (non-clickwrap)
+            // shapes, which fall back to server-side session resolution.
+            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,
@@ -3304,18 +3339,36 @@ export class ConsentService {
                             provider_type: CONSENT_PROVIDER_TYPES.PASSWORD,
                         };
                     }
-                    // CRITICAL FIX: Read userDid from URL params passed through redirect
-                    // This bypasses KV eventual consistency issues - we don't need to read
-                    // from KV because userDid was passed directly in the redirect URL
-                    const userDidFromRedirect = bodyObj.user_did;
-                    if (userDidFromRedirect) {
-                        logger.debug("[ConsentService] ✅ Using userDid from redirect (bypassing KV):", {
-                            sessionId: sessionId?.substring(0, 20) + "...",
-                            userDid: userDidFromRedirect.substring(0, 30) + "...",
-                            source: "redirect-param",
-                        });
-                        // Ensure userDid is in bodyObj for createDelegation and storeDelegationToken
-                        bodyObj.user_did = userDidFromRedirect;
+                    // SECURITY (A3, spec §3.2): the userDid for a post-credential
+                    // clickwrap mint comes ONLY from the server-signed identity assertion
+                    // minted by handleCredentialApproval after it authenticated against
+                    // the provider — bound to this sid AND grant (agent/tool/scopes/
+                    // project). The bare `user_did` redirect param that used to be trusted
+                    // here is gone: it was caller-forgeable (subject/issuer forgery). A
+                    // missing/invalid/expired/mismatched assertion → 403, no mint.
+                    if (this.isDevConsentTestMode()) {
+                        // Dev/test escape hatch (BOTH MCPI_TEST_CONSENT and a development
+                        // env), mirroring consent-anchor-bridge's call-site CSRF relaxation:
+                        // no signed assertion is required, so local/miniflare runs work
+                        // without OAUTH_ENCRYPTION_SECRET. Never on prod/staging/unset.
+                        trustedUserDid = bodyObj.user_did;
+                    }
+                    else {
+                        const assertion = bodyObj.identity_assertion;
+                        const verifiedUserDid = typeof assertion === "string"
+                            ? await this.verifyIdentityAssertion(assertion, {
+                                sid: sessionId,
+                                agentDid: bodyObj.agent_did ?? "",
+                                tool: bodyObj.tool ?? "",
+                                scopes: this.parseScopes(bodyObj.scopes),
+                                projectId: bodyObj.project_id ?? "",
+                            })
+                            : null;
+                        if (!verifiedUserDid) {
+                            logger.warn("[ConsentService] Post-credential clickwrap has no valid identity assertion — refusing to mint");
+                            return this.identityAssertionRequiredResponse();
+                        }
+                        trustedUserDid = verifiedUserDid;
                     }
                     // Read user info from redirect URL params
                     // Field mapping (clear naming):
@@ -3341,7 +3394,7 @@ export class ConsentService {
                         sessionId: sessionId?.substring(0, 20) + "...",
                         providerType: CONSENT_PROVIDER_TYPES.PASSWORD,
                         provider: credentialProvider,
-                        hasUserDid: !!userDidFromRedirect,
+                        hasUserDid: !!trustedUserDid,
                         hasCredentialUserEmail: !!credentialUserEmailFromRedirect,
                         hasProviderUserId: !!credentialProviderUserIdFromRedirect,
                         note: "Delegation will have authorization.type='password' to match tool protection",
@@ -3370,12 +3423,46 @@ export class ConsentService {
                         provider: oauthProvider || bodyObj.provider,
                         note: "Delegation will have authorization.type='oauth' to match tool protection",
                     });
+                    // SECURITY (A3, spec §3.2): as with the credential clickwrap, the
+                    // userDid for a post-OAuth clickwrap mint comes ONLY from the
+                    // server-signed identity assertion minted by the OAuth callback
+                    // (oauth-handler.ts) after it linked the OAuth identity to the user
+                    // DID — bound to this sid AND grant. No valid assertion → 403, no
+                    // mint. The bare `user_did` redirect param is no longer trusted here.
+                    if (this.isDevConsentTestMode()) {
+                        trustedUserDid = bodyObj.user_did;
+                    }
+                    else {
+                        const assertion = bodyObj.identity_assertion;
+                        const verifiedUserDid = typeof assertion === "string"
+                            ? await this.verifyIdentityAssertion(assertion, {
+                                sid: sessionId,
+                                agentDid: bodyObj.agent_did ?? "",
+                                tool: bodyObj.tool ?? "",
+                                scopes: this.parseScopes(bodyObj.scopes),
+                                projectId: bodyObj.project_id ?? "",
+                            })
+                            : null;
+                        if (!verifiedUserDid) {
+                            logger.warn("[ConsentService] Post-OAuth clickwrap has no valid identity assertion — refusing to mint");
+                            return this.identityAssertionRequiredResponse();
+                        }
+                        trustedUserDid = verifiedUserDid;
+                    }
                 }
                 // If neither credential nor OAuth, this is pure consent-only
                 if (!(credentialProviderType === CONSENT_PROVIDER_TYPES.PASSWORD ||
                     oauthProviderType === "oauth")) {
                     // Pure consent-only mode - no prior authentication
                     logger.debug("[ConsentService] Consent-only mode detected (pure clickwrap)");
+                    // SECURITY (A3, spec §3.2, review #5): a pure consent-only mint is
+                    // intentionally anonymous/ephemeral — it never had a victim identity
+                    // to attribute. Any caller-supplied `user_did` is forgeable and must
+                    // NEVER survive. Discard it up-front, before the ephemeral/session DID
+                    // is (maybe) resolved below, so no sub-path — including the
+                    // DELEGATION_STORAGE-unbound `else` fallback that used to leave the
+                    // body value intact — can carry a forged DID into the mint.
+                    trustedUserDid = undefined;
                     if (sessionId && this.env.DELEGATION_STORAGE) {
                         // Check if session already has userDid (from credential auth or OAuth)
                         let existingUserDid;
@@ -3393,7 +3480,9 @@ export class ConsentService {
                                 sessionId: sessionId.substring(0, 20) + "...",
                                 userDid: existingUserDid.substring(0, 30) + "...",
                             });
-                            bodyObj.user_did = existingUserDid;
+                            // Server-side session identity (set by a prior auth step), not a
+                            // caller-supplied body value — safe to trust.
+                            trustedUserDid = existingUserDid;
                         }
                         else {
                             // Generate ephemeral userDid for pure consent-only
@@ -3404,8 +3493,9 @@ export class ConsentService {
                                 // This ensures storeDelegationToken can find it and use PRIORITY 1 key
                                 await this.updateSessionWithIdentity(sessionId, ephemeralUserDid, null // No OAuth identity for consent-only
                                 );
-                                // Also inject the user_did into the request body so createDelegation receives it
-                                bodyObj.user_did = ephemeralUserDid;
+                                // Server-generated ephemeral DID (not a caller-supplied value)
+                                // — safe to trust as the anonymous consent-only subject.
+                                trustedUserDid = ephemeralUserDid;
                                 logger.debug("[ConsentService] ✅ Ephemeral userDid stored in session for consent-only flow:", {
                                     sessionId: sessionId.substring(0, 20) + "...",
                                     userDid: ephemeralUserDid.substring(0, 30) + "...",
@@ -3422,6 +3512,16 @@ export class ConsentService {
                     }
                 }
             }
+            // SECURITY (A3, spec §3.2, defect #2 :4419/:4477): overwrite the forgeable
+            // `user_did` body field with the trusted value resolved above — a signed
+            // assertion, or the server-generated ephemeral / session DID — for EVERY
+            // shape, unconditionally. For the plain authenticated (non-clickwrap)
+            // shapes `trustedUserDid` is undefined, which wipes any caller-supplied
+            // `user_did` so it can never be an identity source; those shapes then fall
+            // back to server-side session resolution below. This is the single choke
+            // point that guarantees no downstream consumer (validation,
+            // createDelegation, storeDelegationToken) ever reads a caller-forged DID.
+            bodyObj.user_did = trustedUserDid;
             // Convert null oauth_identity to undefined for proper schema validation
             // Zod's .nullish() should handle null, but converting to undefined is more explicit
             // and avoids potential edge cases with FormData parsing
@@ -3553,11 +3653,21 @@ export class ConsentService {
                 delegationId: delegationResult.delegation_id?.substring(0, 20) + "...",
             });
             // Store delegation token to DO (strongly consistent) and KV (backward compat)
-            // Pass user_did directly if available (from redirect params) to bypass KV consistency issues
+            // SECURITY (A3, defect #2 :4477): pass the trusted `resolvedUserDid`
+            // (assertion / ephemeral / session-resolved), NOT the raw body
+            // `approvalRequest.user_did`, so the stored delegation key is never scoped
+            // to a caller-forged DID. `resolvedUserDid` is a superset of the body
+            // value (which is already neutralised above) plus server-side resolution.
             const serverOrigin = new URL(request.url).origin;
-            await this.storeDelegationToken(approvalRequest.session_id, approvalRequest.agent_did, delegationResult.delegation_token, delegationResult.delegation_id, approvalRequest.user_did, // Pass userDid directly to bypass KV read
-            serverOrigin // Pass origin for DO URL construction
-            );
+            await this.storeDelegationToken(approvalRequest.session_id, approvalRequest.agent_did, delegationResult.delegation_token, delegationResult.delegation_id, resolvedUserDid, // trusted identity only (see above)
+            serverOrigin, // Pass origin for DO URL construction
+            // Task B2: the EFFECTIVE provider_type is the delegation's auth type.
+            // On this ('none') branch it is one of 'none' | 'password' | 'oauth'
+            // (the post-credential / post-OAuth clickwrap branches rewrote it to
+            // match the tool's authorization.type; 'credential'/'password' form
+            // submissions were routed to handleCredentialApproval earlier), so it
+            // maps cleanly through normalizeAuthType — no 'credential' mis-fold here.
+            effectiveProviderType);
             // ✅ After successful delegation creation - log audit events
             if (auditService && delegationResult.success) {
                 try {
@@ -3925,9 +4035,17 @@ export class ConsentService {
      * @param delegationId - Delegation ID
      * @param providedUserDid - Optional userDid passed directly (bypasses KV read for consistency)
      * @param serverOrigin - Server origin for DO URL construction
+     * @param authorizationType - The delegation's authorization type as recorded
+     *   at mint (raw provider_type / authorization.type). Normalized here before
+     *   persisting so the call-time enforcement gate (Task B2/B3) reads a
+     *   consistent value ("password" | "oauth2" | "none" | …). Undefined → the
+     *   field is omitted and the gate fails safe (never satisfies a typed tool).
      */
-    async storeDelegationToken(sessionId, agentDid, token, delegationId, providedUserDid, serverOrigin) {
+    async storeDelegationToken(sessionId, agentDid, token, delegationId, providedUserDid, serverOrigin, authorizationType) {
         const delegationStorage = this.env.DELEGATION_STORAGE;
+        // Task B2: normalize once (folds deprecated aliases: oauth→oauth2) so every
+        // stored record and every read compares in the same vocabulary.
+        const normalizedAuthorizationType = normalizeAuthType(authorizationType);
         // Resolve userDid if not provided
         let userDid = providedUserDid;
         if (!userDid && delegationStorage) {
@@ -3943,7 +4061,14 @@ export class ConsentService {
         // PRIMARY: Store to Durable Object (strongly consistent)
         // This eliminates eventual consistency issues with KV
         const origin = serverOrigin || this.env.MCP_SERVER_URL || "https://localhost";
-        const storedViaDO = await this.storeDelegationViaDO({ sessionId, delegationToken: token, delegationId, userDid, agentDid }, origin);
+        const storedViaDO = await this.storeDelegationViaDO({
+            sessionId,
+            delegationToken: token,
+            delegationId,
+            userDid,
+            agentDid,
+            authorizationType: normalizedAuthorizationType,
+        }, origin);
         // ALSO store to KV for backward compatibility and cross-session persistence
         if (delegationStorage) {
             try {
@@ -3965,6 +4090,10 @@ export class ConsentService {
                     agentDid,
                     delegationToken: token,
                     delegationId,
+                    // Task B2: mirror the auth type into the KV session record too, so
+                    // the two store paths (DO + KV) stay consistent. The DO record is
+                    // the one the enforcement gate reads; this is for parity/debugging.
+                    authorizationType: normalizedAuthorizationType,
                     cachedAt: Date.now(),
                 }), { expirationTtl: ttl });
                 logger.debug("[ConsentService] Token also stored to KV (session key)");
@@ -4110,7 +4239,14 @@ export class ConsentService {
         // tool handler runs server-side through the MCP tools/call proxy, so
         // CSRF is not applicable.
         const isInlineMode = body.inline_mode === true;
-        if (!isInlineMode) {
+        // SECURITY (A4, spec §3.3): the ONLY sanctioned CSRF relaxation is the
+        // dev/test escape hatch — BOTH MCPI_TEST_CONSENT and a development env —
+        // applied here at the call site (mirroring consent-anchor-bridge's
+        // `isTestConsentMode` gate on `validateCsrfToken`), never inside the
+        // validator/minter, which are strictly fail-closed. Production, staging,
+        // and unset always enforce CSRF.
+        const skipCsrf = isInlineMode || this.isDevConsentTestMode();
+        if (!skipCsrf) {
             // Validate CSRF token
             if (!csrf_token || typeof csrf_token !== "string") {
                 logger.warn("[ConsentService] Missing or invalid CSRF token");
@@ -4304,7 +4440,12 @@ export class ConsentService {
                 }
                 // Store delegation token (DO + KV)
                 const serverUrl = this.env.MCP_SERVER_URL || new URL(request.url).origin;
-                await this.storeDelegationToken(session_id, agent_did, delegationResult.delegation_token, delegationResult.delegation_id, identityResult.userDid, serverUrl);
+                await this.storeDelegationToken(session_id, agent_did, delegationResult.delegation_token, delegationResult.delegation_id, identityResult.userDid, serverUrl, 
+                // Task B2: the inline path is the credential (password) auth flow —
+                // it authenticated against the provider and minted with
+                // provider_type=PASSWORD (see approvalBody above), so the delegation's
+                // authorization type is "password".
+                CONSENT_PROVIDER_TYPES.PASSWORD);
                 logger.info("[ConsentService] ✅ Inline credential auth + delegation complete", {
                     delegationId: delegationResult.delegation_id?.substring(0, 20) + "...",
                 });
@@ -4387,17 +4528,49 @@ export class ConsentService {
                 // Provider's internal ID (e.g., customer ID 696395) for business reference
                 clickwrapUrl.searchParams.set("credential_provider_user_id", authResult.userId);
             }
-            // CRITICAL FIX: Pass userDid through redirect to avoid KV eventual consistency issues
-            // Without this, the clickwrap approval might read stale session data from KV
-            // that doesn't yet have the userDid from updateSessionWithIdentity above.
-            // By passing userDid in the URL, we ensure the delegation is stored with the
-            // correct user+agent scoped key regardless of KV propagation timing.
-            clickwrapUrl.searchParams.set("user_did", identityResult.userDid);
+            // SECURITY (A2, spec §3.1): carry the authenticated identity to the
+            // clickwrap as a server-signed, grant-bound `identity_assertion` instead
+            // of the bare, caller-forgeable `user_did` query param that used to live
+            // here. The assertion binds {sid, userDid, provider, agentDid, tool,
+            // scopesHash, projectId}; handleApproval re-verifies it before minting, so
+            // the delegation's subject can no longer be forged and the KV-race the old
+            // param dodged is still dodged (the identity travels in the signed token).
+            //
+            // Delivery: the token goes in the URL *fragment* (`#identity_assertion=…`),
+            // never the query string, so it stays out of access logs, `Referer`, and
+            // browser history. The consent page's client script reads the fragment and
+            // posts it back (see the @kya-os/consent component). The consent render
+            // Response also sets `Referrer-Policy: no-referrer` as defence in depth.
+            if (this.isDevConsentTestMode()) {
+                // Dev/test escape hatch (BOTH MCPI_TEST_CONSENT and a development env):
+                // no signed assertion is minted, so local/miniflare runs work without
+                // OAUTH_ENCRYPTION_SECRET. Mirrors consent-anchor-bridge's call-site
+                // relaxation. Never reached on production/staging/unset deployments.
+                clickwrapUrl.searchParams.set("user_did", identityResult.userDid);
+            }
+            else {
+                // Fail-closed: mintIdentityAssertion throws if OAUTH_ENCRYPTION_SECRET
+                // is unset, surfacing as a 500 rather than a silent unsigned fallback.
+                const identityAssertion = await this.mintIdentityAssertion({
+                    sid: session_id,
+                    userDid: identityResult.userDid,
+                    provider: provider,
+                    agentDid: agent_did,
+                    tool: tool,
+                    scopes,
+                    projectId: project_id,
+                });
+                clickwrapUrl.hash = `identity_assertion=${identityAssertion}`;
+            }
             logger.debug("[ConsentService] ✅ Credential auth complete, redirecting to clickwrap", {
                 sessionId: session_id.substring(0, 20) + "...",
                 userDid: identityResult.userDid.substring(0, 30) + "...",
                 provider: provider,
-                clickwrapUrl: clickwrapUrl.toString().substring(0, 100) + "...",
+                // Never log clickwrapUrl.toString()/.href here: the URL's fragment
+                // carries the signed identity_assertion (see clickwrapUrl.hash
+                // above), and query params carry other session identifiers. Log
+                // only the origin + pathname.
+                clickwrapUrl: clickwrapUrl.origin + clickwrapUrl.pathname,
             });
             // Return success with redirect to clickwrap page
             return new Response(JSON.stringify({
@@ -4701,9 +4874,15 @@ export class ConsentService {
     async validateCredentialCsrfToken(token, sessionId) {
         const secret = this.env.OAUTH_ENCRYPTION_SECRET;
         if (!secret) {
-            logger.warn("[ConsentService] No OAUTH_ENCRYPTION_SECRET for CSRF validation, skipping");
-            // Return true to allow flow to continue (graceful degradation)
-            return true;
+            // SECURITY (A4, spec §3.3, defect #4): fail CLOSED. The old code returned
+            // `true` here ("graceful degradation"), silently disabling CSRF on a
+            // state-changing endpoint whenever the secret was unset — the exact
+            // fail-open this PR removes. Matches consent-anchor-bridge's
+            // `validateCsrfToken`. The single allowed relaxation is the dev/test
+            // escape hatch applied at the CALL SITE (see `handleCredentialApproval`),
+            // never here in the validator.
+            logger.warn("[ConsentService] No OAUTH_ENCRYPTION_SECRET for CSRF validation — rejecting (fail-closed)");
+            return false;
         }
         try {
             const dotIndex = token.indexOf(".");
@@ -4747,10 +4926,19 @@ export class ConsentService {
     async storeCredentialCsrfToken(sessionId) {
         const secret = this.env.OAUTH_ENCRYPTION_SECRET;
         if (!secret) {
-            logger.warn("[ConsentService] No OAUTH_ENCRYPTION_SECRET for CSRF generation");
-            // Fallback: random token (won't validate but allows graceful degradation)
-            const tokenBytes = crypto.getRandomValues(new Uint8Array(32));
-            return this.base64UrlEncode(tokenBytes);
+            // SECURITY (A4, spec §3.3, defect #4): do NOT mint a random,
+            // never-validating token when the secret is unset. The old fallback
+            // handed the form a token that `validateCredentialCsrfToken` (now
+            // fail-closed) can never accept — pure theatre that paired with the old
+            // validate fail-OPEN to silently disable CSRF. Fail closed instead: only
+            // the dev/test escape hatch may render a form without a real secret, in
+            // which case the call-site skips CSRF entirely so a placeholder is safe.
+            if (this.isDevConsentTestMode()) {
+                logger.warn("[ConsentService] No OAUTH_ENCRYPTION_SECRET; issuing a dev/test placeholder CSRF token (CSRF is skipped at the call site in dev mode)");
+                const tokenBytes = crypto.getRandomValues(new Uint8Array(32));
+                return this.base64UrlEncode(tokenBytes);
+            }
+            throw new Error("[ConsentService] OAUTH_ENCRYPTION_SECRET is unset; refusing to mint a CSRF token (fail-closed)");
         }
         // 10 minute expiration (matches previous KV TTL)
         const exp = Math.floor(Date.now() / 1000) + 600;
@@ -4807,6 +4995,202 @@ export class ConsentService {
         }
         return result === 0;
     }
+    /**
+     * Whether local/miniflare testing may relax consent security checks.
+     *
+     * Mirrors `consent-anchor-bridge.ts`'s `isTestConsentMode` verbatim: requires
+     * BOTH `MCPI_TEST_CONSENT === "true"` AND an explicit `development`
+     * environment. The flag alone must NEVER relax a check on a
+     * production/staging/unset deployment.
+     *
+     * NOT used by `mintIdentityAssertion`/`verifyIdentityAssertion` — those are
+     * strictly fail-closed with no dev relaxation of any kind (a review found
+     * that signing/verifying under an attacker-known empty key when this flag
+     * is active was a latent total-forgery bypass if the two dev flags ever
+     * co-occurred in production). If a dev bypass for the identity-assertion
+     * requirement is ever needed, it belongs at the CALL SITE (mirroring how
+     * the anchor bridge bypasses CSRF via this flag at the handler, before
+     * `validateCsrfToken` is even invoked — never inside the crypto itself).
+     * Public so the OAuth callback path (runtime/oauth-handler.ts) can gate its
+     * own redirect mint on the identical dev/test relaxation used by the
+     * credential redirect above, rather than re-deriving the two-flag check.
+     */
+    isDevConsentTestMode() {
+        if (this.env.MCPI_TEST_CONSENT !== "true") {
+            return false;
+        }
+        const environment = (this.env.ENVIRONMENT ??
+            this.env.MCPI_ENV ??
+            "").toLowerCase();
+        return environment === "development";
+    }
+    /**
+     * SHA-256 hex digest of the given scopes, sorted ascending and
+     * JSON-array-encoded. Used as the identity assertion's `scopesHash` so the
+     * signed grant binds to the scope *set* regardless of the order scopes
+     * arrive in the request body. Mirrors the digest-to-hex shape already used
+     * elsewhere in this codebase (e.g. `DelegationService.hashToken`).
+     *
+     * `JSON.stringify` (not a `\n`-joined string) is required for injectivity:
+     * a plain join collides distinct scope sets that share the same joined
+     * bytes — e.g. `["a\nb"]` and `["a", "b"]` both join to `"a\nb"`. JSON
+     * array encoding preserves each element's boundary (quoting + `,`
+     * separators), so distinct scope sets can never hash identically.
+     */
+    async hashScopes(scopes) {
+        const canonical = JSON.stringify([...scopes].sort());
+        const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+        return Array.from(new Uint8Array(digest))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+    /**
+     * Compute HMAC-SHA256 for identity-assertion generation/validation.
+     *
+     * Structurally identical to `computeCsrfHmac`, but `computeCsrfHmac`
+     * hardcodes the `csrf:` key prefix internally so it cannot be reused for a
+     * different domain — this mirrors its shape with an `identity:` prefix
+     * instead, so a CSRF token and an identity assertion are signed under
+     * disjoint keys and can never validate as one another.
+     */
+    async computeIdentityHmac(secret, data) {
+        const encoder = new TextEncoder();
+        const keyMaterial = encoder.encode(`identity:${secret}`);
+        const key = await crypto.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        return crypto.subtle.sign("HMAC", key, encoder.encode(data));
+    }
+    /**
+     * Mint a grant-bound, domain-separated HMAC identity assertion.
+     *
+     * Carries the `userDid` resolved by a completed authentication step
+     * (credential or OAuth) across the consent redirect, replacing the
+     * caller-forgeable `user_did` body field (see
+     * docs/superpowers/specs/2026-07-29-consent-approve-auth-gate-design.md
+     * §3.1). Format mirrors `storeCredentialCsrfToken`:
+     * `${hmacB64url}.${payloadB64url}`.
+     *
+     * Binds the grant, not just the identity: `agentDid`, `tool`, `scopesHash`
+     * (SHA-256 of the sorted scope set), and `projectId` are signed in and must
+     * be re-checked against the request body at mint time by the caller — a
+     * leaked assertion must not be replayable to mint an arbitrary grant under
+     * the victim's `userDid` within the 10-minute window.
+     *
+     * FAIL-CLOSED, ALWAYS: throws if `OAUTH_ENCRYPTION_SECRET` is unset or
+     * empty. There is deliberately NO dev/test relaxation inside this helper —
+     * signing under a predictable key (e.g. an empty-string fallback) would be
+     * an attacker-known key and a latent total-forgery bypass if a dev flag
+     * were ever misconfigured in production. A mint must never silently
+     * produce an unsigned/unverifiable token — unlike
+     * `storeCredentialCsrfToken`'s legacy "graceful degradation," which this
+     * assertion deliberately does not inherit. Any future dev/test bypass
+     * belongs at the call site (see `isDevConsentTestMode`'s docstring).
+     *
+     * Public so both authenticated redirect sites can mint under this service's
+     * `identity:`-keyed secret: the credential redirect (in-class) and the OAuth
+     * callback redirect (runtime/oauth-handler.ts, a separate module).
+     */
+    async mintIdentityAssertion(params) {
+        const secret = this.env.OAUTH_ENCRYPTION_SECRET;
+        if (!secret) {
+            throw new Error("[ConsentService] OAUTH_ENCRYPTION_SECRET is unset; refusing to mint an identity assertion (fail-closed)");
+        }
+        const exp = Math.floor(Date.now() / 1000) + 600;
+        const scopesHash = await this.hashScopes(params.scopes);
+        const payload = JSON.stringify({
+            v: 1,
+            sid: params.sid,
+            userDid: params.userDid,
+            provider: params.provider,
+            agentDid: params.agentDid,
+            tool: params.tool,
+            scopesHash,
+            projectId: params.projectId,
+            exp,
+        });
+        const payloadB64 = this.base64UrlEncodeString(payload);
+        const hmac = await this.computeIdentityHmac(secret, payloadB64);
+        const hmacB64 = this.base64UrlEncode(new Uint8Array(hmac));
+        return `${hmacB64}.${payloadB64}`;
+    }
+    /**
+     * Verify a grant-bound identity assertion minted by `mintIdentityAssertion`.
+     *
+     * Returns the payload's `userDid` iff: the HMAC matches (constant-time),
+     * the assertion has not expired, and every bound field (`sid`, `agentDid`,
+     * `tool`, `projectId`, and `scopesHash` recomputed from `expected.scopes`)
+     * equals the caller-supplied `expected` values. Any mismatch, tamper, or
+     * expiry returns `null` — never throws, so callers can treat `null`
+     * uniformly as "no verified identity."
+     *
+     * FAIL-CLOSED, ALWAYS: returns `null` if `OAUTH_ENCRYPTION_SECRET` is unset
+     * or empty. There is deliberately NO dev/test relaxation inside this
+     * helper — mirrors `consent-anchor-bridge.ts`'s `validateCsrfToken`, NOT
+     * `validateCredentialCsrfToken`'s legacy "return true to allow flow to
+     * continue" behavior (the fail-open this PR closes). Any future dev/test
+     * bypass belongs at the call site (see `isDevConsentTestMode`'s
+     * docstring), never as a predictable/empty signing key inside this helper.
+     */
+    async verifyIdentityAssertion(token, expected) {
+        const secret = this.env.OAUTH_ENCRYPTION_SECRET;
+        if (!secret) {
+            logger.warn("[ConsentService] No OAUTH_ENCRYPTION_SECRET for identity-assertion verification; rejecting (fail-closed)");
+            return null;
+        }
+        try {
+            const dotIndex = token.indexOf(".");
+            if (dotIndex === -1) {
+                logger.warn("[ConsentService] Identity assertion missing separator");
+                return null;
+            }
+            const hmacB64 = token.substring(0, dotIndex);
+            const payloadB64 = token.substring(dotIndex + 1);
+            const payloadJson = this.base64UrlDecodeString(payloadB64);
+            const payload = JSON.parse(payloadJson);
+            if (payload.sid !== expected.sid) {
+                logger.warn("[ConsentService] Identity assertion sid mismatch");
+                return null;
+            }
+            if (payload.agentDid !== expected.agentDid) {
+                logger.warn("[ConsentService] Identity assertion agentDid mismatch");
+                return null;
+            }
+            if (payload.tool !== expected.tool) {
+                logger.warn("[ConsentService] Identity assertion tool mismatch");
+                return null;
+            }
+            if (payload.projectId !== expected.projectId) {
+                logger.warn("[ConsentService] Identity assertion projectId mismatch");
+                return null;
+            }
+            const expectedScopesHash = await this.hashScopes(expected.scopes);
+            if (payload.scopesHash !== expectedScopesHash) {
+                logger.warn("[ConsentService] Identity assertion scopes mismatch");
+                return null;
+            }
+            if (typeof payload.exp !== "number" ||
+                payload.exp < Math.floor(Date.now() / 1000)) {
+                logger.warn("[ConsentService] Identity assertion expired");
+                return null;
+            }
+            // Recompute HMAC and constant-time compare. Kept last so tampering with
+            // any bound field above is already caught by the field checks; this is
+            // the authoritative integrity check.
+            const expectedHmac = await this.computeIdentityHmac(secret, payloadB64);
+            const expectedB64 = this.base64UrlEncode(new Uint8Array(expectedHmac));
+            if (!this.constantTimeCompare(hmacB64, expectedB64)) {
+                logger.warn("[ConsentService] Identity assertion HMAC mismatch");
+                return null;
+            }
+            if (typeof payload.userDid !== "string" || !payload.userDid) {
+                return null;
+            }
+            return payload.userDid;
+        }
+        catch (error) {
+            logger.error("[ConsentService] Identity assertion verification error:", error);
+            return null;
+        }
+    }
     /**
      * Build full DelegationRecord format request (future format)
      */