@foldrun/core 2.6.0 → 2.7.0

package/src/secrets.ts

@@ -88,7 +88,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";
+export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity";
 
 interface StoredSecret {
   iv: string;
@@ -236,6 +236,11 @@ export function setSecretSites(tenant: string, name: string, sites: string[], wo
     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 delete rec.sites;
     return all;
@@ -545,7 +550,9 @@ export function rotateMasterKey(
 export interface OAuth2Config {
   token_url: string;
   client_id: string;
-  client_secret: string;
+  /** Absent for a public client (an app with no secret, connected with
+   *  PKCE): its refresh sends client_id and refresh_token only. */
+  client_secret?: string;
   /** Required for the refresh grant; absent for client_credentials. */
   refresh_token?: string;
   /** "refresh_token" (default — user-consented) or "client_credentials"
@@ -573,9 +580,14 @@ export function setOAuth2Secret(
   config: OAuth2Config,
   workspace?: string,
 ) {
-  for (const field of ["token_url", "client_id", "client_secret"] as const) {
+  for (const field of ["token_url", "client_id"] as const) {
     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)");
   }
@@ -597,11 +609,67 @@ export function isOAuth2Value(value: string): boolean {
 const tokenCache = new Map<string, { token: string; expiresAt: number }>();
 const inFlight = new Map<string, Promise<string>>();
 
-async function exchange(config: OAuth2Config, cacheKey: string): Promise<string> {
-  const cached = tokenCache.get(cacheKey);
-  if (cached && cached.expiresAt > Date.now()) return cached.token;
+/**
+ * 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: "oauth2" | "sa", storedValue: string, tenant?: string): string {
+  return crypto.createHash("sha256").update(JSON.stringify([kind, tenant ?? "", storedValue])).digest("hex");
+}
 
-  const pending = inFlight.get(cacheKey);
+/**
+ * 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: string, name: string, workspace: string | undefined, usedValue: string, refreshToken: string): boolean {
+  if (!isOAuth2Value(usedValue)) return false;
+  const config = JSON.parse(usedValue.slice(OAUTH2_PREFIX.length)) as OAuth2Config;
+  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;
+}
+
+/** An oauth2 refresh's outcome: the access token and, when the provider
+ *  rotated it, the new refresh token — kept with the cache entry so every
+ *  copy of the old credential (another secret name, another scope) that is
+ *  served this token also gets the new refresh token written back. */
+interface OAuthLive { token: string; expiresAt: number; rotated?: string }
+const oauthCache = new Map<string, OAuthLive>();
+const oauthFlight = new Map<string, Promise<OAuthLive>>();
+
+/** 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: string, live: OAuthLive): void {
+  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: OAuth2Config, cacheKey: string): Promise<OAuthLive> {
+  const cached = oauthCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) return cached;
+
+  const pending = oauthFlight.get(cacheKey);
   if (pending) return pending;
 
   const flight = (async () => {
@@ -609,7 +677,7 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
       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"
@@ -639,6 +707,7 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
     if (!res) throw lastNetwork instanceof Error ? lastNetwork : new Error(String(lastNetwork));
     const payload = (await res.json().catch(() => ({}))) as {
       access_token?: string;
+      refresh_token?: string;
       expires_in?: number;
       error?: string;
       error_description?: string;
@@ -649,15 +718,21 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
       );
     }
     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: OAuthLive = { 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);
   }
 }
 
@@ -685,13 +760,21 @@ export async function materializeSecrets(
         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);
         const link = ctx ? await platform.noteOAuthRefresh(ctx, name, message).catch(() => undefined) : undefined;
@@ -706,7 +789,7 @@ export async function materializeSecrets(
         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)}`);
       }
@@ -737,6 +820,10 @@ export interface ServiceAccountConfig {
   scope: string; // space-separated
   /** JWT audience — usually the same as token_url. */
   audience?: string;
+  /** The JWT bearer grant's subject (RFC 7523 §3): the user the account acts
+   *  as, where the provider allows it — Google's domain-wide delegation, once
+   *  a Workspace admin grants it. Absent, the account acts as itself. */
+  subject?: string;
 }
 
 export function setServiceAccountSecret(
@@ -751,7 +838,12 @@ export function setServiceAccountSecret(
   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: ServiceAccountConfig = { ...config, ...(config.subject !== undefined ? { subject: config.subject.trim() } : {}) };
+  setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(stored), workspace, "service-account");
 }
 
 function base64url(input: Buffer | string): string {
@@ -770,7 +862,9 @@ async function exchangeServiceAccount(config: ServiceAccountConfig, cacheKey: st
     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,
@@ -898,14 +992,134 @@ export function sshConfigOf(value: string): SshConfig {
 // never appears in the bash command at all.
 
 const API_PREFIX = "@api ";
+const CLIENT_CERT_PREFIX = "@client-cert ";
+
+/** A client certificate for mutual TLS: presented by the egress proxy, on its
+ *  own connection, to the exact hosts the secret is bound to — the sandbox
+ *  never holds the key. `export` puts it in the sandbox as files instead,
+ *  only when asked for (a step with no egress proxy). */
+export interface ClientCertConfig {
+  /** PEM certificate, chain included. */
+  cert: string;
+  /** PEM private key. */
+  key: string;
+  passphrase?: string;
+  export?: boolean;
+}
+
+export function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string) {
+  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: ClientCertConfig = {
+    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 ";
+
+/** A keyless cloud identity: no credential at all, only the audience the
+ *  platform's signed tokens are for. A step that declares it gets a token
+ *  file the sandbox driver keeps fresh through the egress proxy. */
+export interface IdentityConfig {
+  audience: string;
+}
+
+export function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string) {
+  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: string): boolean {
+  return value.startsWith(IDENTITY_PREFIX);
+}
+
+export function identityOf(value: string): IdentityConfig {
+  return JSON.parse(value.slice(IDENTITY_PREFIX.length));
+}
+
+export function isClientCertValue(value: string): boolean {
+  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: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(env).filter(([, v]) => typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export === true));
+}
+
+export function clientCertOf(value: string): ClientCertConfig {
+  return JSON.parse(value.slice(CLIENT_CERT_PREFIX.length));
+}
 
 export interface ApiConfig {
   base_url?: string;
   headers: Record<string, string>;
+  /** Username and password for HTTP Basic (RFC 7617): stored as the
+   *  `Authorization: Basic …` header they make, never kept apart. */
+  basic?: { username: string; password: string };
+}
+
+/** `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: string, password: string): string {
+  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: string, name: string, config: ApiConfig, workspace?: string) {
-  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: URL | null = 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) {
     if (!/^[A-Za-z0-9-]+$/.test(h)) throw new Error(`"${h}" is not a valid header name`);