@foldrun/core 9.0.0 → 9.2.0

package/dist/src/secrets.d.ts

@@ -31,12 +31,27 @@ interface StoredSecret {
      *  these sites alone. Metadata, not a value, so it is stored in the clear
      *  beside the ciphertext and survives the value being set again. */
     sites?: string[];
+    /** An ACCOUNT secret limited to these workspaces (GitHub's "selected
+     *  repositories" for an organisation secret). Absent: every workspace may
+     *  use it, as before. Every other workspace is answered as if it were not
+     *  set (getSecret). Metadata like `sites`: in the clear, and in the seal
+     *  of a bound record. Never on a workspace's own record. */
+    workspaces?: string[];
     /** 2: sealed with the record's place as AAD — account, scope, name, kind,
-     *  key and sites (vaultAad). Absent: the older, unbound form. */
+     *  key, sites and, when limited, workspaces (vaultAad). Absent: the older,
+     *  unbound form. */
     v?: 2;
 }
 type SecretsFile = Record<string, StoredSecret>;
 declare const writeBound: () => boolean;
+/**
+ * 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 declare function lockFileExclusive(file: string, busy?: string): () => void;
 /**
  * Change one vault file safely: `change` gets what is stored now and returns
  * the new contents, or null to leave the file untouched. Returns what is
@@ -44,7 +59,30 @@ declare const writeBound: () => boolean;
  */
 export declare function mutateVaultFile(file: string, change: (all: SecretsFile) => SecretsFile | null): SecretsFile;
 export declare const SECRET_NAME: RegExp;
-export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind): void;
+/**
+ * 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 declare function signingSecretShown(name: string): string;
+/**
+ * Which workspaces an ACCOUNT secret may be used in, given with the value so
+ * both are sealed in one locked write (30 Oct 2026): a new secret created
+ * and limited in two calls was open to every workspace between them, and
+ * stayed open if the second failed. `workspaces` undefined keeps what the
+ * record has; null opens it to every workspace; a list limits it.
+ * `exists` is asked about each name under the vault lock, so a workspace
+ * deleted meanwhile is not granted (the delete takes its name off every
+ * list under the same lock — retargetSecretWorkspaces).
+ */
+export interface SecretLimit {
+    workspaces?: string[] | null;
+    exists?: (workspace: string) => boolean;
+}
+export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind, limit?: SecretLimit): void;
 /**
  * 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
@@ -71,11 +109,61 @@ export declare function decryptValue(tenant: string, rec: {
     data: string;
     k?: "tenant";
 } | undefined): string | null;
-/** 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 declare function getSecret(tenant: string, name: string, workspace?: string): {
     value: string;
     scope: SecretScope;
 } | null;
+/** 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 declare function accountSecretUsableIn(tenant: string, name: string, workspace: string): boolean;
+/**
+ * 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 declare function setSecretWorkspaces(tenant: string, name: string, workspaces: string[] | null, opts?: {
+    exists?: (workspace: string) => boolean;
+    ifWorkspaces?: string[] | null;
+}): string[] | null;
+/**
+ * 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 declare function retargetSecretWorkspaces(tenant: string, from: string, to: string | null): {
+    changed: string[];
+    failed: string[];
+};
 export declare function deleteSecret(tenant: string, name: string, workspace?: string): void;
 export interface SecretEntry {
     name: string;
@@ -89,6 +177,8 @@ export interface SecretEntry {
     /** The sites it is bound to — the proxy fills it for these and no other,
      *  and it never enters a sandbox. Absent when unbound. */
     sites?: string[];
+    /** An account secret limited to these workspaces; absent: every one. */
+    workspaces?: string[];
 }
 export declare function listSecrets(tenant: string, workspace?: string): SecretEntry[];
 export declare function resolveSecrets(tenant: string, names: string[], workspace?: string): {
@@ -154,7 +244,7 @@ export interface OAuth2Config {
 export declare const OAUTH_REFRESH_TRIES = 3;
 /** Wait before try n (1-based retry): 1s, 3s — FOLDRUN_OAUTH_RETRY_MS scales it for tests. */
 export declare function oauthRetryDelayMs(n: number): number;
-export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string): void;
+export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string, limit?: SecretLimit): void;
 export declare function isOAuth2Value(value: string): boolean;
 /**
  * The cache key for a live token: SHA-256 over the kind, the account and the
@@ -193,6 +283,28 @@ ctx?: {
      *  the stored value with the new refresh token. */
     onRotate?: (name: string, usedValue: string, next: string) => unknown;
 }): Promise<Record<string, string>>;
+/**
+ * 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 declare function materializeCurrent(env: Record<string, string>, scope?: {
+    tenant: string;
+    workspace?: string;
+} | null): Promise<Record<string, string>>;
 export interface ServiceAccountConfig {
     token_url: string;
     issuer: string;
@@ -205,8 +317,8 @@ export interface ServiceAccountConfig {
      *  a Workspace admin grants it. Absent, the account acts as itself. */
     subject?: string;
 }
-export declare function setServiceAccountSecret(tenant: string, name: string, config: ServiceAccountConfig, workspace?: string): void;
-export declare function setFileSecret(tenant: string, name: string, content: string, workspace?: string): void;
+export declare function setServiceAccountSecret(tenant: string, name: string, config: ServiceAccountConfig, workspace?: string, limit?: SecretLimit): void;
+export declare function setFileSecret(tenant: string, name: string, content: string, workspace?: string, limit?: SecretLimit): void;
 export declare function isFileValue(value: string): boolean;
 export declare function fileContent(value: string): string;
 export interface SshConfig {
@@ -217,7 +329,7 @@ export interface SshConfig {
     private_key?: string;
     password?: string;
 }
-export declare function setSshSecret(tenant: string, name: string, config: SshConfig, workspace?: string): void;
+export declare function setSshSecret(tenant: string, name: string, config: SshConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isSshValue(value: string): boolean;
 export declare function sshConfigOf(value: string): SshConfig;
 /** A client certificate for mutual TLS: presented by the egress proxy, on its
@@ -232,14 +344,14 @@ export interface ClientCertConfig {
     passphrase?: string;
     export?: boolean;
 }
-export declare function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string): void;
+export declare function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string, limit?: SecretLimit): void;
 /** 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 declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string): void;
+export declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isIdentityValue(value: string): boolean;
 export declare function identityOf(value: string): IdentityConfig;
 export declare function isClientCertValue(value: string): boolean;
@@ -260,7 +372,7 @@ export interface ApiConfig {
 /** `Authorization: Basic …` from a username and password (RFC 7617 §2):
  *  UTF-8, no colon in the username, no control characters in either. */
 export declare function basicAuthorization(username: string, password: string): string;
-export declare function setApiSecret(tenant: string, name: string, config: ApiConfig, workspace?: string): void;
+export declare function setApiSecret(tenant: string, name: string, config: ApiConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isApiValue(value: string): boolean;
 export declare function apiConfigOf(value: string): ApiConfig;
 /**