@foldrun/core 9.0.0 → 9.2.0

package/dist/src/secrets.js

@@ -106,11 +106,43 @@ function secretsFile(tenant, workspace) {
 // every rename a re-seal racing other writers. What that leaves open — a
 // ciphertext moved between two workspaces of the same account by someone who
 // can already write the volume — is the residual, and stays inside one account.
+//
+// Rolling out (30 Oct 2026, accepted, no switch): a pod from before this
+// release cannot open a limited record (its AAD lacks the list), and one that
+// sets a new value over it writes the record back without the list — open to
+// every workspace again. So limits are set after every pod, worker and the
+// egress proxy run this version; the secrets docs say so.
+//
+// The workspaces an account secret is limited to are in the seal too (30 Oct
+// 2026), appended only when the record has the list: every record sealed
+// before keeps the AAD it was sealed with, and a list added to, widened in or
+// stripped from a sealed record on disk makes it fail to open — "not set",
+// never "every workspace". These ARE workspace names, so a rename re-seals
+// them (retargetSecretWorkspaces), under the vault lock.
 function vaultAad(tenant, workspace, name, rec) {
     if (rec.sites !== undefined && (!Array.isArray(rec.sites) || rec.sites.some((x) => typeof x !== "string"))) {
         throw new Error("malformed sites");
     }
-    return Buffer.from(JSON.stringify(["foldrun-vault/2", tenant, workspace ? "w" : "a", name, rec.kind ?? "", rec.k ?? "install", [...(rec.sites ?? [])].sort()]), "utf8");
+    if (rec.workspaces !== undefined && (!Array.isArray(rec.workspaces) || rec.workspaces.some((x) => typeof x !== "string"))) {
+        throw new Error("malformed workspaces");
+    }
+    return Buffer.from(JSON.stringify([
+        "foldrun-vault/2",
+        tenant,
+        workspace ? "w" : "a",
+        name,
+        rec.kind ?? "",
+        rec.k ?? "install",
+        [...(rec.sites ?? [])].sort(),
+        ...(rec.workspaces !== undefined ? [["workspaces", [...rec.workspaces].sort()]] : []),
+    ]), "utf8");
+}
+/** May an account record be used in this workspace? No list: everywhere. A
+ *  list that is not a list of names (rewritten on disk) allows nowhere. */
+function usableIn(rec, workspace) {
+    if (!rec || rec.workspaces === undefined)
+        return true;
+    return Array.isArray(rec.workspaces) && rec.workspaces.includes(workspace);
 }
 const writeBound = () => process.env.FOLDRUN_VAULT_WRITE_BOUND === "1";
 const requireBound = () => process.env.FOLDRUN_VAULT_REQUIRE_BOUND === "1";
@@ -126,6 +158,8 @@ function sealRecord(tenant, workspace, name, value, meta, bound = writeBound())
         ...(meta.kind ? { kind: meta.kind } : {}),
         ...(mark ? { k: mark } : {}),
         ...(meta.sites?.length ? { sites: [...meta.sites] } : {}),
+        // An empty list is a choice (no workspace may use it), kept as written.
+        ...(meta.workspaces !== undefined ? { workspaces: [...meta.workspaces] } : {}),
     };
     const iv = crypto.randomBytes(12);
     const cipher = crypto.createCipheriv("aes-256-gcm", key, iv, GCM);
@@ -187,6 +221,16 @@ function readFile(file) {
     }
 }
 function lockVault(file) {
+    return lockFileExclusive(file, "the vault is busy — another change is being saved; try again");
+}
+/**
+ * An exclusive lock on `file` for a read-change-write, across processes and
+ * pods: `<file>.lock` opened O_EXCL (NFS 4.1 and EFS honour it), taken over
+ * when older than LOCK_STALE_MS (a holder that died), waited for up to
+ * LOCK_WAIT_MS, then `busy` is thrown. Returns the release. The vault's,
+ * and any other small state file several runs write (a2a-tools' handles).
+ */
+export function lockFileExclusive(file, busy = `${path.basename(file)} is busy — another writer holds it; try again`) {
     const lock = `${file}.lock`;
     const deadline = Date.now() + LOCK_WAIT_MS;
     for (;;) {
@@ -209,7 +253,7 @@ function lockVault(file) {
                 continue; // released between the open and the stat
             }
             if (Date.now() > deadline)
-                throw new Error("the vault is busy — another change is being saved; try again");
+                throw new Error(busy);
             sleep(25);
         }
     }
@@ -237,7 +281,38 @@ export function mutateVaultFile(file, change) {
     }
 }
 export const SECRET_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
-export function setSecret(tenant, name, value, workspace, kind) {
+/**
+ * How a `signing_secret:` is shown in an answer, a log line or a delivery
+ * record: the name it holds, and only a name (30 Oct 2026). It is meant to
+ * name a vault entry, but nothing stopped the value itself being written
+ * there, and notify's test send echoed it back to the dashboard as "signed
+ * with <it>". Anything that is not a secret name is described, never
+ * repeated (foldrun check flags it as secret/signing-secret-value).
+ */
+export function signingSecretShown(name) {
+    return SECRET_NAME.test(name) ? name : "the signing_secret: (not a secret name — see foldrun check)";
+}
+/** A list as stored: trimmed, de-duplicated, sorted; every name a safe one
+ *  and, when the caller can say, one that exists. */
+function cleanWorkspaceList(workspaces) {
+    if (workspaces === null)
+        return null;
+    if (!Array.isArray(workspaces) || workspaces.some((w) => typeof w !== "string")) {
+        throw new Error("workspaces is a list of workspace names, or null for every workspace");
+    }
+    const clean = [...new Set(workspaces.map((w) => w.trim()).filter(Boolean))].sort();
+    for (const w of clean)
+        assertSafeName(w, "workspace");
+    return clean;
+}
+function assertWorkspacesExist(list, exists) {
+    if (!list || !exists)
+        return;
+    const missing = list.filter((w) => !exists(w));
+    if (missing.length)
+        throw Object.assign(new Error(`no workspace ${missing.join(", ")} in this account`), { status: 400 });
+}
+export function setSecret(tenant, name, value, workspace, kind, limit = {}) {
     // A string, not anything that prints as one: RegExp.test and the vault's
     // keys both coerce, so ["RESEND_API_KEY"] from a JSON body was stored as
     // RESEND_API_KEY past a caller's check on the name (30 Oct 2026).
@@ -246,18 +321,35 @@ export function setSecret(tenant, name, value, workspace, kind) {
     }
     if (value.length > 8192)
         throw new Error("secret too long");
+    const wanted = limitFor(workspace, limit);
     mutateVaultFile(secretsFile(tenant, workspace), (all) => {
         // A new value keeps the sites the old one was bound to: binding is a
         // property of the credential's use, not of its current value, and a
         // rotation that silently unbound it would put the new value in pods.
         // Sealed here, under the lock: a bound record's AAD names those sites.
         const sites = all[name]?.sites;
+        // The workspaces it is limited to stay too, for the same reason: a new
+        // value that every workspace could suddenly read is a widening nobody
+        // asked for — unless this call says otherwise, in the same write.
+        if (wanted !== undefined)
+            assertWorkspacesExist(wanted, limit.exists);
+        const workspaces = wanted !== undefined ? (wanted ?? undefined) : all[name]?.workspaces;
         // Once bound, always bound: a re-save with the switch off must not
-        // quietly drop the record's authentication.
-        all[name] = sealRecord(tenant, workspace, name, value, { kind, sites }, all[name]?.v === 2 || writeBound());
+        // quietly drop the record's authentication. A limited record is always
+        // bound, so its list is in its seal (see setSecretWorkspaces).
+        all[name] = sealRecord(tenant, workspace, name, value, { kind, sites, workspaces }, all[name]?.v === 2 || workspaces !== undefined || writeBound());
         return all;
     });
 }
+/** The list a write was asked to store, checked: undefined when it was not
+ *  asked to change it. Only the account's store has lists. */
+function limitFor(workspace, limit) {
+    if (limit.workspaces === undefined)
+        return undefined;
+    if (workspace)
+        throw new Error("a workspace's own secret is that workspace's already — only an account secret is limited to workspaces");
+    return cleanWorkspaceList(limit.workspaces);
+}
 /**
  * Bind a secret to sites, or unbind it (an empty list). The secret must
  * exist in that scope. Sites are `api.example.com` or `*.example.com` — no
@@ -296,7 +388,7 @@ export function setSecretSites(tenant, name, sites, workspace) {
             const value = openRecord(tenant, workspace, name, rec);
             if (value === null)
                 throw new Error(`${name} cannot be read with this install's keys — set its value again before binding it`);
-            all[name] = sealRecord(tenant, workspace, name, value, { kind: rec.kind, sites: clean, updatedAt: rec.updatedAt }, true);
+            all[name] = sealRecord(tenant, workspace, name, value, { kind: rec.kind, sites: clean, workspaces: rec.workspaces, updatedAt: rec.updatedAt }, true);
             return all;
         }
         if (clean.length)
@@ -323,7 +415,11 @@ export function secretSites(tenant, names, workspace) {
         // when it opens, else the account's. Picking by presence paired an
         // account value with a workspace record's (unauthenticated) sites.
         const ownRec = own[name];
-        const rec = ownRec && openRecord(tenant, workspace, name, ownRec) !== null ? ownRec : account[name];
+        const ownOpens = Boolean(ownRec && openRecord(tenant, workspace, name, ownRec) !== null);
+        // An account record limited to other workspaces is not this one's.
+        if (!ownOpens && workspace && !usableIn(account[name], workspace))
+            continue;
+        const rec = ownOpens ? ownRec : account[name];
         if (rec?.sites?.length)
             out[name] = [...rec.sites];
     }
@@ -398,16 +494,141 @@ function decrypt(tenant, rec, aad) {
         return null; // key rotated or file tampered with
     }
 }
-/** Nearest wins: a workspace secret shadows an account one of the same name. */
+/** Nearest wins: a workspace secret shadows an account one of the same name.
+ *  An account secret limited to some workspaces (setSecretWorkspaces) is
+ *  absent for every other — the answer a secret that was never set gets, on
+ *  every path that resolves one for a workspace: runs, tool tests, notify,
+ *  the egress proxy, MCP servers. Without a workspace it is the account's
+ *  own use (its model key, its mail sender), which no list limits. */
 export function getSecret(tenant, name, workspace) {
     if (workspace) {
         const own = openRecord(tenant, workspace, name, read(tenant, workspace)[name]);
         if (own !== null)
             return { value: own, scope: "workspace" };
     }
-    const shared = openRecord(tenant, undefined, name, read(tenant)[name]);
+    const rec = read(tenant)[name];
+    if (workspace && !usableIn(rec, workspace))
+        return null;
+    const shared = openRecord(tenant, undefined, name, rec);
     return shared === null ? null : { value: shared, scope: "account" };
 }
+/** May the ACCOUNT's secret `name` be used for this workspace? True when it
+ *  is not limited (or not set); for callers that read the account's copy on
+ *  a workspace's behalf without getSecret's workspace-first lookup — the
+ *  account's mail sender for a workspace's notifications (notify.ts). */
+export function accountSecretUsableIn(tenant, name, workspace) {
+    return usableIn(read(tenant)[name], workspace);
+}
+/**
+ * Limit an account secret to some workspaces, or lift the limit (null).
+ * An empty list means no workspace may use it. Returns the list as stored,
+ * sorted, or null.
+ *
+ * `exists` is asked about each name under the vault lock (the API passes
+ * "is there such a workspace"), so it cannot grant a name a delete has just
+ * taken off every list. `ifWorkspaces`, when given, is the list the caller
+ * saw (null: every workspace): a list changed since is refused (409), so
+ * two admins editing it at once do not silently overwrite each other.
+ *
+ * The record is sealed (v2) whatever it was, whatever
+ * FOLDRUN_VAULT_WRITE_BOUND says: a list in the clear on an unbound record
+ * could be stripped on disk to open the secret to every workspace; sealed,
+ * a stripped list makes it unreadable. Every reader since 29 Oct 2026 reads v2.
+ */
+export function setSecretWorkspaces(tenant, name, workspaces, opts = {}) {
+    if (typeof name !== "string")
+        throw new Error("a secret's name is a string");
+    const clean = cleanWorkspaceList(workspaces);
+    const expected = opts.ifWorkspaces === undefined ? undefined : cleanWorkspaceList(opts.ifWorkspaces);
+    let found = false;
+    mutateVaultFile(secretsFile(tenant), (all) => {
+        const rec = all[name];
+        if (!rec)
+            return null;
+        found = true;
+        if (expected !== undefined) {
+            const now = Array.isArray(rec.workspaces) ? [...rec.workspaces].sort() : null;
+            if (JSON.stringify(now) !== JSON.stringify(expected)) {
+                throw Object.assign(new Error(`${name}'s workspaces changed since you loaded them (now ${now === null ? "every workspace" : now.length ? now.join(", ") : "none"}) — reload and try again`), { status: 409 });
+            }
+        }
+        assertWorkspacesExist(clean, opts.exists);
+        all[name] = withWorkspaces(tenant, name, rec, clean);
+        return all;
+    });
+    if (!found)
+        throw Object.assign(new Error(`no secret ${name} in the account`), { status: 404 });
+    return clean;
+}
+/** An account record with its workspace list replaced (null: removed),
+ *  opened and sealed again as a bound record with the new list in its seal.
+ *  One that will not open is refused, never relabelled (setSecretSites). */
+function withWorkspaces(tenant, name, rec, workspaces) {
+    const value = openRecord(tenant, undefined, name, rec);
+    if (value === null)
+        throw new Error(`${name} cannot be read with this install's keys — set its value again before changing its workspaces`);
+    return sealRecord(tenant, undefined, name, value, { kind: rec.kind, sites: rec.sites, workspaces: workspaces ?? undefined, updatedAt: rec.updatedAt }, true);
+}
+/**
+ * A workspace is being renamed (to: its new name) or deleted (to: null):
+ * every account secret limited to it follows. Without this a rename quietly
+ * cut the workspace off its secrets, and a delete left the name on the list
+ * for the next workspace given it.
+ *
+ * `failed` names the records that hold the name but will not open with this
+ * install's keys: they are left exactly as they are, so the old name is
+ * STILL on their list — a key restored later would bring the grant back.
+ * The caller must not report the rename or delete as clean while any are
+ * left (the API refuses it, naming them: set them again, or delete them).
+ *
+ * Names, not ids: a grant naming a workspace's immutable id would survive a
+ * rename untouched and could never pass to a new workspace given an old
+ * name — the stronger design, not built yet (30 Oct 2026).
+ */
+export function retargetSecretWorkspaces(tenant, from, to) {
+    const changed = [];
+    const failed = [];
+    const file = secretsFile(tenant);
+    if (!fs.existsSync(file))
+        return { changed, failed };
+    mutateVaultFile(file, (all) => {
+        changed.length = 0;
+        failed.length = 0;
+        const staged = {};
+        for (const [name, rec] of Object.entries(all)) {
+            const list = rec.workspaces;
+            if (list === undefined)
+                continue;
+            if (!Array.isArray(list)) {
+                // A list rewritten on disk into something else allows nowhere
+                // (usableIn) — nothing for this rename to carry.
+                continue;
+            }
+            if (!list.includes(from))
+                continue;
+            const next = [...new Set(list.map((w) => (w === from ? to : w)).filter((w) => typeof w === "string"))].sort();
+            try {
+                staged[name] = withWorkspaces(tenant, name, rec, next);
+                changed.push(name);
+            }
+            catch {
+                failed.push(name);
+            }
+        }
+        // All or nothing (Codex, 30 Oct 2026): writing the readable records and
+        // refusing the rename for the unreadable ones moved grants to a name the
+        // workspace never took. One failure leaves the vault exactly as it was.
+        if (failed.length) {
+            changed.length = 0;
+            return null;
+        }
+        if (!changed.length)
+            return null;
+        Object.assign(all, staged);
+        return all;
+    });
+    return { changed, failed };
+}
 export function deleteSecret(tenant, name, workspace) {
     mutateVaultFile(secretsFile(tenant, workspace), (all) => {
         if (!(name in all))
@@ -420,12 +641,18 @@ export function deleteSecret(tenant, name, workspace) {
 // store; with one it lists what that workspace actually resolves, marking
 // which scope each name comes from.
 export function listSecrets(tenant, workspace) {
-    const account = Object.entries(read(tenant)).map(([name, rec]) => ({
+    const records = Object.entries(read(tenant));
+    const account = records
+        // What a workspace resolves leaves out an account secret limited to
+        // others: it is not set, as far as that workspace is concerned.
+        .filter(([, rec]) => !workspace || usableIn(rec, workspace))
+        .map(([name, rec]) => ({
         name,
         updatedAt: rec.updatedAt,
         scope: "account",
         ...(rec.kind ? { kind: rec.kind } : {}),
         ...(rec.sites?.length ? { sites: [...rec.sites] } : {}),
+        ...(!workspace && Array.isArray(rec.workspaces) ? { workspaces: [...rec.workspaces] } : {}),
     }));
     if (!workspace)
         return account.sort((a, b) => a.name.localeCompare(b.name));
@@ -559,6 +786,9 @@ export function rotateMasterKey(tenant, from, to) {
                     // Kept too (it was dropped until 29 Oct 2026): a rotation that
                     // unbinds every bound secret puts their values into pods.
                     ...(rec.sites?.length ? { sites: rec.sites } : {}),
+                    // And the workspaces it is limited to: dropped, it would read as
+                    // "every workspace" (and fail its seal).
+                    ...(rec.workspaces !== undefined ? { workspaces: rec.workspaces } : {}),
                     ...(aad ? { v: 2 } : {}),
                 };
                 count++;
@@ -578,7 +808,7 @@ export function oauthRetryDelayMs(n) {
     const base = Number(process.env.FOLDRUN_OAUTH_RETRY_MS ?? 1000);
     return base * (n === 1 ? 1 : 3);
 }
-export function setOAuth2Secret(tenant, name, config, workspace) {
+export function setOAuth2Secret(tenant, name, config, workspace, limit = {}) {
     for (const field of ["token_url", "client_id"]) {
         if (!config[field]?.trim())
             throw new Error(`oauth2 secret needs ${field}`);
@@ -596,7 +826,7 @@ export function setOAuth2Secret(tenant, name, config, workspace) {
     if (!/^https:\/\//.test(config.token_url) && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(config.token_url)) {
         throw new Error("token_url must be https — a refresh token over http is a leaked one");
     }
-    setSecret(tenant, name, OAUTH2_PREFIX + JSON.stringify(config), workspace, "oauth2");
+    setSecret(tenant, name, OAUTH2_PREFIX + JSON.stringify(config), workspace, "oauth2", limit);
 }
 export function isOAuth2Value(value) {
     return value.startsWith(OAUTH2_PREFIX);
@@ -638,7 +868,7 @@ export function replaceOAuth2RefreshToken(tenant, name, workspace, usedValue, re
                 // Built whole, not spread over the old record: a spread kept a stale
                 // `k: "tenant"` when this seal fell back to the install key, and the
                 // record then opened with neither.
-                all[name] = sealRecord(tenant, scope, name, next, { kind: rec.kind, sites: rec.sites }, rec.v === 2 || writeBound());
+                all[name] = sealRecord(tenant, scope, name, next, { kind: rec.kind, sites: rec.sites, workspaces: rec.workspaces }, rec.v === 2 || writeBound());
                 replaced = true;
             }
             return all;
@@ -799,6 +1029,36 @@ ctx) {
     }
     return out;
 }
+/**
+ * materializeSecrets for a tool that holds secrets for a whole step and
+ * makes them live per call (the API tools, the a2a tools), on a host with
+ * the vault.
+ *
+ * Two things the step's copy of a recipe cannot do alone. A provider that
+ * rotates refresh tokens has spent the refresh token the step started with —
+ * the runner materialised it at step start, and any refresh since spent its
+ * successor — so an oauth2 recipe is read again from the vault as it is now
+ * (and `env` updated in place, for the next call). And it is made live in
+ * the account's scope, as the runner and the egress proxy do: the cached
+ * access token is keyed by account, and a rotation is written back to the
+ * vault by the compare-and-set above. Refreshing the starting recipe outside
+ * that scope missed the cache and sent a spent refresh token: invalid_grant.
+ *
+ * No `scope` (inside a sandbox, where there is no vault and the values
+ * crossed already made live): materializeSecrets as it was.
+ */
+export async function materializeCurrent(env, scope) {
+    if (!scope?.tenant)
+        return materializeSecrets(env);
+    for (const [name, value] of Object.entries(env)) {
+        if (typeof value !== "string" || !isOAuth2Value(value))
+            continue;
+        const current = getSecret(scope.tenant, name, scope.workspace)?.value;
+        if (current && isOAuth2Value(current))
+            env[name] = current;
+    }
+    return materializeSecrets(env, { tenant: scope.tenant, ...(scope.workspace ? { workspace: scope.workspace } : {}) });
+}
 // ---------------------------------------------------------------- service account
 // Signed-key credentials: a Google service account, or anything that mints a
 // token by self-signing a JWT with a private key and exchanging it. No user,
@@ -808,7 +1068,7 @@ ctx) {
 // Stored as the JSON key, encrypted. Materialised the same way oauth2 is: a
 // live access token appears at the last host-side moment, cached until expiry.
 const SERVICE_ACCOUNT_PREFIX = "@service-account ";
-export function setServiceAccountSecret(tenant, name, config, workspace) {
+export function setServiceAccountSecret(tenant, name, config, workspace, limit = {}) {
     for (const field of ["token_url", "issuer", "private_key", "scope"]) {
         if (!config[field]?.trim())
             throw new Error(`service account secret needs ${field}`);
@@ -823,7 +1083,7 @@ export function setServiceAccountSecret(tenant, name, config, workspace) {
             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");
+    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(stored), workspace, "service-account", limit);
 }
 function base64url(input) {
     return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -886,10 +1146,10 @@ async function exchangeServiceAccount(config, cacheKey) {
 // the only place that knows where a run's writable scratch is; here we only
 // mark the kind and carry the content.
 const FILE_PREFIX = "@file ";
-export function setFileSecret(tenant, name, content, workspace) {
+export function setFileSecret(tenant, name, content, workspace, limit = {}) {
     if (!content)
         throw new Error("a file secret needs content");
-    setSecret(tenant, name, FILE_PREFIX + content, workspace, "file");
+    setSecret(tenant, name, FILE_PREFIX + content, workspace, "file", limit);
 }
 export function isFileValue(value) {
     return value.startsWith(FILE_PREFIX);
@@ -905,7 +1165,7 @@ export function fileContent(value) {
 // config into an executable wrapper, so the agent runs `"$NAME" 'uptime'`
 // and never learns which auth flavour it is.
 const SSH_PREFIX = "@ssh ";
-export function setSshSecret(tenant, name, config, workspace) {
+export function setSshSecret(tenant, name, config, workspace, limit = {}) {
     const host = config.host?.trim();
     const user = config.user?.trim();
     if (!host || /[\s'"`$\\]/.test(host))
@@ -928,7 +1188,7 @@ export function setSshSecret(tenant, name, config, workspace) {
         host, user, port,
         ...(hasKey ? { private_key: config.private_key } : { password: config.password }),
     };
-    setSecret(tenant, name, SSH_PREFIX + JSON.stringify(stored), workspace, "ssh");
+    setSecret(tenant, name, SSH_PREFIX + JSON.stringify(stored), workspace, "ssh", limit);
 }
 export function isSshValue(value) {
     return value.startsWith(SSH_PREFIX);
@@ -944,7 +1204,7 @@ export function sshConfigOf(value) {
 // 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) {
+export function setClientCertSecret(tenant, name, config, workspace, limit = {}) {
     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 ?? ""))
@@ -973,23 +1233,27 @@ export function setClientCertSecret(tenant, name, config, workspace) {
     // 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.
+    const wanted = limitFor(workspace, limit);
     mutateVaultFile(secretsFile(tenant, workspace), (all) => {
         const sites = all[name]?.sites;
+        if (wanted !== undefined)
+            assertWorkspacesExist(wanted, limit.exists);
+        const workspaces = wanted !== undefined ? (wanted ?? undefined) : all[name]?.workspaces;
         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] = sealRecord(tenant, workspace, name, plainCert, { kind: "client-cert", sites }, all[name]?.v === 2 || writeBound());
+        all[name] = sealRecord(tenant, workspace, name, plainCert, { kind: "client-cert", sites, workspaces }, all[name]?.v === 2 || workspaces !== undefined || writeBound());
         return all;
     });
 }
 const IDENTITY_PREFIX = "@identity ";
-export function setIdentitySecret(tenant, name, config, workspace) {
+export function setIdentitySecret(tenant, name, config, workspace, limit = {}) {
     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");
+    setSecret(tenant, name, IDENTITY_PREFIX + JSON.stringify({ audience }), workspace, "identity", limit);
 }
 export function isIdentityValue(value) {
     return value.startsWith(IDENTITY_PREFIX);
@@ -1021,7 +1285,7 @@ export function basicAuthorization(username, 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) {
+export function setApiSecret(tenant, name, config, workspace, limit = {}) {
     let all = { ...(config.headers ?? {}) };
     if (config.basic) {
         if (Object.keys(all).some((h) => h.toLowerCase() === "authorization")) {
@@ -1056,7 +1320,7 @@ export function setApiSecret(tenant, name, config, workspace) {
     const base = config.base_url?.trim();
     if (base && !/^https?:\/\//.test(base))
         throw new Error("base_url must be http(s)");
-    setSecret(tenant, name, API_PREFIX + JSON.stringify({ ...(base ? { base_url: trimSlashes(base) } : {}), headers: config.headers }), workspace, "api");
+    setSecret(tenant, name, API_PREFIX + JSON.stringify({ ...(base ? { base_url: trimSlashes(base) } : {}), headers: config.headers }), workspace, "api", limit);
 }
 export function isApiValue(value) {
     return value.startsWith(API_PREFIX);
@@ -1094,7 +1358,7 @@ export function sealVaultBindings(tenant) {
             const next = { ...all };
             for (const [name, value] of plain) {
                 const rec = all[name];
-                next[name] = sealRecord(tenant, workspace, name, value, { kind: rec.kind, sites: rec.sites, updatedAt: rec.updatedAt }, true);
+                next[name] = sealRecord(tenant, workspace, name, value, { kind: rec.kind, sites: rec.sites, workspaces: rec.workspaces, updatedAt: rec.updatedAt }, true);
             }
             sealed += plain.size;
             return next;
@@ -1142,7 +1406,7 @@ export function rewrapTenantSecrets(tenant) {
                 return null;
             const next = { ...all };
             for (const [name, value] of plain) {
-                next[name] = sealRecord(tenant, workspace, name, value, { kind: all[name].kind, sites: all[name].sites, updatedAt: all[name].updatedAt }, all[name].v === 2 || writeBound());
+                next[name] = sealRecord(tenant, workspace, name, value, { kind: all[name].kind, sites: all[name].sites, workspaces: all[name].workspaces, updatedAt: all[name].updatedAt }, all[name].v === 2 || writeBound());
             }
             moved += plain.size;
             return next;

package/dist/src/starter.js

@@ -373,6 +373,7 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/export\` · \`/import\` | GET · POST | the workspace, a flow (\`?kind=flow&name=\`) or an agent as a .zip; take one in (\`?dryRun=1\` first, \`?overwrite=1\` to replace) |
 | \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
+| \`/a2a\` | GET | what it serves to outside agents over A2A: flows that say \`a2a:\`, card URLs, recent tasks |
 | \`/check\` | GET | what \`foldrun check\` says about the deployed copy, as findings with rule ids (\`?security=1\`) |
 | \`/assistant\` | POST | ask the assistant, or have it write agents, flows, tools and skills — from the docs only; proposals come back, nothing is written |
 
@@ -382,7 +383,8 @@ Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/
 \`/api/me/inbox\` (what waits on you: gates, questions, issues, proposed fixes, your failed runs),
 \`/api/account/backups\` (snapshots, restore requests), \`/api/me/onboarding\` (getting started),
 \`/api/healthz\` and \`/api/version\` (open), \`/api/changelog\` (release notes)
-and \`/api/metrics\` (Prometheus).
+and \`/api/metrics\` (Prometheus). Outside \`/api\`: \`/a2a/<account>/<ws>/flows/<flow>\`
+(a published flow's agent card and A2A 1.0 JSON-RPC endpoint — an A2A key only, \`foldrun docs a2a\`).
 
 Every call answers — and the CLI sends — \`Foldrun-Version: YYYY-MM-DD\` (dated API
 versions; an account pin in Settings → API), \`X-RateLimit-*\` headers (a \`429\`
@@ -418,6 +420,7 @@ effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
 priority: normal         # high | normal | low — where its runs stand in the queue
 compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }  # optional: what one run may hold at once
+a2a: { publish: false }  # true: outside agents may call it over A2A (admin only; callers need an A2A key)
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.
@@ -483,6 +486,7 @@ hooks: [no-force-push]      # from hooks/ or the library: code at every tool cal
 scripts: [summarise.py]     # from scripts/, each becomes a callable tool
 apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
+remotes: []                 # outside A2A agents [{name, card, secret?}] — the a2a_send/status/reply/cancel tools
 agents: [writer]            # colleagues this one may consult (an answer, no tools)
 subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
 sandbox: own                # delegated to: run each job in its own sandbox (own tools, secrets, network)

package/dist/src/store.d.ts

@@ -14,6 +14,8 @@ import { frontmatterErrorText } from "./matter.ts";
  * the runtime, and there is nothing to fail to import.
  */
 export declare function readFrontmatter(file: string): Record<string, unknown>;
+import { type A2aPublication } from "./a2a-publish.ts";
+import { type RemoteSpec } from "./a2a-remotes.ts";
 import { type NetworkPolicy } from "./network.ts";
 import { type WireFormat, type AuthShape } from "./providers.ts";
 /**
@@ -306,6 +308,9 @@ export interface AgentInfo {
     effort: string | null;
     tools: string[];
     apis: ApiSpec[];
+    /** `remotes:` — the outside A2A agents it may call, the entries that read
+     *  (a2a-remotes.ts). Never a token: names, card URLs, secret NAMES. */
+    remotes?: RemoteSpec[];
     /** The author's own tools named in `tools:` — the subset that is not a
      *  built-in. Same list as `tools`, minus what the runtime provides. */
     ownTools: string[];
@@ -652,6 +657,10 @@ export interface FlowInfo {
     owner: string | null;
     /** Which of the three `owner` came from. */
     ownerFrom: OwnerSource | null;
+    /** `a2a:` — whether outside agents may call this flow over A2A, and what
+     *  its agent card says (a2a-publish.ts). Null when absent or unreadable:
+     *  a block with a problem publishes nothing. */
+    a2a?: A2aPublication | null;
     /** Flow-level frontmatter values the parser could not read — a bad
      *  `overlap:`/`priority:`/`catchup:`/`on:`/`signature:`, or a step line
      *  whose `[[target]]` is malformed. Errors, the way a bad step option is,
@@ -1445,6 +1454,11 @@ export interface RunRecord {
      *  expressed only as a status, because "failed" and "someone stopped it"
      *  are different facts and the trace should not conflate them. */
     stopRequested?: boolean;
+    /** Who stopped it, as the trail says it, when that was not a person
+     *  stopping it from the dashboard, the CLI or the API: "A2A caller
+     *  <key label>" for an A2A CancelTask (1 Nov 2026). Absent: a person.
+     *  Written by stopRun beside stopRequested, carried the same way. */
+    stoppedBy?: string;
     /**
      * What this run concluded, in one line — the first line of the last step
      * that produced a result, captured when the run finishes.
@@ -1523,6 +1537,17 @@ export interface RunRecord {
      *  step of this run — never the tokens. A link is good once; the second
      *  click is a 409, not a second approval. Written by approvals.ts. */
     approvalLinksUsed?: string[];
+    /** What started it, when that is not a person, a schedule or an event the
+     *  flow's own trigger names: "a2a" — an outside agent, over A2A (1 Nov
+     *  2026). Absent for every other run. */
+    trigger?: "a2a";
+    /** For an A2A run: the A2A task it serves and the id of the A2A key (its
+     *  first id, kept across rotations) that asked. A correlation only — the
+     *  protocol's own state lives in the platform's a2a_tasks. */
+    a2a?: {
+        task: string;
+        key: string;
+    };
     steps: StepRecord[];
 }
 /** Merge one part (the input, on the call; the output, on its completion)
@@ -1643,6 +1668,12 @@ export interface RunSummary {
     revision?: string | null;
     /** A step is parked for a person — what the approvals banner counts. */
     awaitingApproval: boolean;
+    /** RunRecord.trigger and .a2a: an outside agent started it. */
+    trigger?: "a2a";
+    a2a?: {
+        task: string;
+        key: string;
+    };
     steps: RunSummaryStep[];
 }
 /** One run's row. */
@@ -1661,6 +1692,9 @@ export declare function listRunSummaries(tenant: string, workspace: string): Run
 export declare function listAllRunSummaries(tenant: string): (RunSummary & {
     workspace: string;
 })[];
+/** Who stopped a run, for a trail line: "a person" unless stopRun was told
+ *  otherwise (RunRecord.stoppedBy). */
+export declare function stoppedByText(run: Pick<RunRecord, "stoppedBy"> | null | undefined): string;
 /**
  * The status a person should see. "failed" and "someone stopped it" are
  * different facts — the record keeps them apart (stopRequested), and the