@foldrun/core 10.1.0 → 11.1.0

package/dist/index.d.ts

@@ -34,6 +34,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/dist/index.js

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

package/dist/src/a2a-client.d.ts

@@ -112,6 +112,15 @@ export declare function stripHidden(text: string): {
 /** The address a request to `target` goes to: the egress door when the
  *  token is a placeholder only the proxy can fill, else the target. */
 export declare function routeFor(conn: Pick<A2AConnection, "token" | "egress">, target: string): string;
+/** 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 declare function egressRefusal(status: number, text: string): {
+    reason: string;
+    said: string | null;
+} | null;
 /**
  * The endpoint a card names, if it names one we may call: a JSON-RPC
  * interface of protocol 1.x at the card's own origin. Pure — the card in,

package/dist/src/a2a-client.js

@@ -129,6 +129,30 @@ export function routeFor(conn, 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, text) {
+    if (status !== 403)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const err = body?.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.
  *
@@ -178,6 +202,11 @@ async function exchange(conn, target, init, maxBytes) {
         }
         throw new A2AError(`${conn.remote}: the answer could not be read: ${short(err?.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/dist/src/oauth-capabilities.js

@@ -93,15 +93,18 @@ export const OAUTH_CAPABILITIES = [
     },
     {
         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/dist/src/oauth-dpop.d.ts

@@ -0,0 +1,33 @@
+/** A new DPoP key for a connection (EC P-256, ES256): the private PEM. */
+export declare function generateDpopKey(): string;
+/** The htu of a request: its URL with no query or fragment (RFC 9449 §4.2). */
+export declare function dpopHtu(url: string): string;
+/** The ath of an access token: base64url of its SHA-256 (RFC 9449 §4.2). */
+export declare function dpopAth(accessToken: string): string;
+/** A DPoP proof for one request. */
+export declare function dpopProof(key: string, req: {
+    htm: string;
+    htu: string;
+    ath?: string;
+    nonce?: string;
+}, nowMs?: number): string;
+/** The JWK thumbprint the server binds a DPoP token to (cnf.jkt). */
+export declare function dpopJkt(key: string): string;
+/** Remember a DPoP-Nonce a response to this connection carried. */
+export declare function noteDpopNonce(url: string, res: {
+    headers: {
+        get(name: string): string | null;
+    };
+}, key: string): void;
+/** The nonce for this connection's next proof to this URL's server, if any. */
+export declare function dpopNonceFor(url: string, key: string): string | undefined;
+/** 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 declare function wantsDpopNonce(res: {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}, body?: {
+    error?: string;
+}): boolean;

package/dist/src/oauth-dpop.js

@@ -0,0 +1,85 @@
+// 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 } from "./oauth-assertion.js";
+/** A new DPoP key for a connection (EC P-256, ES256): the private PEM. */
+export function generateDpopKey() {
+    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) {
+    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) {
+    return crypto.createHash("sha256").update(accessToken).digest("base64url");
+}
+const b64url = (s) => Buffer.from(s).toString("base64url");
+/** A DPoP proof for one request. */
+export function dpopProof(key, req, nowMs = Date.now()) {
+    const k = readPrivateKey(key);
+    const alg = algForKey(k);
+    if (!ASSERTION_ALGS.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" });
+    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) {
+    const pub = crypto.createPublicKey(readPrivateKey(key)).export({ format: "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();
+const nonceKey = (url, key) => `${new URL(url).origin} ${dpopJkt(key)}`;
+/** Remember a DPoP-Nonce a response to this connection carried. */
+export function noteDpopNonce(url, res, key) {
+    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, key) {
+    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, body) {
+    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/dist/src/oauth-token.d.ts

@@ -1,5 +1,5 @@
 import { type AssertionAlg } from "./oauth-assertion.ts";
-export declare const TOKEN_AUTH_METHODS: readonly ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"];
+export declare const TOKEN_AUTH_METHODS: readonly ["client_secret_post", "client_secret_basic", "none", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"];
 export type TokenAuth = (typeof TOKEN_AUTH_METHODS)[number];
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
 export declare function parseTokenAuth(value: string): TokenAuth | null;
@@ -13,6 +13,11 @@ 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 declare function tokenAuthProblem(client: {
@@ -21,6 +26,9 @@ export declare function tokenAuthProblem(client: {
     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;
 /**
  * The headers and body of one token request. `params` is the grant's own

package/dist/src/oauth-token.js

@@ -17,8 +17,9 @@
 //                        secret at all (RFC 7523 §2.2, oauth-assertion.ts)
 //
 // Absent means the old behaviour: the body, with the secret if there is one.
+import crypto from "node:crypto";
 import { ASSERTION_TYPE, assertionKeyProblem, signClientAssertion } from "./oauth-assertion.js";
-export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"];
+export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"];
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
 export function parseTokenAuth(value) {
     const v = value.trim().toLowerCase();
@@ -30,6 +31,10 @@ export function parseTokenAuth(value) {
         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;
 }
 /** Why a client's token_auth cannot work, or null. */
@@ -53,6 +58,20 @@ export function tokenAuthProblem(client) {
             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;
 }
 /** The form-urlencoding RFC 6749 Appendix B asks for: space as '+'. */
@@ -93,6 +112,11 @@ opts = {}) {
         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)");

package/dist/src/platform.d.ts

@@ -183,6 +183,13 @@ export interface PlatformHooks {
      */
     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,

package/dist/src/runner.js

@@ -2211,8 +2211,10 @@ mayDefer) {
         const cardProblems = new Map();
         for (const r of remotes) {
             const why = await platform.checkUntrustedUrl(r.card);
-            if (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 = remotes.map((r) => {
             const refused = cardProblems.get(r.name);

package/dist/src/secrets.d.ts

@@ -17,7 +17,7 @@ export declare function installKeyMaterial(): 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;
     tag: string;
@@ -256,6 +256,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;
 }
 /** Tries at a token endpoint before a refresh is called failed: the first,
  *  and two more after a short wait, for a network error, a 5xx or a 429. */
@@ -273,7 +282,7 @@ export declare function isOAuth2Value(value: string): boolean;
  * second account with the same names be handed the first one's token
  * (Codex debate, 22 Oct 2026).
  */
-export declare function tokenCacheKey(kind: "oauth2" | "sa", storedValue: string, tenant?: string): string;
+export declare function tokenCacheKey(kind: "oauth2" | "sa" | "tx", storedValue: string, tenant?: string): string;
 /**
  * A provider that rotates refresh tokens (RFC 9700 §2.2.2) answered a refresh
  * with a new one: write it back where the old one is stored — the workspace
@@ -417,6 +426,32 @@ export declare function setClientCertSecret(tenant: string, name: string, config
 export interface IdentityConfig {
     audience: string;
 }
+export declare const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type: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 declare function setTokenExchangeSecret(tenant: string, name: string, config: TokenExchangeConfig, workspace?: string, limit?: SecretLimit): void;
+export declare function isTokenExchangeValue(value: string): boolean;
 export declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isIdentityValue(value: string): boolean;
 export declare function identityOf(value: string): IdentityConfig;

package/dist/src/secrets.js

@@ -25,6 +25,7 @@ import { platform } from "./platform.js";
 import { fetchUntrusted } from "./untrusted-fetch.js";
 import { oauthTokenRequest, readTokenResponse, tokenAuthProblem } from "./oauth-token.js";
 import { isSecureUrl } from "./oauth-discovery.js";
+import { dpopProof, dpopNonceFor, noteDpopNonce } from "./oauth-dpop.js";
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
  * `authTagLength`, Node accepts whatever length `setAuthTag` is handed — 4, 8,
@@ -41,7 +42,7 @@ const tenantKey = (tenant) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.js";
 import { trimSlashes } from "./paths.js";
-import { SITE } from "./network.js";
+import { SITE, siteCovers } from "./network.js";
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 /**
  * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
@@ -817,8 +818,9 @@ export function setOAuth2Secret(tenant, name, config, workspace, limit = {}) {
     }
     // 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)");
@@ -923,31 +925,55 @@ async function exchange(config, cacheKey) {
         // and the reconnect mail; a 5xx or 429 is the provider busy, retried.
         let res;
         let lastNetwork;
+        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"}`);
         }
@@ -1055,7 +1081,9 @@ export async function revokeOAuth2Value(value, opts = {}) {
     }
     // 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 = 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 = 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 = [];
@@ -1144,6 +1172,9 @@ ctx) {
             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;
             try {
@@ -1383,6 +1414,116 @@ export function setClientCertSecret(tenant, name, config, workspace, limit = {})
     });
 }
 const IDENTITY_PREFIX = "@identity ";
+// ---------------------------------------------------------------- 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 function setTokenExchangeSecret(tenant, name, config, workspace, limit = {}) {
+    for (const field of ["token_url", "client_id", "subject_secret"]) {
+        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"]) {
+        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) {
+    return value.startsWith(TOKEN_EXCHANGE_PREFIX);
+}
+const txCache = new Map();
+const txFlight = new Map();
+async function materializeTokenExchange(name, value, env, ctx) {
+    let config;
+    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 = 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, name, config, workspace, limit = {}) {
     const audience = typeof config.audience === "string" ? config.audience.trim() : "";
     if (!audience)

package/dist/src/untrusted-fetch.d.ts

@@ -28,4 +28,10 @@ export declare function fetchUntrusted(url: string, init?: RequestInit, opts?: {
      *  caller to treat as the failure it is (a revocation that redirects to
      *  a login page did not revoke anything). */
     noRedirects?: boolean;
+    /** Present this client certificate (mutual TLS, RFC 8705). */
+    clientCert?: {
+        cert: string;
+        key: string;
+        passphrase?: string;
+    };
 }): Promise<Response>;