@foldrun/core 10.1.0 → 11.1.0

package/dist/src/untrusted-fetch.js

@@ -20,7 +20,8 @@
 // tier holding it all in memory is the platform's problem, not the tenant's.
 // Past the limit the body errors — a caller never gets the first megabyte
 // passed off as the whole answer.
-import { platform } from "./platform.js";
+import crypto from "node:crypto";
+import { platform, guardsUntrustedUrls } from "./platform.js";
 /** How many redirects one request may follow. fetch's own limit is 20;
  *  nothing a tenant points the platform at needs more than a couple. */
 export const MAX_REDIRECTS = 5;
@@ -80,6 +81,57 @@ export function capBody(res, maxBytes, url) {
     Object.defineProperty(out, "url", { value: res.url });
     return out;
 }
+/** One request with a client certificate, through node's https — a laptop's
+ *  fetch has no way to present one. Redirects are the caller's. */
+async function fetchWithClientCert(url, init, cert, maxBytes) {
+    const https = await import("node:https");
+    const body = init.body === undefined || init.body === null ? undefined : typeof init.body === "string" ? init.body : Buffer.from(await new Response(init.body).arrayBuffer());
+    const headers = {};
+    new Headers(init.headers).forEach((v, k) => (headers[k] = v));
+    // fetch decompresses; node's https does not. Ask for none, and decode one
+    // that comes anyway (Codex review).
+    headers["accept-encoding"] ??= "identity";
+    const zlib = await import("node:zlib");
+    const { pipeline } = await import("node:stream");
+    return new Promise((resolve, reject) => {
+        const r = https.request(url, { method: init.method ?? "GET", headers, cert: cert.cert, key: cert.key, ...(cert.passphrase ? { passphrase: cert.passphrase } : {}), ...(init.signal ? { signal: init.signal } : {}) }, (raw) => {
+            const enc = String(raw.headers["content-encoding"] ?? "").toLowerCase();
+            const decoder = enc === "gzip" || enc === "x-gzip" ? zlib.createGunzip()
+                : enc === "deflate" ? zlib.createInflate()
+                    : enc === "br" ? zlib.createBrotliDecompress()
+                        : null;
+            // pipeline: a reset mid-answer, or a bad compressed stream, rejects;
+            // and one side ending destroys the other (Codex review).
+            const res = decoder ? pipeline(raw, decoder, (err) => { if (err)
+                reject(err); }) : raw;
+            const chunks = [];
+            let size = 0;
+            res.on("data", (c) => {
+                // The read limit holds while reading, not after (Codex review).
+                size += c.length;
+                if (size > maxBytes) {
+                    res.destroy();
+                    raw.destroy();
+                    reject(new Error(`${url}: the answer is larger than ${maxBytes} bytes — not read`));
+                    return;
+                }
+                chunks.push(c);
+            });
+            res.on("end", () => {
+                const h = new Headers();
+                for (const [k, v] of Object.entries(raw.headers))
+                    if (v !== undefined && k !== "content-encoding" && k !== "content-length")
+                        h.set(k, Array.isArray(v) ? v.join(", ") : String(v));
+                resolve(new Response(chunks.length ? Buffer.concat(chunks) : null, { status: raw.statusCode ?? 502, headers: h }));
+            });
+            res.on("error", reject);
+        });
+        r.on("error", reject);
+        if (body !== undefined)
+            r.write(body);
+        r.end();
+    });
+}
 export class RedirectRefused extends Error {
     constructor(message) {
         super(message);
@@ -91,7 +143,15 @@ export async function fetchUntrusted(url, init = {}, opts = {}) {
     let current = url;
     let req = { ...init };
     for (let hop = 0;; hop++) {
-        const res = await platform.fetchUntrusted(current, { ...req, redirect: "manual" }, { maxBytes });
+        const res = opts.clientCert && !guardsUntrustedUrls()
+            // A laptop's plain fetch cannot present a certificate: node's https does.
+            ? await fetchWithClientCert(current, { ...req, redirect: "manual" }, opts.clientCert, maxBytes)
+            : await platform.fetchUntrusted(current, { ...req, redirect: "manual" }, {
+                maxBytes,
+                // A pool per certificate: a connection that presented one client's
+                // certificate is never reused for another's (Codex review).
+                ...(opts.clientCert ? (() => { const fp = crypto.createHash("sha256").update(`${opts.clientCert.cert}\n${opts.clientCert.key}`).digest("hex"); return { clientCert: { pool: `oauth-mtls:${fp}`, identity: fp, ...opts.clientCert } }; })() : {}),
+            });
         const location = REDIRECT.has(res.status) ? res.headers.get("location") : null;
         if (!location || opts.noRedirects)
             return capBody(res, maxBytes, current);
@@ -111,7 +171,8 @@ export async function fetchUntrusted(url, init = {}, opts = {}) {
         }
         const from = new URL(current);
         const crossOrigin = next.origin !== from.origin;
-        if (crossOrigin && opts.sameOrigin) {
+        // A client certificate is a credential too: never carried to another origin.
+        if (crossOrigin && (opts.sameOrigin || opts.clientCert)) {
             throw new RedirectRefused(`${from.origin} redirected to ${next.origin} — not followed: this request carries a credential, and it goes only where it was sent`);
         }
         // fetch's own rewrite: a 303, and a 301/302 answering a POST, is

package/index.ts

@@ -46,6 +46,7 @@ export * from "./src/oauth-token.ts";
 export * from "./src/oauth-discovery.ts";
 export * from "./src/oauth-assertion.ts";
 export * from "./src/oauth-device.ts";
+export * from "./src/oauth-dpop.ts";
 export * from "./src/secret-files.ts";
 export * from "./src/notify.ts";
 export * from "./src/webhook.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "10.1.0",
+  "version": "11.1.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/src/a2a-client.ts

@@ -200,6 +200,28 @@ export function routeFor(conn: Pick<A2AConnection, "token" | "egress">, target:
   return target;
 }
 
+/** Why the egress proxy refused a request, or null for an answer that is
+ *  the remote's. The diagnostic is fixed text of ours; the body's own words
+ *  go back as `said`, for the untrusted fence — the proxy passes a remote's
+ *  403 through as it came, so a remote can send this exact shape (Codex
+ *  review, 2 Nov 2026). */
+export function egressRefusal(status: number, text: string): { reason: string; said: string | null } | null {
+  if (status !== 403) return null;
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const err = (body as { error?: { type?: unknown; message?: unknown } } | null)?.error;
+  if (!err || err.type !== "egress") return null;
+  const said = typeof err.message === "string" ? short(err.message.replace(/^egress:\s*/, ""), 200) : "";
+  const reason = /private|internal/i.test(said)
+    ? "its address is not allowed — this platform does not call private or internal addresses"
+    : "the platform's egress refused it";
+  return { reason, said: said || null };
+}
+
 /**
  * One HTTP exchange, read as JSON, to a limit, with no redirect followed.
  *
@@ -251,6 +273,10 @@ async function exchange(
     }
     throw new A2AError(`${conn.remote}: the answer could not be read: ${short((err as Error)?.message ?? err, 200)}`);
   }
+  // The egress proxy's own refusal ({error: {type: "egress"}}) is ours, not
+  // the remote's: the address is not allowed, and no secret would change it.
+  const egress = egressRefusal(res.status, text);
+  if (egress) throw new A2AError(`${conn.remote} cannot be called from here: ${egress.reason}`, null, true, egress.said);
   if (res.status === 401 || res.status === 403) {
     throw new A2AError(`${conn.remote} refused the credential (HTTP ${res.status})${conn.token ? "" : " — this remote has no secret: set one"}`, null, true);
   }

package/src/oauth-capabilities.ts

@@ -119,15 +119,18 @@ export const OAUTH_CAPABILITIES: OAuthCapability[] = [
   },
   {
     id: "client.token-exchange", role: "client", title: "Token exchange", spec: "RFC 8693",
-    status: "planned", note: "Part I: a `token-exchange` secret kind. Cloud STS is covered today by the keyless identity kind.",
+    status: "supported", note: "A `token-exchange` secret: another secret's live token traded for a narrower one, cached. Cloud STS is covered by the keyless identity kind; a workload identity as the subject is not yet.",
+    proof: [core("tests/oauth-token-exchange.test.ts", "the subject's live token is traded for a narrower one"), platform(KC, "token exchange (RFC 8693)"), cli("tests/cli-connect.test.ts", "--kind token-exchange")],
   },
   {
     id: "client.dpop", role: "client", title: "DPoP sender-constrained tokens", spec: "RFC 9449",
-    status: "planned", note: "Part H: Bluesky/atproto, Okta DPoP.",
+    status: "supported", note: "`dpop: true` on the app (`--dpop`): each connection's own key; the egress proxy signs a proof for every call through a site binding; nonces honoured.",
+    proof: [core("tests/oauth-dpop-mtls.test.ts", "refresh with DPoP"), platform("tests/egress-dpop.test.ts", "a used DPoP connection gives its key"), platform(KC, "DPoP (RFC 9449): a connection made with DPoP gets a bound token"), cli("tests/cli-connect.test.ts", "connect --dpop")],
   },
   {
     id: "client.mtls", role: "client", title: "Mutual-TLS client auth and bound tokens", spec: "RFC 8705",
-    status: "planned", note: "Part H: the client-cert secret at the token endpoint.",
+    status: "supported", note: "`token_auth: tls_client_auth` with the certificate and key; presented to the token URL and, through the egress proxy, on the calls the token is bound to.",
+    proof: [core("tests/oauth-dpop-mtls.test.ts", "tls_client_auth (RFC 8705)"), platform("tests/egress-dpop.test.ts", "a certificate-authenticated connection gives its certificate"), platform(KC, "mutual TLS (RFC 8705)"), cli("tests/cli-connect.test.ts", "--token-auth mtls stores the certificate")],
   },
   {
     id: "client.ciba", role: "client", title: "Client-initiated backchannel authentication", spec: "OpenID CIBA",

package/src/oauth-dpop.ts

@@ -0,0 +1,93 @@
+// DPoP (RFC 9449): sender-constrained tokens. A connection made with DPoP
+// holds a key of its own; every request to the token endpoint, and every call
+// that uses the access token, carries a fresh proof signed with it — so a
+// token copied off the wire is useless without the key. Bluesky/atproto and
+// Okta's DPoP mode require it.
+//
+// The proof: header { typ: "dpop+jwt", alg, jwk: the public key }, claims
+// { jti, htm, htu (no query or fragment), iat, ath? (SHA-256 of the access
+// token, on resource calls), nonce? (when the server asked for one) }.
+//
+// Where the proofs are made: core's refresh and the platform's code exchange
+// (token requests), and the egress proxy (resource calls) — a DPoP-bound
+// connection is used through a site binding, where the proxy can sign each
+// request; the sandbox never holds the key.
+
+import crypto from "node:crypto";
+import { algForKey, readPrivateKey, ASSERTION_ALGS, type AssertionAlg, type Jwk } from "./oauth-assertion.ts";
+
+/** A new DPoP key for a connection (EC P-256, ES256): the private PEM. */
+export function generateDpopKey(): string {
+  return crypto.generateKeyPairSync("ec", { namedCurve: "P-256" }).privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+}
+
+/** The htu of a request: its URL with no query or fragment (RFC 9449 §4.2). */
+export function dpopHtu(url: string): string {
+  const u = new URL(url);
+  return `${u.origin}${u.pathname}`;
+}
+
+/** The ath of an access token: base64url of its SHA-256 (RFC 9449 §4.2). */
+export function dpopAth(accessToken: string): string {
+  return crypto.createHash("sha256").update(accessToken).digest("base64url");
+}
+
+const b64url = (s: string | Buffer) => Buffer.from(s).toString("base64url");
+
+/** A DPoP proof for one request. */
+export function dpopProof(key: string, req: { htm: string; htu: string; ath?: string; nonce?: string }, nowMs = Date.now()): string {
+  const k = readPrivateKey(key);
+  const alg: AssertionAlg = algForKey(k);
+  if (!(ASSERTION_ALGS as readonly string[]).includes(alg) || alg === "PS256") throw new Error("a DPoP key must be EC P-256/P-384, RSA or Ed25519");
+  const pub = crypto.createPublicKey(k).export({ format: "jwk" }) as Jwk;
+  const header = { typ: "dpop+jwt", alg, jwk: pub };
+  const claims = {
+    jti: b64url(crypto.randomBytes(18)),
+    htm: req.htm.toUpperCase(),
+    htu: dpopHtu(req.htu),
+    iat: Math.floor(nowMs / 1000),
+    ...(req.ath ? { ath: req.ath } : {}),
+    ...(req.nonce ? { nonce: req.nonce } : {}),
+  };
+  const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
+  const data = Buffer.from(input);
+  const sig =
+    alg === "ES256" ? crypto.sign("sha256", data, { key: k, dsaEncoding: "ieee-p1363" })
+    : alg === "ES384" ? crypto.sign("sha384", data, { key: k, dsaEncoding: "ieee-p1363" })
+    : alg === "EdDSA" ? crypto.sign(null, data, k)
+    : crypto.sign("sha256", data, k);
+  return `${input}.${b64url(sig)}`;
+}
+
+/** The JWK thumbprint the server binds a DPoP token to (cnf.jkt). */
+export function dpopJkt(key: string): string {
+  const pub = crypto.createPublicKey(readPrivateKey(key)).export({ format: "jwk" }) as Jwk;
+  const members = pub.kty === "EC" ? { crv: pub.crv, kty: pub.kty, x: pub.x, y: pub.y } : pub.kty === "RSA" ? { e: pub.e, kty: pub.kty, n: pub.n } : { crv: pub.crv, kty: pub.kty, x: pub.x };
+  return crypto.createHash("sha256").update(JSON.stringify(members)).digest("base64url");
+}
+
+// Server-provided nonces (RFC 9449 §8, §9), kept per origin and per DPoP
+// key: the last one a server sent to this connection is the one its next
+// proof carries — two connections to one server never overwrite each other's
+// (a server may issue nonces per client; Codex review).
+const nonces = new Map<string, string>();
+const nonceKey = (url: string, key: string) => `${new URL(url).origin} ${dpopJkt(key)}`;
+
+/** Remember a DPoP-Nonce a response to this connection carried. */
+export function noteDpopNonce(url: string, res: { headers: { get(name: string): string | null } }, key: string): void {
+  const n = res.headers.get("dpop-nonce");
+  if (n) nonces.set(nonceKey(url, key), n);
+}
+
+/** The nonce for this connection's next proof to this URL's server, if any. */
+export function dpopNonceFor(url: string, key: string): string | undefined {
+  return nonces.get(nonceKey(url, key));
+}
+
+/** Whether an answer asks for a (new) nonce: a token endpoint's 400
+ *  use_dpop_nonce, or a resource's 401 with it in WWW-Authenticate. */
+export function wantsDpopNonce(res: { status: number; headers: { get(name: string): string | null } }, body?: { error?: string }): boolean {
+  if (!res.headers.get("dpop-nonce")) return false;
+  if (res.status === 400 && body?.error === "use_dpop_nonce") return true;
+  return res.status === 401 && /use_dpop_nonce/.test(res.headers.get("www-authenticate") ?? "");
+}

package/src/oauth-token.ts

@@ -18,9 +18,10 @@
 //
 // Absent means the old behaviour: the body, with the secret if there is one.
 
+import crypto from "node:crypto";
 import { ASSERTION_TYPE, assertionKeyProblem, signClientAssertion, type AssertionAlg } from "./oauth-assertion.ts";
 
-export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"] as const;
+export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"] as const;
 export type TokenAuth = (typeof TOKEN_AUTH_METHODS)[number];
 
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
@@ -30,6 +31,8 @@ export function parseTokenAuth(value: string): TokenAuth | null {
   if (v === "post" || v === "body") return "client_secret_post";
   if (v === "basic") return "client_secret_basic";
   if (v === "jwt" || v === "private-key-jwt" || v === "key") return "private_key_jwt";
+  if (v === "mtls" || v === "tls" || v === "cert") return "tls_client_auth";
+  if (v === "self-signed-mtls" || v === "self-signed") return "self_signed_tls_client_auth";
   return null;
 }
 
@@ -43,10 +46,15 @@ export interface TokenClient {
   client_assertion_kid?: string;
   client_assertion_alg?: AssertionAlg;
   client_assertion_cert?: string;
+  /** tls_client_auth / self_signed_tls_client_auth (RFC 8705): the client
+   *  certificate and key presented on the connection to the token URL. */
+  tls_client_cert?: string;
+  tls_client_key?: string;
+  tls_client_passphrase?: string;
 }
 
 /** Why a client's token_auth cannot work, or null. */
-export function tokenAuthProblem(client: { client_secret?: string; token_auth?: unknown; client_assertion_key?: string; client_assertion_alg?: unknown; client_assertion_cert?: string }): string | null {
+export function tokenAuthProblem(client: { client_secret?: string; token_auth?: unknown; client_assertion_key?: string; client_assertion_alg?: unknown; client_assertion_cert?: string; tls_client_cert?: string; tls_client_key?: string; tls_client_passphrase?: string }): string | null {
   const auth = client.token_auth;
   if (auth === undefined) return null;
   if (typeof auth !== "string" || !(TOKEN_AUTH_METHODS as readonly string[]).includes(auth)) {
@@ -61,6 +69,16 @@ export function tokenAuthProblem(client: { client_secret?: string; token_auth?:
     if (hasSecret) return "token_auth private_key_jwt signs with a key and sends no client_secret — leave the secret empty";
     return assertionKeyProblem(client);
   }
+  if (auth === "tls_client_auth" || auth === "self_signed_tls_client_auth") {
+    if (hasSecret) return `token_auth ${auth} proves the client with its certificate and sends no client_secret — leave the secret empty`;
+    if (!client.tls_client_cert?.trim() || !client.tls_client_key?.trim()) return `token_auth ${auth} needs tls_client_cert and tls_client_key (PEM)`;
+    try {
+      const key = crypto.createPrivateKey(client.tls_client_passphrase ? { key: client.tls_client_key, passphrase: client.tls_client_passphrase } : client.tls_client_key);
+      if (!new crypto.X509Certificate(client.tls_client_cert).checkPrivateKey(key)) return "tls_client_cert is not the certificate of tls_client_key";
+    } catch {
+      return "tls_client_cert and tls_client_key must be a PEM certificate and its private key";
+    }
+  }
   return null;
 }
 
@@ -102,6 +120,10 @@ export function oauthTokenRequest(
     const pair = `${formEncode(client.client_id)}:${formEncode(client.client_secret!)}`;
     headers.authorization = `Basic ${Buffer.from(pair, "utf8").toString("base64")}`;
     if (opts.clientIdInBody) form.set("client_id", client.client_id);
+  } else if (auth === "tls_client_auth" || auth === "self_signed_tls_client_auth") {
+    // The certificate on the connection is the proof (RFC 8705 §2): the
+    // caller presents tls_client_cert; the body names the client only.
+    form.set("client_id", client.client_id);
   } else if (auth === "private_key_jwt") {
     if (!opts.audience) throw new Error("a private_key_jwt request needs the endpoint it goes to (its assertion's aud)");
     form.set("client_id", client.client_id);

package/src/platform.ts

@@ -185,7 +185,7 @@ export interface PlatformHooks {
    * `maxBytes` is the most the answer may be, read (untrusted-fetch.ts
    * caps it again, so a laptop's plain fetch may ignore it).
    */
-  fetchUntrusted(url: string, init?: RequestInit, opts?: { maxBytes?: number }): Promise<Response>;
+  fetchUntrusted(url: string, init?: RequestInit, opts?: { maxBytes?: number; clientCert?: { pool: string; identity: string; cert: string; key: string; passphrase?: string } }): Promise<Response>;
   /**
    * May the host call this URL a tenant chose — a provider's base_url,
    * before an eval's judge or a dashboard draft talks to it? A reason it may

package/src/runner.ts

@@ -2407,7 +2407,10 @@ async function runStep(
     const cardProblems = new Map<string, string>();
     for (const r of remotes) {
       const why = await platform.checkUntrustedUrl(r.card);
-      if (why) cardProblems.set(r.name, why);
+      if (why) {
+        cardProblems.set(r.name, why);
+        console.warn(`[a2a] remotes: ${r.name} refused for ${tenant}/${path.basename(workspaceRootOf(agentDir))} (${step.agent}): ${why}`);
+      }
     }
     const stepRemotes: RemoteSpec[] = remotes.map((r) => {
       const refused = cardProblems.get(r.name);

package/src/secrets.ts

@@ -27,6 +27,7 @@ import { fetchUntrusted } from "./untrusted-fetch.ts";
 import { oauthTokenRequest, readTokenResponse, tokenAuthProblem, type TokenAuth } from "./oauth-token.ts";
 import { isSecureUrl } from "./oauth-discovery.ts";
 import type { AssertionAlg } from "./oauth-assertion.ts";
+import { dpopProof, dpopNonceFor, noteDpopNonce } from "./oauth-dpop.ts";
 
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
@@ -45,7 +46,7 @@ const tenantKey = (tenant: string) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.ts";
 import { trimSlashes } from "./paths.ts";
-import { SITE } from "./network.ts";
+import { SITE, siteCovers } from "./network.ts";
 
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 
@@ -97,7 +98,7 @@ function secretsFile(tenant: string, workspace?: string) {
 /** How the stored value is used at run time — "oauth2"/"service-account"
  *  are refreshed into live tokens, "file"/"ssh"/"api" are materialised into
  *  the run's scratch. Plain values have no kind. */
-export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity";
+export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity" | "token-exchange";
 
 interface StoredSecret {
   iv: string;
@@ -953,6 +954,15 @@ export interface OAuth2Config {
   client_assertion_kid?: string;
   client_assertion_alg?: AssertionAlg;
   client_assertion_cert?: string;
+  /** DPoP (RFC 9449): this connection's own key; token requests and the
+   *  calls that use its token carry proofs signed with it (oauth-dpop.ts). */
+  dpop_key?: string;
+  /** tls_client_auth (RFC 8705): the client certificate and key presented
+   *  to the token URL — and, through the egress proxy, on the calls its
+   *  certificate-bound token is used for. */
+  tls_client_cert?: string;
+  tls_client_key?: string;
+  tls_client_passphrase?: string;
 }
 
 const OAUTH2_PREFIX = "@oauth2 ";
@@ -978,8 +988,9 @@ export function setOAuth2Secret(
   }
   // A public client (PKCE, no secret) refreshes with its client id alone;
   // client credentials are nothing without the secret.
-  if (config.grant_type === "client_credentials" && !config.client_secret?.trim() && config.token_auth !== "private_key_jwt") {
-    throw new Error("oauth2 secret needs client_secret for client_credentials (or token_auth private_key_jwt with a key)");
+  // Client credentials need a proof of the client: a secret, a signing key or a certificate.
+  if (config.grant_type === "client_credentials" && !config.client_secret?.trim() && !["private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"].includes(config.token_auth ?? "")) {
+    throw new Error("oauth2 secret needs client_secret for client_credentials (or token_auth private_key_jwt with a key, or tls_client_auth with a certificate)");
   }
   if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
     throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
@@ -1016,7 +1027,7 @@ const inFlight = new Map<string, Promise<string>>();
  * second account with the same names be handed the first one's token
  * (Codex debate, 22 Oct 2026).
  */
-export function tokenCacheKey(kind: "oauth2" | "sa", storedValue: string, tenant?: string): string {
+export function tokenCacheKey(kind: "oauth2" | "sa" | "tx", storedValue: string, tenant?: string): string {
   return crypto.createHash("sha256").update(JSON.stringify([kind, tenant ?? "", storedValue])).digest("hex");
 }
 
@@ -1091,27 +1102,51 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<OAuthLi
     // and the reconnect mail; a 5xx or 429 is the provider busy, retried.
     let res: Response | undefined;
     let lastNetwork: unknown;
+    let text = "";
+    // A certificate-authenticated client (RFC 8705) presents it on the connection.
+    const clientCert = config.tls_client_cert && config.tls_client_key
+      ? { cert: config.tls_client_cert, key: config.tls_client_key, ...(config.tls_client_passphrase ? { passphrase: config.tls_client_passphrase } : {}) }
+      : undefined;
+    let nonceRetried = false;
     for (let attempt = 0; attempt < OAUTH_REFRESH_TRIES; attempt++) {
       if (attempt) await new Promise((r) => setTimeout(r, oauthRetryDelayMs(attempt)));
       try {
         const request = build();
+        // DPoP: a fresh proof per try, with the server's nonce when it gave one.
+        const headers = config.dpop_key
+          ? { ...request.headers, dpop: dpopProof(config.dpop_key, { htm: "POST", htu: config.token_url, ...(dpopNonceFor(config.token_url, config.dpop_key) ? { nonce: dpopNonceFor(config.token_url, config.dpop_key) } : {}) }) }
+          : request.headers;
         res = await fetchUntrusted(config.token_url, {
           method: "POST",
-          headers: request.headers,
+          headers,
           body: request.body,
           signal: AbortSignal.timeout(15_000),
-        }, { sameOrigin: true });
+          // A DPoP proof names this URL and method: a redirect would carry it
+          // somewhere it is not for, so none is followed (Codex review).
+        }, { sameOrigin: true, ...(clientCert ? { clientCert } : {}), ...(config.dpop_key ? { noRedirects: true } : {}) });
       } catch (err) {
         lastNetwork = err;
         res = undefined;
         continue;
       }
+      // Read before deciding to retry: the last answer's own words are the
+      // error a person sees when every try is busy (Codex review).
+      text = await res.text().catch(() => "");
       if (res.status === 429 || res.status >= 500) continue;
+      if (config.dpop_key) {
+        noteDpopNonce(config.token_url, res, config.dpop_key);
+        // The server wants a nonce in the proof (RFC 9449 §8): once more, at once.
+        if (!nonceRetried && res.status === 400 && res.headers.get("dpop-nonce") && readTokenResponse(text, res.headers.get("content-type") ?? "").error === "use_dpop_nonce") {
+          nonceRetried = true;
+          attempt--;
+          continue;
+        }
+      }
       break;
     }
     if (!res) throw lastNetwork instanceof Error ? lastNetwork : new Error(String(lastNetwork));
     // JSON or form-encoded, Slack's nested user token, expires_in as a string.
-    const payload = readTokenResponse(await res.text().catch(() => ""), res.headers.get("content-type") ?? "");
+    const payload = readTokenResponse(text, res.headers.get("content-type") ?? "");
     if (!res.ok || !payload.access_token) {
       throw new Error(
         `token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`,
@@ -1234,7 +1269,9 @@ export async function revokeOAuth2Value(
   }
   // No redirect is followed: a 3xx is not ok, so a revocation endpoint that
   // sends us to a login page is reported, never counted as revoked.
-  const fetcher: RevokeFetcher = opts.fetcher ?? ((url, init) => fetchUntrusted(url, init, { sameOrigin: true, noRedirects: true }));
+  // A certificate-authenticated client (RFC 8705) presents it here too.
+  const clientCert = config.tls_client_cert && config.tls_client_key ? { cert: config.tls_client_cert, key: config.tls_client_key, ...(config.tls_client_passphrase ? { passphrase: config.tls_client_passphrase } : {}) } : undefined;
+  const fetcher: RevokeFetcher = opts.fetcher ?? ((url, init) => fetchUntrusted(url, init, { sameOrigin: true, noRedirects: true, ...(clientCert ? { clientCert } : {}) }));
   const key = tokenCacheKey("oauth2", value, opts.tenant);
   const access = oauthCache.get(key)?.token;
   const tokens: ["refresh_token" | "access_token", string][] = [];
@@ -1319,6 +1356,8 @@ export async function materializeSecrets(
         throw new Error(`secret ${name}: ${message}${link ? ` — reconnect it in one click: ${link}` : ""}`);
       }
       if (ctx) await platform.noteOAuthRefresh(ctx, name, null).catch(() => undefined);
+    } else if (value.startsWith(TOKEN_EXCHANGE_PREFIX)) {
+      out[name] = await materializeTokenExchange(name, value, env, ctx);
     } else if (value.startsWith(SERVICE_ACCOUNT_PREFIX)) {
       let config: ServiceAccountConfig;
       try {
@@ -1624,6 +1663,136 @@ export interface IdentityConfig {
   audience: string;
 }
 
+// ---------------------------------------------------------------- token exchange
+
+// Token exchange (RFC 8693): a secret that is not a credential of its own but
+// a recipe for one — present another secret's token (the subject) at a token
+// endpoint and get back a narrower one: another audience, fewer scopes, a
+// token a downstream service accepts. Cached like an oauth2 token; the
+// subject is made live first, the same way it would be on its own.
+
+export const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
+const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+const TOKEN_EXCHANGE_PREFIX = "@token-exchange ";
+
+export interface TokenExchangeConfig {
+  token_url: string;
+  client_id: string;
+  client_secret?: string;
+  token_auth?: TokenAuth;
+  client_assertion_key?: string;
+  client_assertion_kid?: string;
+  client_assertion_alg?: AssertionAlg;
+  client_assertion_cert?: string;
+  tls_client_cert?: string;
+  tls_client_key?: string;
+  tls_client_passphrase?: string;
+  /** The secret whose live token is the subject: an oauth2 or service-account
+   *  secret, or a static token. Declared beside this one, or found in the
+   *  vault at the same scope. */
+  subject_secret: string;
+  /** Default urn:ietf:params:oauth:token-type:access_token. */
+  subject_token_type?: string;
+  requested_token_type?: string;
+  audience?: string;
+  resource?: string;
+  scope?: string;
+}
+
+export function setTokenExchangeSecret(tenant: string, name: string, config: TokenExchangeConfig, workspace?: string, limit: SecretLimit = {}) {
+  for (const field of ["token_url", "client_id", "subject_secret"] as const) {
+    if (typeof config[field] !== "string" || !config[field].trim()) throw new Error(`a token-exchange secret needs ${field}`);
+  }
+  if (!SECRET_NAME.test(config.subject_secret)) throw new Error("subject_secret is a secret's name, UPPER_SNAKE_CASE");
+  if (config.subject_secret === name) throw new Error("a token exchange cannot be its own subject");
+  if (!isSecureUrl(config.token_url)) throw new Error("token_url must be https");
+  for (const k of ["subject_token_type", "requested_token_type", "audience", "resource", "scope"] as const) {
+    if (config[k] !== undefined && typeof config[k] !== "string") throw new Error(`${k} is a string`);
+  }
+  const authProblem = tokenAuthProblem(config);
+  if (authProblem) throw new Error(`token-exchange secret: ${authProblem}`);
+  setSecret(tenant, name, TOKEN_EXCHANGE_PREFIX + JSON.stringify(config), workspace, "token-exchange", limit);
+}
+
+export function isTokenExchangeValue(value: string): boolean {
+  return value.startsWith(TOKEN_EXCHANGE_PREFIX);
+}
+
+const txCache = new Map<string, { token: string; expiresAt: number }>();
+const txFlight = new Map<string, Promise<string>>();
+
+async function materializeTokenExchange(
+  name: string,
+  value: string,
+  env: Record<string, string>,
+  ctx?: { tenant: string; workspace?: string },
+): Promise<string> {
+  let config: TokenExchangeConfig;
+  try {
+    config = JSON.parse(value.slice(TOKEN_EXCHANGE_PREFIX.length));
+  } catch {
+    throw new Error(`secret ${name}: stored token-exchange config is unreadable`);
+  }
+  // The subject: declared beside this secret, else the vault at this scope.
+  const subjectName = config.subject_secret;
+  let subjectValue: string | undefined = env[subjectName];
+  if (subjectValue === undefined && ctx) subjectValue = getSecret(ctx.tenant, subjectName, ctx.workspace)?.value;
+  if (subjectValue === undefined) throw new Error(`secret ${name}: its subject ${subjectName} is not set — declare it in secrets: beside ${name}`);
+  if (isTokenExchangeValue(subjectValue)) throw new Error(`secret ${name}: its subject ${subjectName} is itself a token exchange — the subject must be a token`);
+  // Only a token may be sent as the subject: a file, ssh key, header set,
+  // certificate or identity recipe would hand its contents to the token
+  // endpoint (Codex review).
+  for (const p of [FILE_PREFIX, SSH_PREFIX, API_PREFIX, CLIENT_CERT_PREFIX, IDENTITY_PREFIX]) {
+    if (subjectValue.startsWith(p)) throw new Error(`secret ${name}: its subject ${subjectName} is a ${p.slice(1).trim()} secret — the subject must be a token (an oauth2, service-account or plain token secret)`);
+  }
+  // A subject bound to sites goes to those sites alone: an exchange whose
+  // token URL is not one of them would carry it elsewhere (Codex review).
+  if (ctx) {
+    const bound = secretSites(ctx.tenant, [subjectName], ctx.workspace)[subjectName] ?? [];
+    const host = new URL(config.token_url).host;
+    if (bound.length && !bound.some((site) => siteCovers(site, host))) {
+      throw new Error(`secret ${name}: its subject ${subjectName} is bound to ${bound.join(", ")} — the exchange's token URL (${host}) is not one of them; bind the subject to it too`);
+    }
+  }
+  const subjectToken = (await materializeSecrets({ [subjectName]: subjectValue }, ctx))[subjectName];
+  // Cached by the recipe and the subject token: a new subject is a new exchange.
+  const key = tokenCacheKey("tx", `${value}\n${crypto.createHash("sha256").update(subjectToken).digest("hex")}`, ctx?.tenant);
+  const hit = txCache.get(key);
+  if (hit && hit.expiresAt > Date.now()) return hit.token;
+  const pending = txFlight.get(key);
+  if (pending) return pending;
+  const flight = (async () => {
+    const clientCert = config.tls_client_cert && config.tls_client_key ? { cert: config.tls_client_cert, key: config.tls_client_key, ...(config.tls_client_passphrase ? { passphrase: config.tls_client_passphrase } : {}) } : undefined;
+    const request = oauthTokenRequest(config, {
+      grant_type: TOKEN_EXCHANGE_GRANT,
+      subject_token: subjectToken,
+      subject_token_type: config.subject_token_type ?? ACCESS_TOKEN_TYPE,
+      ...(config.requested_token_type ? { requested_token_type: config.requested_token_type } : {}),
+      ...(config.audience ? { audience: config.audience } : {}),
+      ...(config.resource ? { resource: config.resource } : {}),
+      ...(config.scope ? { scope: config.scope } : {}),
+    }, { audience: config.token_url });
+    const res = await fetchUntrusted(config.token_url, { method: "POST", headers: request.headers, body: request.body, signal: AbortSignal.timeout(15_000) }, { sameOrigin: true, ...(clientCert ? { clientCert } : {}) });
+    const payload = readTokenResponse(await res.text().catch(() => ""), res.headers.get("content-type") ?? "");
+    if (!res.ok || !payload.access_token) {
+      throw new Error(`secret ${name}: the token exchange was refused (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
+    }
+    // Never cached past its life: a minute short of it, or half a short life.
+    const life = payload.expires_in ?? 3600;
+    const ttl = Math.max(0, life - Math.min(60, life / 2)) * 1000;
+    const now = Date.now();
+    for (const [k, v] of txCache) if (v.expiresAt <= now) txCache.delete(k);
+    txCache.set(key, { token: payload.access_token, expiresAt: now + ttl });
+    return payload.access_token;
+  })();
+  txFlight.set(key, flight);
+  try {
+    return await flight;
+  } finally {
+    txFlight.delete(key);
+  }
+}
+
 export function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string, limit: SecretLimit = {}) {
   const audience = typeof config.audience === "string" ? config.audience.trim() : "";
   if (!audience) throw new Error("an identity needs an audience — the value your cloud's trust expects in aud");