@foldrun/core 2.6.0 → 2.7.0

package/dist/src/secrets.js

@@ -200,6 +200,11 @@ export function setSecretSites(tenant, name, sites, workspace) {
         if (clean.length && (rec.kind === "file" || rec.kind === "ssh" || rec.kind === "api")) {
             throw new Error(`${name} is a ${rec.kind} secret, unpacked inside the sandbox — only a value sent in a request can be bound to sites`);
         }
+        // A client certificate is presented by the egress proxy to the exact
+        // hosts named — never to a whole domain on a wildcard.
+        if (rec.kind === "client-cert" && clean.some((s) => s.startsWith("*."))) {
+            throw new Error(`${name} is a client certificate — bind it to exact hosts, not a wildcard`);
+        }
         if (clean.length)
             rec.sites = clean;
         else
@@ -459,10 +464,15 @@ export function oauthRetryDelayMs(n) {
     return base * (n === 1 ? 1 : 3);
 }
 export function setOAuth2Secret(tenant, name, config, workspace) {
-    for (const field of ["token_url", "client_id", "client_secret"]) {
+    for (const field of ["token_url", "client_id"]) {
         if (!config[field]?.trim())
             throw new Error(`oauth2 secret needs ${field}`);
     }
+    // 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()) {
+        throw new Error("oauth2 secret needs client_secret for client_credentials");
+    }
     if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
         throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
     }
@@ -481,11 +491,62 @@ export function isOAuth2Value(value) {
 // steps must not hit Google twenty times in one second.
 const tokenCache = new Map();
 const inFlight = new Map();
+/**
+ * The cache key for a live token: SHA-256 over the kind, the account and the
+ * WHOLE stored config — credential material included (client secret, refresh
+ * token, private key, subject, scopes, token URL). A caller can only hit an
+ * entry it could have minted itself. Both maps are process-wide, so a key of
+ * names alone (`sa:${name}:${issuer}`, `${name}:${client_id}:…`) once let a
+ * second account with the same names be handed the first one's token
+ * (Codex debate, 22 Oct 2026).
+ */
+export function tokenCacheKey(kind, storedValue, tenant) {
+    return crypto.createHash("sha256").update(JSON.stringify([kind, tenant ?? "", storedValue])).digest("hex");
+}
+/**
+ * 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
+ * copy, else the account's — but only while that copy still holds the value
+ * this refresh used (compare-and-set), so two refreshes racing cannot put an
+ * older token over a newer one. Returns whether a copy was replaced.
+ */
+export function replaceOAuth2RefreshToken(tenant, name, workspace, usedValue, refreshToken) {
+    if (!isOAuth2Value(usedValue))
+        return false;
+    const config = JSON.parse(usedValue.slice(OAUTH2_PREFIX.length));
+    const next = OAUTH2_PREFIX + JSON.stringify({ ...config, refresh_token: refreshToken });
+    for (const scope of workspace ? [workspace, undefined] : [undefined]) {
+        let replaced = false;
+        mutateVaultFile(secretsFile(tenant, scope), (all) => {
+            const rec = all[name];
+            if (rec && decrypt(tenant, rec) === usedValue) {
+                all[name] = { ...rec, ...encryptValue(tenant, next), updatedAt: new Date().toISOString() };
+                replaced = true;
+            }
+            return all;
+        });
+        if (replaced)
+            return true;
+    }
+    return false;
+}
+const oauthCache = new Map();
+const oauthFlight = new Map();
+/** Cache an access token, sweeping expired entries as it goes: a rotating
+ *  provider changes the stored config — and so the key — on every refresh,
+ *  and expired entries would otherwise pile up for the life of the process. */
+function cacheOAuth(key, live) {
+    const now = Date.now();
+    for (const [k, v] of oauthCache)
+        if (v.expiresAt <= now)
+            oauthCache.delete(k);
+    oauthCache.set(key, live);
+}
 async function exchange(config, cacheKey) {
-    const cached = tokenCache.get(cacheKey);
+    const cached = oauthCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now())
-        return cached.token;
-    const pending = inFlight.get(cacheKey);
+        return cached;
+    const pending = oauthFlight.get(cacheKey);
     if (pending)
         return pending;
     const flight = (async () => {
@@ -493,7 +554,7 @@ async function exchange(config, cacheKey) {
             grant_type: config.grant_type ?? "refresh_token",
             ...(config.grant_type === "client_credentials" ? {} : { refresh_token: config.refresh_token }),
             client_id: config.client_id,
-            client_secret: config.client_secret,
+            ...(config.client_secret ? { client_secret: config.client_secret } : {}),
             ...(config.extra ?? {}),
         });
         // A network blip is retried; a provider's answer is not. "fetch failed"
@@ -530,15 +591,21 @@ async function exchange(config, cacheKey) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
         }
         const ttl = Math.max(60, (payload.expires_in ?? 3600) - 60) * 1000;
-        tokenCache.set(cacheKey, { token: payload.access_token, expiresAt: Date.now() + ttl });
-        return payload.access_token;
+        // A rotated refresh token replaces the old one, which the provider may
+        // now refuse; dropping it broke the next refresh for rotating providers.
+        const rotated = payload.refresh_token && config.grant_type !== "client_credentials" && payload.refresh_token !== config.refresh_token
+            ? payload.refresh_token
+            : undefined;
+        const live = { token: payload.access_token, expiresAt: Date.now() + ttl, ...(rotated ? { rotated } : {}) };
+        cacheOAuth(cacheKey, live);
+        return live;
     })();
-    inFlight.set(cacheKey, flight);
+    oauthFlight.set(cacheKey, flight);
     try {
         return await flight;
     }
     finally {
-        inFlight.delete(cacheKey);
+        oauthFlight.delete(cacheKey);
     }
 }
 /**
@@ -565,13 +632,23 @@ ctx) {
                 throw new Error(`secret ${name}: stored oauth2 config is unreadable`);
             }
             try {
-                // Fingerprint the WHOLE refresh token, not its first 8 chars: Google
-                // refresh tokens share a long common prefix, so an 8-char slice could
-                // collide two distinct grants onto one cache entry and hand one the
-                // other's access token. Hashed so the token is not held in a Map key.
-                const grantMaterial = config.refresh_token ?? config.grant_type ?? "";
-                const fp = crypto.createHash("sha256").update(grantMaterial).digest("hex").slice(0, 16);
-                out[name] = await exchange(config, `${name}:${config.client_id}:${fp}`);
+                const live = await exchange(config, tokenCacheKey("oauth2", value, ctx?.tenant));
+                out[name] = live.token;
+                if (live.rotated) {
+                    // This caller's copy takes the new refresh token (compare-and-set:
+                    // a copy already updated, or changed since, is left alone), and the
+                    // access token is cached under the config as it is now stored, so
+                    // the next run does not refresh again.
+                    const next = OAUTH2_PREFIX + JSON.stringify({ ...config, refresh_token: live.rotated });
+                    try {
+                        if (ctx)
+                            replaceOAuth2RefreshToken(ctx.tenant, name, ctx.workspace, value, live.rotated);
+                    }
+                    catch {
+                        // The access token is good either way; the next refresh says if not.
+                    }
+                    cacheOAuth(tokenCacheKey("oauth2", next, ctx?.tenant), { token: live.token, expiresAt: live.expiresAt });
+                }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -590,7 +667,7 @@ ctx) {
                 throw new Error(`secret ${name}: stored service account config is unreadable`);
             }
             try {
-                out[name] = await exchangeServiceAccount(config, `sa:${name}:${config.issuer}`);
+                out[name] = await exchangeServiceAccount(config, tokenCacheKey("sa", value, ctx?.tenant));
             }
             catch (err) {
                 throw new Error(`secret ${name}: ${err instanceof Error ? err.message : String(err)}`);
@@ -619,7 +696,14 @@ export function setServiceAccountSecret(tenant, name, config, workspace) {
     if (!/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM key (from the service account JSON)");
     }
-    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(config), workspace, "service-account");
+    if (config.subject !== undefined) {
+        if (typeof config.subject !== "string" || !config.subject.trim())
+            throw new Error("subject is the user to act as — leave it out to act as the account itself");
+        if (config.subject.length > 320 || /[\u0000-\u001f\u007f\s]/.test(config.subject.trim()))
+            throw new Error("subject is one identifier, no spaces or control characters");
+    }
+    const stored = { ...config, ...(config.subject !== undefined ? { subject: config.subject.trim() } : {}) };
+    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(stored), workspace, "service-account");
 }
 function base64url(input) {
     return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -636,7 +720,9 @@ async function exchangeServiceAccount(config, cacheKey) {
         const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
         const claim = base64url(JSON.stringify({
             iss: config.issuer,
-            sub: config.issuer,
+            // The subject is part of the stored config, so of the cache key: two
+            // subjects never share a token (tokenCacheKey).
+            sub: config.subject || config.issuer,
             scope: config.scope,
             aud: config.audience ?? config.token_url,
             iat: now,
@@ -737,8 +823,108 @@ export function sshConfigOf(value) {
 // wrapper with the headers baked in — `"$NAME" /v1/charges` — so the secret
 // never appears in the bash command at all.
 const API_PREFIX = "@api ";
+const CLIENT_CERT_PREFIX = "@client-cert ";
+export function setClientCertSecret(tenant, name, config, workspace) {
+    if (!/-----BEGIN CERTIFICATE-----/.test(config.cert ?? ""))
+        throw new Error("cert must be a PEM certificate");
+    if (!/-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----/.test(config.key ?? ""))
+        throw new Error("key must be a PEM private key");
+    // The pair must match: a certificate presented with another key's proof
+    // fails at the server, after the request has gone.
+    let matches = false;
+    try {
+        const key = crypto.createPrivateKey({ key: config.key, ...(config.passphrase ? { passphrase: config.passphrase } : {}) });
+        matches = new crypto.X509Certificate(config.cert).checkPrivateKey(key);
+    }
+    catch (err) {
+        throw new Error(`the certificate or key cannot be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!matches)
+        throw new Error("the key does not belong to the certificate");
+    const stored = {
+        cert: config.cert,
+        key: config.key,
+        ...(config.passphrase ? { passphrase: config.passphrase } : {}),
+        ...(config.export ? { export: true } : {}),
+    };
+    if (!SECRET_NAME.test(name))
+        throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
+    const sealed = encryptValue(tenant, CLIENT_CERT_PREFIX + JSON.stringify(stored));
+    // Written under the vault's own lock, with the binding checked in the same
+    // step: a value set over a secret keeps its site binding, and a wildcard
+    // one would present the certificate to a whole domain.
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        const sites = all[name]?.sites;
+        if (sites?.some((site) => site.startsWith("*."))) {
+            throw new Error(`${name} is bound to ${sites.join(", ")} — a client certificate is bound to exact hosts; unbind the wildcard first`);
+        }
+        all[name] = { ...sealed, updatedAt: new Date().toISOString(), kind: "client-cert", ...(sites?.length ? { sites } : {}) };
+        return all;
+    });
+}
+const IDENTITY_PREFIX = "@identity ";
+export function setIdentitySecret(tenant, name, config, workspace) {
+    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");
+    if (audience.length > 600 || /[\u0000-\u001f\u007f]/.test(audience))
+        throw new Error("audience is one value, at most 600 characters, no control characters");
+    setSecret(tenant, name, IDENTITY_PREFIX + JSON.stringify({ audience }), workspace, "identity");
+}
+export function isIdentityValue(value) {
+    return value.startsWith(IDENTITY_PREFIX);
+}
+export function identityOf(value) {
+    return JSON.parse(value.slice(IDENTITY_PREFIX.length));
+}
+export function isClientCertValue(value) {
+    return value.startsWith(CLIENT_CERT_PREFIX);
+}
+/** An environment without the client certificates that were not saved with
+ *  `export`: those are the egress proxy's to present, never a program's. */
+export function withoutHeldCerts(env) {
+    return Object.fromEntries(Object.entries(env).filter(([, v]) => typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export === true));
+}
+export function clientCertOf(value) {
+    return JSON.parse(value.slice(CLIENT_CERT_PREFIX.length));
+}
+/** `Authorization: Basic …` from a username and password (RFC 7617 §2):
+ *  UTF-8, no colon in the username, no control characters in either. */
+export function basicAuthorization(username, password) {
+    if (typeof username !== "string" || typeof password !== "string")
+        throw new Error("basic needs username and password");
+    if (!username)
+        throw new Error("basic needs a username");
+    if (username.includes(":"))
+        throw new Error("a Basic username cannot contain a colon (RFC 7617)");
+    if (/[\u0000-\u001f\u007f]/.test(username) || /[\u0000-\u001f\u007f]/.test(password))
+        throw new Error("Basic credentials cannot contain control characters");
+    return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
+}
 export function setApiSecret(tenant, name, config, workspace) {
-    const headers = Object.entries(config.headers ?? {});
+    let all = { ...(config.headers ?? {}) };
+    if (config.basic) {
+        if (Object.keys(all).some((h) => h.toLowerCase() === "authorization")) {
+            throw new Error("give either basic or an Authorization header, not both");
+        }
+        // Credentials in the clear over http are leaked ones: https, or loopback.
+        const base = config.base_url?.trim();
+        if (base) {
+            let u = null;
+            try {
+                u = new URL(base);
+            }
+            catch {
+                u = null;
+            }
+            const loopback = u?.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+            if (!u || (u.protocol !== "https:" && !loopback))
+                throw new Error("Basic credentials need an https base_url");
+        }
+        all = { ...all, Authorization: basicAuthorization(config.basic.username, config.basic.password) };
+    }
+    config = { ...(config.base_url ? { base_url: config.base_url } : {}), headers: all };
+    const headers = Object.entries(all);
     if (headers.length === 0)
         throw new Error("api secret needs at least one header");
     for (const [h, v] of headers) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/capture.ts

@@ -7,7 +7,7 @@
 
 import { redactText } from "./scan.ts";
 import { writeCapturedCall, CAPTURE_CAP } from "./store.ts";
-import { isFileValue, fileContent } from "./secrets.ts";
+import { isFileValue, fileContent, isApiValue, apiConfigOf, isClientCertValue, clientCertOf } from "./secrets.ts";
 import type { CallIo } from "./step-exec.ts";
 
 /** How much past the cap a step sends, so masking sees a secret whole
@@ -31,6 +31,38 @@ export function redactionsFor(secrets: Record<string, string | undefined>): [str
   };
   for (const [name, raw] of Object.entries(secrets)) {
     if (typeof raw !== "string") continue;
+    // An API connection's header values are each a secret in their own right
+    // (a token, Basic credentials) — and a Basic header's password too.
+    // An exported client certificate's passphrase and private key reach the
+    // sandbox as files: each is masked, whole and line by line.
+    if (isClientCertValue(raw)) {
+      const c = clientCertOf(raw);
+      for (const v of [c.passphrase, c.key]) {
+        if (!v) continue;
+        add(v, name);
+        add(v.trim(), name);
+        const escaped = JSON.stringify(v).slice(1, -1);
+        if (escaped !== v) add(escaped, name);
+        for (const line of v.split(/\r?\n/)) if (line.trim().length >= 16) add(line.trim(), name);
+      }
+    }
+    if (isApiValue(raw)) {
+      // Each as written and as JSON would escape it, like every value here.
+      const both = (v: string) => {
+        add(v, name);
+        const escaped = JSON.stringify(v).slice(1, -1);
+        if (escaped !== v) add(escaped, name);
+      };
+      for (const v of Object.values(apiConfigOf(raw).headers ?? {})) {
+        both(v);
+        const basic = /^Basic\s+([A-Za-z0-9+/=]+)$/i.exec(v.trim());
+        if (basic) {
+          both(basic[1]!);
+          const decoded = Buffer.from(basic[1]!, "base64").toString("utf8");
+          if (decoded.includes(":")) both(decoded.slice(decoded.indexOf(":") + 1));
+        }
+      }
+    }
     for (const v of isFileValue(raw) ? [raw, fileContent(raw)] : [raw]) {
       add(v, name);
       add(v.trim(), name);

package/src/egress.ts

@@ -96,6 +96,14 @@ export function hostOf(url: string): string | null {
  * from the step's declared secrets and the hosts its tools and provider
  * name; the proxy enforces it per request.
  */
+/** Which workload a lease is for — the runner's word, never the pod's: what
+ *  an identity token's subject is built from (oidc-issuer.ts). */
+export interface LeaseWho {
+  workspace: string;
+  agent: string;
+  flow?: string;
+}
+
 export interface EgressGrant {
   /** Secret name → the hosts that secret may be substituted for. */
   secrets: Record<string, { value: string; hosts: string[] }>;
@@ -116,6 +124,9 @@ export interface EgressGrant {
   /** Refuse a site off the list (true), or allow it and name it in the
    *  trace (false: report only). Set by the platform when it leases. */
   enforce?: boolean;
+  /** Identity name → the audience its tokens are for: the only identities
+   *  this step may ask the proxy's /identity door to mint (oidc-issuer.ts). */
+  identities?: Record<string, { audience: string }>;
 }
 
 export interface EgressLease {
@@ -161,7 +172,10 @@ export interface EgressHooks {
    *  `agent` and `peers` — this step's agent and the other steps of its
    *  parallel group (tools: [peers]): the proxy serves the roster and
    *  addresses a colleague's message to the right inbox. */
-  lease(args: { tenant: string; runId: string; grant: EgressGrant; test?: boolean; step?: number; agent?: string; peers?: PeerInfo[] }): Promise<EgressLease | null>;
+  lease(args: { tenant: string; runId: string; grant: EgressGrant; test?: boolean; step?: number; agent?: string; peers?: PeerInfo[]; who?: LeaseWho }): Promise<EgressLease | null>;
+  /** The run is still being driven: renew its leases' heartbeat. Optional —
+   *  an install without leases has nothing to renew. */
+  renew?(runId: string): Promise<number>;
   /** The step is over — every attempt, however it ended (tools: [peers]).
    *  A lease comes and goes per attempt, so it cannot say this: a sibling
    *  between retries, or waiting for a slot, holds none and is not done.

package/src/run-container.ts

@@ -726,6 +726,36 @@ try {
   const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };
   const inbox = channel ? inboxReader(channel, emit) : undefined;
 
+  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept
+  // fresh through the proxy's /identity door, which mints only what this
+  // step's lease was granted. Fetched before the step starts, renewed five
+  // minutes before it expires (with jitter); a failure is said and retried.
+  // Plain JS: this text is the driver, not TypeScript.
+  const identityNames = (env.FOLDRUN_IDENTITIES || "").split(",").filter(Boolean);
+  if (identityNames.length) {
+    // No backslashes: this sits inside a template literal, which eats them.
+    const ep = new RegExp("^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$").exec(env.FOLDRUN_EGRESS || "");
+    const dir = env.FOLDRUN_IDENTITY_DIR || "/tmp/foldrun-identity";
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const keepFresh = async (name) => {
+      let wait = 30000;
+      try {
+        if (!ep) throw new Error("no egress proxy to ask");
+        const res = await fetch(ep[1] + "/identity/" + ep[2] + "/" + name, { signal: AbortSignal.timeout(15000) });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || ("proxy answered " + res.status));
+        const file = dir + "/" + name.toLowerCase() + ".jwt";
+        fs.writeFileSync(file + ".tmp", body.token, { mode: 0o600 });
+        fs.renameSync(file + ".tmp", file);
+        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);
+      } catch (err) {
+        emit("error", "identity " + name + ": " + (err && err.message ? err.message : String(err)) + " — trying again in 30s");
+      }
+      setTimeout(() => { void keepFresh(name); }, wait).unref();
+    };
+    await Promise.all(identityNames.map(keepFresh));
+  }
+
   mark("tools");
   const outcome = await executeStep({
     agentDir,

package/src/runner.ts

@@ -90,7 +90,7 @@ import {
 import { canReadBack } from "./tool-output.ts";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.ts";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf, type Catalog, type TokenPrice } from "./catalog.ts";
-import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.ts";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites, isClientCertValue, clientCertOf, withoutHeldCerts, isIdentityValue, identityOf } from "./secrets.ts";
 import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.ts";
@@ -1485,7 +1485,8 @@ export function agentContext(
     // the agent, and the date the platform believes it is.
     {
       ...runtime.env,
-      ...secretEnv,
+      // An unexported client certificate is the proxy's, never a script's.
+      ...withoutHeldCerts(secretEnv),
       ...(identity.runId ? { FOLDRUN_RUN_ID: identity.runId } : {}),
       ...(identity.agent ? { FOLDRUN_AGENT: identity.agent } : {}),
       // And the workspace: a commit or a record made by a shared library
@@ -1766,6 +1767,9 @@ export function agentContext(
     // asked for by name fails inside the container with "cannot find" while
     // the host path, which uses this same merged spec, works fine.
     runtime: { log: runtimeLog, error: runtimeError, executor, spec: runtimeSpec, dispose: runtime.dispose },
+    // Whole: a bound client certificate goes from here into the egress
+    // grant (runStep), which is where it is presented. Programs get theirs
+    // filtered (withoutHeldCerts) where their environments are built.
     secretEnv: { ...runtime.env, ...secretEnv },
     formatWarning: checkFormatVersion(workspaceFrontmatter(agentDir, tenant).foldrun_version).warning,
     providerEnv,
@@ -2686,11 +2690,27 @@ async function runStep(
         readAgentsMd(accountDir(tenant))?.data?.network_enforce,
         readAgentsMd(workspaceRootOf(agentDir))?.data?.network_enforce,
       );
+      // Keyless cloud identities the step declared: the proxy may mint tokens
+      // for these audiences only, for this workload (oidc-issuer.ts).
+      // A test run withholds them as it withholds every credential
+      // (test-mode.ts): a token is a credential, however it is delivered.
+      const declaredIdentities = Object.entries(liveSecrets).filter(([, v]) => typeof v === "string" && isIdentityValue(v));
+      const identitiesHeld = testRun
+        ? withholdSecrets(Object.fromEntries(declaredIdentities), {
+            outward: scriptSpecs.some((sc) => sc.outward),
+            allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
+          }).withheld
+        : [];
+      const identities = Object.fromEntries(
+        declaredIdentities.filter(([name]) => !identitiesHeld.includes(name)).map(([name, v]) => [name, { audience: identityOf(v).audience }]),
+      );
+      if (Object.keys(identities).length) grant.identities = identities;
       const lease = await platform.egress.lease({
         tenant,
         runId: runId ?? "adhoc",
         grant,
         test: testRun,
+        who: { workspace: workspaceName, agent: step.agent },
         ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}),
         // tools: [peers] — the roster the proxy serves, and the inboxes a
         // colleague's message may be addressed to. Only when granted: a
@@ -2763,6 +2783,34 @@ async function runStep(
           push("info", `test: ${name} withheld from the sandbox — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
         }
       }
+      // A keyless identity holds nothing to hand over: the sandbox gets the
+      // path of a token file the driver keeps fresh through the proxy's
+      // /identity door. Without a lease there is no door, and so no token.
+      const identityDeclared = declared.filter((name) => typeof liveSecrets[name] === "string" && isIdentityValue(liveSecrets[name]!));
+      for (const name of identityDeclared) delete sandboxSecrets[name];
+      for (const name of identitiesHeld) {
+        push("info", `test: ${name} withheld — no identity token on a test run`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
+      }
+      const identityNames = identityDeclared.filter((name) => !identitiesHeld.includes(name));
+      if (identityNames.length) {
+        if (lease) {
+          const dir = "/tmp/foldrun-identity";
+          sandboxSecrets.FOLDRUN_IDENTITIES = identityNames.join(",");
+          sandboxSecrets.FOLDRUN_IDENTITY_DIR = dir;
+          for (const name of identityNames) sandboxSecrets[`${name}_FILE`] = `${dir}/${name.toLowerCase()}.jwt`;
+          push("info", `identity: ${identityNames.join(", ")} — a short-lived token in $NAME_FILE, renewed by the platform while the step runs`);
+        } else {
+          push("error", `identity: ${identityNames.join(", ")} needs a sandboxed step on the platform — no token here`);
+        }
+      }
+      // A client certificate is the proxy's to present, to the exact sites it
+      // is bound to; never the sandbox's, unless it was saved with `export`.
+      for (const name of declared) {
+        const v = liveSecrets[name];
+        if (typeof v !== "string" || !isClientCertValue(v) || bound.includes(name) || clientCertOf(v).export) continue;
+        delete sandboxSecrets[name];
+        push("info", `secrets: ${name} is a client certificate — the egress proxy presents it to the sites it is bound to (\`foldrun secrets sites ${name} <host>\`); unbound, it stays out of the sandbox`);
+      }
       // On a test run the http tools always go through the proxy as
       // placeholders, even when a script made the step materialise: the
       // proxy is where the outward-write policy lives, and a header
@@ -3174,7 +3222,20 @@ async function runStep(
       for (const name of held.withheld) {
         push("info", `test: ${name} withheld from scripts — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from scripts` } });
       }
-      const stepSecrets = held.env;
+      // A client certificate not saved with `export` has no proxy here to
+      // present it: it stays out of everything this step runs — tools,
+      // consults, verify commands — not only out of the files.
+      const stepSecrets = Object.fromEntries(
+        Object.entries(held.env).filter(([name, v]) => {
+          if (typeof v === "string" && isIdentityValue(v)) {
+            push("error", `identity: ${name} needs a sandboxed step on the platform — no token here`);
+            return false;
+          }
+          if (typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export) return true;
+          push("info", `secrets: ${name} is a client certificate — no egress proxy here to present it; save it with export to use it as files`);
+          return false;
+        }),
+      );
       // The model credential for this machine's Claude Code — the agent's
       // own provider when it names one. The host allowlist drops it, so
       // without this every in-process step ran on the machine's login.
@@ -4038,7 +4099,14 @@ export function driveRun(
   opts: { parkOnApproval?: boolean; effortOverride?: string | null } = {},
 ): Promise<void> {
   drivingRuns.add(run.id);
+  // The run's egress leases are renewed while it is driven, by whichever
+  // door drove it — the queue, or a reconcile that picked it back up — so an
+  // identity token is renewed for a live step however it was started.
+  const renew = platform.egress.renew;
+  const beat = renew ? setInterval(() => void renew(run.id).catch(() => undefined), 5 * 60_000) : null;
+  beat?.unref?.();
   return driveRunInner(tenant, workspace, run, modelOverride, tags, opts).finally(() => {
+    if (beat) clearInterval(beat);
     drivingRuns.delete(run.id);
   });
 }

package/src/secret-files.ts

@@ -21,7 +21,7 @@ import path from "node:path";
 import {
   isFileValue, fileContent,
   isSshValue, sshConfigOf,
-  isApiValue, apiConfigOf,
+  isApiValue, apiConfigOf, isClientCertValue, clientCertOf,
 } from "./secrets.ts";
 
 // POSIX single-quoting: the one escape sh actually honours inside ' is none,
@@ -46,7 +46,7 @@ export function materializeFileSecrets(
   env: Record<string, string>,
 ): { env: Record<string, string>; dir: string | null } {
   const entries = Object.entries(env).filter(
-    ([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v)),
+    ([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v) || isClientCertValue(v)),
   );
   if (entries.length === 0) return { env, dir: null };
 
@@ -62,6 +62,26 @@ export function materializeFileSecrets(
       const file = path.join(dir, name.toLowerCase());
       fs.writeFileSync(file, fileContent(value), { mode: 0o600 });
       out[name] = file;
+    } else if (isClientCertValue(value)) {
+      // Only an exported certificate reaches here as itself (the runner
+      // withholds the rest): its parts as files, $NAME the certificate.
+      const c = clientCertOf(value);
+      if (!c.export) {
+        delete out[name];
+        continue;
+      }
+      const cert = path.join(dir, `${name.toLowerCase()}.crt`);
+      const key = path.join(dir, `${name.toLowerCase()}.key`);
+      fs.writeFileSync(cert, c.cert, { mode: 0o600 });
+      fs.writeFileSync(key, c.key, { mode: 0o600 });
+      out[name] = cert;
+      out[`${name}_CERT`] = cert;
+      out[`${name}_KEY`] = key;
+      if (c.passphrase) {
+        const pass = path.join(dir, `${name.toLowerCase()}.pass`);
+        fs.writeFileSync(pass, c.passphrase, { mode: 0o600 });
+        out[`${name}_PASSPHRASE_FILE`] = pass;
+      }
     } else if (isSshValue(value)) {
       const ssh = sshConfigOf(value);
       const dest = `${ssh.user}@${ssh.host}`;