@foldrun/core 10.0.0 → 11.0.0

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/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");

package/src/untrusted-fetch.ts

@@ -21,7 +21,8 @@
 // Past the limit the body errors — a caller never gets the first megabyte
 // passed off as the whole answer.
 
-import { platform } from "./platform.ts";
+import crypto from "node:crypto";
+import { platform, guardsUntrustedUrls } from "./platform.ts";
 
 /** 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. */
@@ -88,6 +89,54 @@ export function capBody(res: Response, maxBytes: number, url: string): Response
   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: string, init: RequestInit, cert: { cert: string; key: string; passphrase?: string }, maxBytes: number): Promise<Response> {
+  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 as BodyInit).arrayBuffer());
+  const headers: Record<string, string> = {};
+  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<Response>((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: Buffer[] = [];
+      let size = 0;
+      res.on("data", (c: Buffer) => {
+        // 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: string) {
     super(message);
@@ -108,13 +157,23 @@ export async function fetchUntrusted(
      *  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> {
   const maxBytes = opts.maxBytes ?? MAX_BYTES;
   let current = url;
   let req: RequestInit = { ...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);
     // The body of a redirect is never read; free the socket.
@@ -131,7 +190,8 @@ export async function fetchUntrusted(
     }
     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`,
       );