foldrun 2.4.0 → 2.5.0

package/bin/foldrun.mjs

@@ -183,6 +183,7 @@ const HELP = `foldrun — agents are just folders
   foldrun billing card      Stripe's page for saving a card for auto top-up (owner only)
   foldrun billing credit <usd>  put credit on the balance by hand (--note "…") — only on an install without Stripe (self-hosted, dev); refused once billing is live
   foldrun gallery           the platform's built-in tools (web) and whether you keep your own copy — also pull (a copy for offline runs), upgrade <tool>
+  foldrun identity          what your cloud must trust for keyless identities: the issuer and each agent's subject (--to <workspace>, --json)
   foldrun jobs              the four jobs — governance, guardrail, observability, evaluation — and what each has set (--to <workspace>, --json)
   foldrun account           the account's defaults — also set <key> <value>, clear <key> (timezone, notify, budget, concurrency, deploy_block none|secrets|security, network_enforce on|off, owner, alerts <threshold> <value>, judge model|effort <value>; or <job>.<field>, e.g. governance.owner), pause [--reason] [--stop] / resume (the kill switch), telemetry [set <url> --header name=\${SECRET} | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
   foldrun account export    everything the platform holds about the account as one JSON file (owner only; --file <path>, --force)
@@ -277,7 +278,7 @@ Options
   --on-fail <agent>         flow add: who takes the step over when it fails
   --off                     flow add: take the pattern off the step instead (fan-out, loop, approval, ask, wait, rescue)
   --schedule "<cron>"       flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
-  --kind <k>                secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file or a prompted password), api (--base-url, --header "Name: value" repeatable), service-account (--file <key.json>, --scopes), m2m (--token-url, --client-id, --scopes; secret prompted)
+  --kind <k>                secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file or a prompted password), api (--base-url, --header "Name: value" repeatable, or --basic-user <u> with the password prompted or --basic-password), service-account (--file <key.json>, --scopes, --subject <user to act as>), client-cert (--cert-file, --key-file, --passphrase, --export to put it in the sandbox as files too), identity (--audience: keyless cloud access, no credential stored), m2m (--token-url, --client-id, --scopes; secret prompted)
   --client <name>           connect: run the consent from that OAuth client saved on the platform (secrets clients lists them)
   --subagent <name>         agent link, agent unlink: a worker it delegates to (subagents:)
   --consult <name>          agent link, agent unlink: a colleague it asks (agents:)
@@ -334,7 +335,9 @@ Options
   --from <n>                invoke, flow run, rerun: start at step n; earlier steps are recorded as skipped (a bulk rerun defaults to 1)
   --no-browser              login, connect, billing top-up/card/plan: print the address instead of opening it
   --provider <name>         connect: google, github, microsoft or linkedin (fills the URLs)
-  --scopes "<a b c>"        connect: space-separated scopes (default: the provider's example)
+  --no-pkce                 connect, secrets clients add: leave PKCE off (only for an app with a secret whose provider refuses it)
+  --issuer <url>            secrets clients add: the provider's issuer, checked against the iss it sends back (RFC 9207)
+  --scopes "<a b c>"        connect: space-separated scopes (default: the provider's example; with --client, the saved client's default — the connection keeps the ones asked for)
   --client-id / --client-secret  connect: the OAuth app (prompted if omitted; secret never echoed)
   --port <n>                connect: loopback port for the redirect (default 8642 — register http://localhost:8642/callback on the app)
   --authorize-url / --token-url  connect: a provider with no preset
@@ -381,7 +384,7 @@ if (!command || command === "--help" || command === "-h") {
 // `--value` as the account's argument and stored an empty secret; `--force
 // ./dir` swallowed the directory. A flag followed by another flag is also
 // boolean, so an unlisted switch at least does not eat its neighbour.
-const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last"]);
+const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export"]);
 // Flags said more than once collect into a list: `--tag a --tag b`.
 const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule"]);
 // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes

package/docs/api.md

@@ -319,7 +319,7 @@ its header and requires a URL it can GET for itself.
 | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
 
 `PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
-a cert), `oauth2`, `service_account`, `ssh`, or `api`. They go to the vault;
+a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;
 agents name them in `secrets:` and never see them in a file.
 
 Reads return which secrets exist, never their values.
@@ -463,9 +463,11 @@ signed-in person, never by a key — mints an ordinary API key at their role.
 | Route | Methods | |
 |---|---|---|
 | `/api/oauth/clients` | GET, POST, DELETE | registered providers (`name`, `client`, `config`) |
-| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`) |
-| `/api/oauth/callback` | GET | where the provider returns |
-| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`) → `{ url }` |
+| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`, optional `scopes`). From a signed-in browser: `{ url }` is the provider's consent, bound to that browser by a cookie the callback checks, with PKCE. With an API key: `{ url, handoff: true }` is a dashboard page where a signed-in person accepts first (`foldrun connect --client` opens it). `scopes` (space-separated, as the provider spells them) is what this connection asks for instead of the client's default, and the connection keeps it for its reconnects — one saved app serves any number of connections at different scopes |
+| `/api/oauth/callback` | GET | where the provider returns — refuses a consent that comes back to another browser, and an `iss` that is not the app's issuer |
+| `/api/identity?workspace=` | GET | keyless cloud identity: `{ enabled, issuer, subject, tokenSeconds }` — the issuer a cloud must trust and the subject pattern each agent's tokens carry (`account:<a>:workspace:<w>:agent:<agent>`). Open (no key), outside `/api`: `/.well-known/openid-configuration` and `/.well-known/jwks.json`, 404 when the install does not issue tokens |
+| `/api/oauth/handoff/<id>` | POST | accept a connection started from a terminal: a signed-in person only, never a key; answers `{ url }`, the provider's consent bound to this browser. Used once, ten minutes |
+| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`, optional `scopes`) → `{ url }`; it asks for `scopes` when given, else the scopes the secret was connected with, else the client's default |
 | `/api/oauth/connections` | GET | each oauth2 secret's grant: saved client, `status` (ok, expiring, expired, failed, no-client), days left, last error |
 
 ## Triggers

package/docs/cli.md

@@ -96,10 +96,10 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
 | `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `--site <domain>` (repeatable, or `a,b`) binds it as it is stored |
 | `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
-| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable), `service-account` (`--file <key.json>`, `--scopes`), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
+| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `secrets sites`), `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
 | `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --provider google\|github\|microsoft\|linkedin` (or `--authorize-url` / `--token-url`) `--client-id … --scopes …` saves one (secret prompted), `clients rm <name>` removes it |
-| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--provider google\|github\|microsoft\|linkedin`; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
-| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
+| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--provider google\|github\|microsoft\|linkedin`; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
+| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
 | `foldrun deploy [dir]` | push this account into an installation — every workspace and the shared library. `foldrun deploy <workspace>` pushes one. Never removes a workspace the platform has and the folder does not. It first prints where it is going and as whom (`deploying to <url> as <profile> (<email>)`); a deploy that would delete files the folder no longer has lists them and asks — what runs wrote (`storage/`, `state/`, the trigger log) is never deleted, so never listed. The confirmed list goes with the deploy; if the platform would now remove anything else it refuses and the CLI asks again. With no terminal (a script, a CI job, a coding agent) it refuses unless `--yes`. A deploy that only adds or changes files asks nothing |
 | `foldrun help <command>` | that command's usage and options. `foldrun <command> --help` and `-h` print the same and never run the command |
 | `foldrun pull [workspace]` | bring the platform's account down into this folder — refuses to overwrite a locally edited file, and names every one it would have taken (`--force` takes them) |
@@ -142,6 +142,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
 | `foldrun billing credit <usd>` | put credit on the balance by hand (`POST /api/billing { usd, note }`, `--note "…"` on the ledger line) — only on an install without Stripe, a self-hosted or dev platform; once billing is live the platform refuses it and top-ups go through `billing top-up`. The dashboard's Billing → Add credit does the same while billing is off. Needs `billing:manage` |
 | `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
+| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
 | `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
 | `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is the account's own model key, what every step runs on unless a `provider:` block names another: `foldrun account model` shows it (never the key, only its last four; exit 1 when there is none and runs are refused), `model set <provider> --key <api key>` sets it — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it; a Claude login token is refused for any account not allowed the platform's own credential. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
 | `foldrun workspace` | one deployed workspace's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `set owner`, `set alerts <threshold> <value>`, `set judge model|effort <value>`, and `<job>.<field>` as on `account`, `pause` (`--reason`, `--stop`) and `resume` — this workspace's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |

package/docs/secrets.md

@@ -30,9 +30,36 @@ PUT /api/secrets   { "name": "STRIPE_KEY", "value": "sk_live_…" }
 | `file` | a PEM, a certificate, a service-account JSON |
 | `oauth2` | a connected third-party account (see below) |
 | `service_account`, `ssh`, `api` | structured credentials the platform knows how to present |
+| `client_cert` | a certificate and key for mutual TLS, presented by the egress proxy |
+| `identity` | keyless cloud access: an audience, and tokens the platform signs (below) |
 
 Reads return which secrets exist, never their values.
 
+A **service account** is a key file that signs its own token request. It
+acts as itself, or — with **Act as** (`subject`) — as a user the provider
+lets it act for (RFC 7523's grant subject; for Google, domain-wide
+delegation, which a Workspace admin grants in their own console). Each
+subject gets its own token.
+
+An **`api`** connection is a base URL and the headers that go with it. For
+an old system that wants **HTTP Basic**, give a username and password
+instead of an `Authorization` header: the platform builds the header (RFC
+7617, UTF-8), refuses a colon in the username, needs an https base URL, and
+masks the password and the encoded header in every trace — as it does every
+header value of an `api` connection.
+
+A **client certificate** (mutual TLS) is a PEM certificate, its key and an
+optional passphrase; the key must belong to the certificate or it is
+refused. Bind it to the **exact hosts** it is for (`foldrun secrets sites
+NAME api.bank.example` — no wildcards): the egress proxy presents it on its
+own connection to those hosts, and the sandbox never holds the key. Two
+certificates bound to one host is refused, not guessed. A redirect to
+another site never carries it. Unbound, it stays out of the sandbox; save it
+with **export** only for a step that runs without the egress proxy, and it
+arrives as files (`$NAME_CERT`, `$NAME_KEY`, `$NAME_PASSPHRASE_FILE`). This
+is client authentication with a certificate — not OAuth's certificate-bound
+tokens (RFC 8705), which foldrun does not do.
+
 ## Scopes
 
 A secret lives at the **account** or in one **workspace**. An agent looks in
@@ -173,6 +200,78 @@ anything OAuth. Settings → Connections walks the consent flow once and stores
 the result as an `oauth2` secret; the platform refreshes it. An agent names
 it in `secrets:` like any other.
 
+You bring the OAuth app: register it once with the provider (its client id
+and secret, and the redirect URL the form shows), save it, and connect. Every
+later connection can use the same saved app — choose it under **App** and
+type the scopes this connection needs, as the provider spells them. Each
+connection keeps its own scopes, so one app serves any number of APIs from
+the same provider (an ads API in one secret, a search API in another), and
+**Reconnect** asks for that connection's scopes again. The provider decides
+what the app may ask for; foldrun only carries the words. From a terminal:
+`foldrun connect NAME --client <saved app> --scopes "<scopes>" --to <workspace>`.
+
+How a connection is kept safe, whatever the provider:
+
+- **PKCE** (S256) is on for every connection: a code stolen on its way back
+  is useless without the verifier only foldrun holds. An app with no client
+  secret (a *public* app) is allowed — PKCE is then what protects it, and
+  its refreshes send no secret. Turn PKCE off only for an app with a secret
+  whose provider refuses the parameters.
+- **The browser that starts a connection is the one it must come back to.**
+  The consent link carries a cookie the callback checks; a link opened in
+  someone else's browser connects nothing.
+- **From a terminal**, `foldrun connect --client` opens a page in the
+  dashboard where you, signed in, see the secret, the app, the scopes and
+  where it will be stored, and accept before the provider is asked.
+- **Issuer.** Give a saved app its provider's issuer and the `iss` the
+  provider sends back (RFC 9207) must match it; without one, a returned
+  `iss` must at least be the authorize URL's own site.
+- The flow's own parameters (`client_id`, `redirect_uri`, `scope`, `state`,
+  the PKCE pair) cannot be overridden by extra parameters or by a query
+  string in the authorize URL.
+- A provider that **rotates refresh tokens** sends a new one with each
+  refresh; it replaces the old one in the vault, where that secret is kept.
+
+## Keyless cloud identity
+
+The safest credential is none at all. A cloud that supports workload
+identity federation — AWS (`AssumeRoleWithWebIdentity`), Google Cloud
+(Workload Identity Federation), Microsoft Entra (federated credentials) —
+can trust **foldrun's signature** instead of a key you store: a step proves
+which account, workspace and agent it is, and the cloud gives it a
+short-lived credential of its own.
+
+1. In your cloud, trust this install as an OIDC provider: its issuer is
+   shown by `foldrun identity` (and in the Connections form). Pin the
+   subject — `account:<account>:workspace:<workspace>:agent:<agent>` — at
+   least to your account, and the audience you choose.
+2. `foldrun secrets set AWS_ID --kind identity --audience sts.amazonaws.com`
+   (or Connections → Identity). Nothing secret is stored: only the audience.
+3. Name it in an agent's `secrets:`. The step gets **`$AWS_ID_FILE`**: a
+   token signed RS256, valid ten minutes, renewed while the step runs. Point
+   your cloud's SDK at it — for AWS, `AWS_ROLE_ARN` and
+   `AWS_WEB_IDENTITY_TOKEN_FILE=$AWS_ID_FILE`; for Google, an
+   `external_account` credential file whose `credential_source.file` is it;
+   for Entra, the token as the client assertion.
+
+What it is and is not:
+
+- A **workload-federation issuer**, not a sign-in provider: discovery
+  publishes what federation reads (issuer, JWKS, RS256, public subjects),
+  and nothing more.
+- The subject and claims come from the platform's own record of the run,
+  never from the sandbox. A token is issued only to the step the identity
+  was granted to, only while its driver checks in, and never after the step
+  stops or ends.
+- Stopping a step stops renewal; it cannot recall a token already issued,
+  which expires within ten minutes on its own.
+- Within an account, a workspace or agent recreated under the same name
+  is the same subject: pin your trust policy to the account at least.
+- Who may run or edit an agent that names the identity may use it — as
+  with every secret.
+- Not on a laptop: only a sandboxed step on a platform whose operator set
+  `FOLDRUN_OIDC_ISSUER` gets a token.
+
 ## How they are kept
 
 Every account has its own encryption key. Secrets are sealed under it, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^2.6.0"
+    "@foldrun/core": "^2.7.0"
   },
   "files": [
     "bin",

package/src/commands.mjs

@@ -3674,8 +3674,11 @@ async function connect(positional, flags) {
   }
 
   const clientId = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
-  const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
-  if (!clientId || !clientSecret) throw new Error("client_id and client_secret are required");
+  const pkce = flags["no-pkce"] !== true;
+  const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden(`  client_secret${pkce ? " (empty for a public app)" : ""}: `));
+  if (!clientId) throw new Error("client_id is required");
+  // No secret is a public app, which PKCE alone protects (RFC 9700 §2.1.1).
+  if (!clientSecret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
   const scopes = flags.scopes ?? preset?.scopes_example ?? "";
 
   // One fixed loopback address, the same on every developer's machine, so an
@@ -3691,13 +3694,21 @@ async function connect(positional, flags) {
   const crypto = await import("node:crypto");
   const http = await import("node:http");
   const state = crypto.randomBytes(24).toString("hex");
+  // PKCE (RFC 7636, S256): 32 random bytes as the verifier, its hash as the challenge.
+  const verifier = pkce ? crypto.randomBytes(32).toString("base64url") : null;
   const authorize = new URL(authorizeUrl);
+  // Extras first: the flow's own parameters are set after, and win.
+  for (const [k, v] of Object.entries(preset?.authorize_extra ?? {})) authorize.searchParams.set(k, v);
+  for (const k of ["client_id", "redirect_uri", "response_type", "scope", "state", "code_challenge", "code_challenge_method"]) authorize.searchParams.delete(k);
   authorize.searchParams.set("response_type", "code");
   authorize.searchParams.set("client_id", clientId);
   authorize.searchParams.set("redirect_uri", redirectUri);
   authorize.searchParams.set("state", state);
   if (scopes) authorize.searchParams.set("scope", scopes);
-  for (const [k, v] of Object.entries(preset?.authorize_extra ?? {})) authorize.searchParams.set(k, v);
+  if (verifier) {
+    authorize.searchParams.set("code_challenge", crypto.createHash("sha256").update(verifier).digest("base64url"));
+    authorize.searchParams.set("code_challenge_method", "S256");
+  }
 
   // One request, then the listener closes. The state is the whole authority:
   // a callback with any other value is answered and ignored.
@@ -3733,7 +3744,11 @@ async function connect(positional, flags) {
   const exchange = await fetch(tokenUrl, {
     method: "POST",
     headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
-    body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, client_secret: clientSecret }).toString(),
+    body: new URLSearchParams({
+      grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId,
+      ...(clientSecret ? { client_secret: clientSecret } : {}),
+      ...(verifier ? { code_verifier: verifier } : {}),
+    }).toString(),
   });
   const payload = /** @type {any} */ (await exchange.json().catch(() => ({})));
   if (!exchange.ok || (!payload.refresh_token && !payload.access_token)) {
@@ -3743,7 +3758,7 @@ async function connect(positional, flags) {
   // Store: the refresh recipe when there is one, the bare token otherwise.
   /** @type {any} */
   const body = payload.refresh_token
-    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, client_secret: clientSecret, refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
+    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}), refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
     : { name, value: payload.access_token, workspace: workspaceName };
   if (url) {
     // The same PUT `secrets set` makes. A store that fails here has spent the
@@ -5738,6 +5753,30 @@ function shortValue(v) {
   return typeof v === "object" ? JSON.stringify(v).replace(/"([a-z_]+)":/g, "$1: ").replace(/,/g, ", ") : String(v);
 }
 
+/**
+ * `foldrun identity [--to <workspace>]` — what a cloud must trust to accept
+ * this account's keyless identities: the issuer, and each agent's subject.
+ */
+async function identityCmd(flags) {
+  const url = platformFor(flags, "identity");
+  const ws = typeof flags.to === "string" ? flags.to : null;
+  const info = await remoteCall(url, flags, `/api/identity${ws ? `?workspace=${enc(ws)}` : ""}`);
+  if (flags.json === true) {
+    console.log(JSON.stringify(info, null, 2));
+    return 0;
+  }
+  if (!info.enabled) {
+    console.log(`\n  ${c.yellow("This install does not issue identity tokens")} ${c.dim("— its operator sets FOLDRUN_OIDC_ISSUER")}\n`);
+    return 1;
+  }
+  console.log(`\n  ${c.bold("Keyless cloud identity")}\n`);
+  console.log(`  issuer   ${info.issuer}`);
+  console.log(`  subject  ${info.subject}`);
+  console.log(`  tokens   ${Math.round(info.tokenSeconds / 60)} minutes, renewed while a step runs`);
+  console.log(`\n  ${c.dim("Trust the issuer in your cloud and pin at least the account in the subject; then `foldrun secrets set NAME --kind identity --audience <aud>` and name it in an agent's secrets:")}\n`);
+  return 0;
+}
+
 /**
  * `foldrun jobs [--to <workspace>]` — the four jobs and every AGENTS.md
  * field of each: the account's value, the workspace's, and how the two
@@ -10493,9 +10532,17 @@ async function oauthClientsCmd(positional, flags) {
     const token_url = flags["token-url"] ?? preset?.token_url;
     if (!authorize_url || !token_url) throw new Error("--provider, or both --authorize-url and --token-url");
     const client_id = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
-    const client_secret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
-    if (!client_id || !client_secret) throw new Error("client_id and client_secret are required");
-    const config = { authorize_url, token_url, client_id, client_secret, scopes: flags.scopes ?? preset?.scopes_example ?? "", ...(preset?.authorize_extra ? { authorize_extra: preset.authorize_extra } : {}) };
+    const pkce = flags["no-pkce"] !== true;
+    const client_secret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden(`  client_secret${pkce ? " (empty for a public app)" : ""}: `));
+    if (!client_id) throw new Error("client_id is required");
+    if (!client_secret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
+    if (flags.issuer !== undefined && (typeof flags.issuer !== "string" || !/^https:\/\/[^?#]+$/.test(flags.issuer))) throw new Error("--issuer is the provider's https issuer URL, no query or fragment");
+    const config = {
+      authorize_url, token_url, client_id, client_secret: client_secret ?? "", scopes: flags.scopes ?? preset?.scopes_example ?? "",
+      ...(preset?.authorize_extra ? { authorize_extra: preset.authorize_extra } : {}),
+      ...(pkce ? {} : { pkce: false }),
+      ...(typeof flags.issuer === "string" ? { issuer: flags.issuer } : {}),
+    };
     await remoteCall(url, flags, "/api/oauth/clients", { method: "POST", body: JSON.stringify({ name, config }) });
     console.log(`\n  ${c.green("✓")} saved ${name} ${c.dim(`— \`foldrun connect NAME --client ${name}\` runs a consent from it`)}\n`);
     return 0;
@@ -10512,9 +10559,15 @@ async function connectFromClient(name, flags) {
   const url = platformFor(flags, "connect --client");
   const workspace = typeof flags.to === "string" ? flags.to : undefined;
   const before = (await remoteCall(url, flags, "/api/oauth/connections")).connections?.find((s) => s.name === name && (s.workspace ?? undefined) === workspace)?.connectedAt ?? null;
-  const started = await remoteCall(url, flags, "/api/oauth/start", { method: "POST", body: JSON.stringify({ client: flags.client, secret: name, ...(workspace ? { workspace } : {}) }) });
+  // --scopes: this connection's own, instead of the saved client's default;
+  // the platform keeps them with the connection for its reconnects.
+  const scopes = typeof flags.scopes === "string" && flags.scopes.trim() ? { scopes: flags.scopes } : {};
+  const started = await remoteCall(url, flags, "/api/oauth/start", { method: "POST", body: JSON.stringify({ client: flags.client, secret: name, ...(workspace ? { workspace } : {}), ...scopes }) });
   const opened = flags["no-browser"] === true || !process.stdout.isTTY ? false : await openInBrowser(started.url);
-  console.log(opened ? `\n  Opened your browser to consent with the saved ${c.bold(flags.client)} client.\n` : `\n  Open this address in your browser:\n\n    ${started.url}\n`);
+  // The platform answers a hand-off page: a signed-in person accepts the
+  // connection there, then the provider's consent runs in that browser.
+  const what = started.handoff ? "accept the connection, then consent" : "consent";
+  console.log(opened ? `\n  Opened your browser to ${what} with the saved ${c.bold(flags.client)} app.\n` : `\n  Open this address in your browser to ${what}:\n\n    ${started.url}\n`);
   console.log(`  ${c.dim("Waiting for the platform to store it…")}`);
   const deadline = Date.now() + 10 * 60 * 1000;
   while (Date.now() < deadline) {
@@ -10549,7 +10602,11 @@ async function secretOfKind(kind, flags) {
     }
     case "api": {
       const lines = [].concat(flags.header ?? []);
-      if (!lines.length) lines.push(await promptHidden("  header (Name: value): "));
+      // --basic-user: HTTP Basic from a username and password (prompted, or
+      // --basic-password); the platform builds the Authorization header.
+      const basicUser = typeof flags["basic-user"] === "string" ? flags["basic-user"] : null;
+      const basic = basicUser ? { basic: { username: basicUser, password: typeof flags["basic-password"] === "string" ? flags["basic-password"] : await promptHidden("  password: ") } } : {};
+      if (!lines.length && !basicUser) lines.push(await promptHidden("  header (Name: value): "));
       const headers = Object.fromEntries(
         lines.filter(Boolean).map((l) => {
           const i = String(l).indexOf(":");
@@ -10558,7 +10615,23 @@ async function secretOfKind(kind, flags) {
         }),
       );
       const base = typeof flags["base-url"] === "string" ? { base_url: flags["base-url"] } : {};
-      return { body: { api: { ...base, headers } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
+      return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
+    }
+    case "identity": {
+      // A keyless cloud identity: only the audience; the platform signs the
+      // tokens (`foldrun identity` prints what the cloud must trust).
+      if (typeof flags.audience !== "string" || !flags.audience.trim()) throw new Error("--kind identity needs --audience <value your cloud's trust expects in aud>");
+      return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s) => k.setIdentitySecret("default", n, b.identity, s) };
+    }
+    case "client-cert": {
+      // A client certificate for mutual TLS. Bind it to the exact hosts it is
+      // for with `foldrun secrets sites NAME host`; the egress proxy presents
+      // it there. --export also puts it in the sandbox as files.
+      const cert = read(flags["cert-file"], "--cert-file <cert.pem> — the certificate, chain included");
+      const key = read(flags["key-file"], "--key-file <key.pem> — its private key");
+      const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
+      const client_cert = { cert, key, ...(passphrase ? { passphrase } : {}), ...(flags.export === true ? { export: true } : {}) };
+      return { body: { client_cert }, local: (k, n, b, s) => k.setClientCertSecret("default", n, b.client_cert, s) };
     }
     case "service-account": {
       let j;
@@ -10568,7 +10641,9 @@ async function secretOfKind(kind, flags) {
         if (err instanceof SyntaxError) throw new Error(`${flags.file} is not JSON — the key file Google gives you`);
         throw err;
       }
-      const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "" };
+      // --subject: the user it acts as (domain-wide delegation, granted by the
+      // provider's admin); without it the account acts as itself.
+      const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "", ...(typeof flags.subject === "string" ? { subject: flags.subject } : {}) };
       return { body: { service_account: sa }, local: (k, n, b, s) => k.setServiceAccountSecret("default", n, b.service_account, s) };
     }
     case "m2m": {
@@ -10579,7 +10654,7 @@ async function secretOfKind(kind, flags) {
       return { body: { oauth2 }, local: (k, n, b, s) => k.setOAuth2Secret("default", n, b.oauth2, s) };
     }
     default:
-      throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account or m2m (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
+      throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account, m2m, client-cert or identity (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
   }
 }
 
@@ -11235,6 +11310,8 @@ export async function run(command, positional, flags, workspace, layout) {
       return rerunCmd(positional[0], flags, layout);
     case "account":
       return accountCmd(positional, flags);
+    case "identity":
+      return identityCmd(flags);
     case "jobs":
       return jobsCmd(flags, layout);
     case "schedule":