foldrun 5.0.0 → 5.0.2

package/docs/api.md

@@ -41,7 +41,7 @@ read (a deploy with issues, an `Idempotency-Key` reused with a different body),
 than the person who minted it, and opens every route below with that — except
 the ones that are about people: `/api/team` (invite, roles, scope, remove,
 transfer), `/api/auth/*` (profile, password, MFA, sessions), a user's
-`/api/avatars/user/<id>`, and the super admin console. Those need a signed-in
+`/api/avatars/user/<id>`. Those need a signed-in
 session and answer a key with `401` (a user's avatar answers a key with
 `403`: the key is read, then refused because it is not that person). Everything a workspace or an account
 *does* — files, runs, secrets, shares, schedules, hooks, storage, billing —
@@ -335,7 +335,7 @@ Reads return which secrets exist, never their values.
 
 | Route | Methods | |
 |---|---|---|
-| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap) |
+| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
 | `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404. Audited as `apikey.rotated` |
 | `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (bound into the invite: only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). Returns `path` (the invite's relative URL), `expires`, `sent` and any `sendError` either way; the full link is in the mail |
 | `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them |
@@ -404,7 +404,7 @@ person: a key names an account, never a who.
 | `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency` |
 | `/api/billing/plans` | GET | the catalogue (four plans: fee, credits, per-credit price, runs at once, workspaces, lane), where this account stands (plan, status, this cycle's credits and what is left, when it resets), the balance in dollars and credits, and any overdraft the platform has allowed |
 | `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter, creator, pro or scale. With no subscription yet, answers `url`: a Stripe Checkout in subscription mode; the return trip starts the first cycle. With a live one, changes it at Stripe at once, prorated (an upgrade is invoiced today and the bigger bundle lands with it; a downgrade comes back as credit on the next invoice), and answers `changed: true` — only once its prorated invoice is paid: when the payment needs the customer (a declined card, 3-D Secure) the change waits at Stripe as a pending update, nothing about the plan moves, and the answer is 402 `{ pending: true, payUrl }` — paying that invoice applies it; unpaid, Stripe drops it and voids the invoice after 23 hours. A plan set to stop and changed this way stays set to stop once paid — resuming it is the customer's own choice (`resume: true`); nothing resumes on its own. A plan set to stop at the period's end is still that live subscription: choosing a plan takes the stop off (and changes it if it is another plan) — never a second Checkout. With no subscription known here but one still billing at Stripe for the account's customer, 409: a second is not started. POST `resume: true` takes a pending cancellation off — nothing is charged and no cycle moves. DELETE ends the plan with the current cycle: the credits stand until then, and credits bought on top are kept |
-| `/api/billing/stripe` | POST | Stripe's webhook — signature-verified, not for you. Every delivery is logged (see `/api/admin/stripe-events`). Beside top-ups it turns plan cycles: one grant per (subscription, plan, period), whichever of the checkout, `invoice.paid` (either invoice shape) or `customer.subscription.updated` arrives first; `invoice.payment_failed` marks the plan past due and starts dunning (an email, a grace period, then new runs paused — see budgets-and-billing.md), `invoice.paid` and `invoice.voided` end it, `customer.subscription.deleted` ends the plan that subscription paid for — what is left of the bundle expires, the levers come off, money the customer added stays. `charge.refunded` debits a refunded top-up (never a plan fee), `charge.dispute.created` debits a chargeback and `charge.dispute.closed` returns it when won. Answers 500 — so Stripe redelivers — only when a lookup the event needs failed. The full event list is in budgets-and-billing.md |
+| `/api/billing/stripe` | POST | Stripe's webhook — signature-verified, not for you. Every delivery is logged. Beside top-ups it turns plan cycles: one grant per (subscription, plan, period), whichever of the checkout, `invoice.paid` (either invoice shape) or `customer.subscription.updated` arrives first; `invoice.payment_failed` marks the plan past due and starts dunning (an email, a grace period, then new runs paused — see budgets-and-billing.md), `invoice.paid` and `invoice.voided` end it, `customer.subscription.deleted` ends the plan that subscription paid for — what is left of the bundle expires, the levers come off, money the customer added stays. `charge.refunded` debits a refunded top-up (never a plan fee), `charge.dispute.created` debits a chargeback and `charge.dispute.closed` returns it when won. Answers 500 — so Stripe redelivers — only when a lookup the event needs failed. The full event list is in budgets-and-billing.md |
 
 ## Versions
 

package/docs/budgets-and-billing.md

@@ -198,7 +198,7 @@ and on the audit; it is a term, never a surprise.
 
 **Charges an account does not pay.** The platform can waive any of the three
 meters for one account: model tokens, sandbox time, network. It is set per
-account from the admin console, never as an install-wide rate, because a
+account by the platform, never as an install-wide rate, because a
 rate turned off globally would quietly stop charging every customer. The
 meters still run and the Usage page still shows everything measured; what
 changes is the bill. Every run still writes a ledger line — at zero when
@@ -390,26 +390,6 @@ runs, schedules stop firing — while the platform team settles the last
 invoice and any refund. Nothing is deleted by the request itself; people can
 still sign in and take the copy.
 
-## The admin console's money levers
-
-Each customer (account) in the super admin console has a Billing tab with
-every lever that changes what the customer pays, each behind a confirmation
-that names the amount and the account: **credit or debit** with a reason on
-the ledger (the console sends an idempotency key, so a double click is one
-line), **extend the trial** (more trial credits as a grant, with whatever
-trial credit is left carried into it; not for an account on a plan), the
-**plan** (grant a cycle by hand, end it, and the lane and limits that ride
-with it), **going into minus**, and **charges this account does not pay**.
-The overview beside it holds the contact on record (name, email, phone,
-company, ABN), notes, suspension, and the customer's Stripe customer and
-subscription with links into Stripe's own dashboard — test or live, read
-from the install's key.
-
-Revenue has a CSV per month for the accountant (`GET /api/admin/export`):
-one row per customer and a total, charges by leg, fees, top-ups, grants,
-expiries, refunds, disputes, adjustments and net, with Stripe's own figures
-for the month beside them when Stripe is connected.
-
 ## The wallet
 
 Usage is settled from a credit balance. Add credit by card, once or with
@@ -469,11 +449,7 @@ dispute-won, plan, trial, grant-expired, credits-expired — and lines written
 before the field have theirs derived from their key and note. Statements
 label lines by it. **Burn**, the 30-day spend and month-to-date count usage
 and the daily fees only — not expiries, refunds, chargebacks or an
-operator's debit. The admin console's **charged** figure is usage (runs and
-account pod sessions) in the customer list and the money report alike;
-**paid in** is top-ups paid plus plan fees from the invoices Stripe said
-were paid; **held in wallets** is credit bought and unspent — granted
-credit is shown apart, because nobody paid for it by the dollar.
+operator's debit.
 
 **Hand-placed plans renew.** A plan the super admin grants runs a month and
 is renewed by the hourly sweep at its period's end, with the same grant and
@@ -482,9 +458,6 @@ rollover rules. Granting a plan to an account Stripe is billing is refused
 the subscription at Stripe first, at once, and changes nothing if Stripe
 refuses.
 
-**An operator's credit or debit is written once** per idempotency key the
-console sends, and audited once.
-
 **Stripe.** Every call pins its API version (`2025-03-31.basil`;
 `STRIPE_API_VERSION` overrides) — create the webhook endpoint on the same
 version — and charges in `FOLDRUN_CURRENCY` (default `usd`), which is also
@@ -513,12 +486,10 @@ kept too, for the types above only, up to 256 KB, set when it first
 arrives and emptied after **180 days**: Stripe keeps events for 30, and a
 replay after that needs a copy. It carries what Stripe sends (names,
 emails, addresses, a card's last four digits — never a full card number),
-so only the super admin's console reads it and lists never load it. The
-super admin lists the log at `GET /api/admin/stripe-events` and replays
-one event with `POST /api/admin/stripe-events/<id>/replay` — Stripe's copy
-while Stripe has it, the kept copy after — through the same handler; every
-write it makes is keyed once, so a replay of an event that was handled
-changes nothing.
+so it is never shown to the account. The platform can replay an event
+through the same handler — Stripe's copy while Stripe has it, the kept
+copy after; every write it makes is keyed once, so a replay of an event
+that was handled changes nothing.
 
 ## Plan gates
 

package/docs/cli.md

@@ -449,7 +449,7 @@ this way: they can take it back without changing a password.
 
 **You reset it, as the platform.** Only the platform's own super admin can,
 only on the hosted platform, and it ends every session that account had:
-`/admin/<account>` → the member → **reset password**. The new password is
+from its console, the member → **reset password**. The new password is
 shown once. Sign in as them in a private window, then `foldrun login
 --profile <name>` and approve the code in that window.
 

package/docs/evals.md

@@ -47,9 +47,9 @@ satisfy. The heading is the case's name, so make it the thing being checked.
 |---|---|
 | `contains:` | the text must appear |
 | `not-contains:` | the text must not appear |
-| `matches:` | a JavaScript regular expression over the reply, case-insensitive. No inline flags such as `(?m)`: write `(^\|\n)` for the start of a line. `foldrun check` reports one that does not compile |
+| `matches:` | a JavaScript regular expression over the reply, case-insensitive, given a quarter of a second (a pattern that backtracks fails the check). No inline flags such as `(?m)`: write `(^\|\n)` for the start of a line. `foldrun check` reports one that does not compile |
 | `file:` | the path exists and is non-empty |
-| `run:` | a shell command that must exit 0 |
+| `run:` | a shell command that must exit 0 — `foldrun eval` on your machine only: an install that isolates runs refuses it (the check fails, saying so), because there it would run on the platform's own web server rather than in a sandbox |
 | `judge:` | a model grades the reply against this sentence |
 
 **Deterministic checks run first and cost nothing.** The judge only runs if they

package/docs/feature-flags.md

@@ -46,11 +46,8 @@ foldrun flags --json
 
 ## Running the platform yourself
 
-On a hosted install the super admin changes flags at **/admin → Flags**:
-the install-wide on/off and rollout, and an override per account. The same
-is `PUT`/`DELETE /api/admin/flags/<flag>` and
-`/api/admin/flags/<flag>/accounts/<account>` (see the API reference's
-super admin section). Every change is on the platform's audit as
+On the hosted platform the operator changes flags from its own console:
+the install-wide on/off and rollout, and an override per account. Every change is on the platform's audit as
 `operator.flag.global`, `operator.flag.global_cleared`,
 `operator.flag.account` or `operator.flag.account_cleared`, with who made
 it and what it was before. The settings are rows in Postgres

package/docs/security.md

@@ -152,6 +152,30 @@ name only — for the owner and admins to read or export. Support can view an
 account only [read-only, for thirty minutes, with a reason the customer
 reads](team-and-access#support-access).
 
+Signing in, in particular:
+
+- a password reset or change, two-step sign-in turned on or off, and a new
+  API key each send a notice to the person's address;
+- signing out ends the session on the server, not just in the browser;
+- a two-step code works once; replacing a second factor means turning it
+  off first, which needs the password and a code;
+- the sign-in forms refuse a request from another site, and `?next=` only
+  ever leads to a page on the same site;
+- `foldrun login` asks you to type the code your terminal shows — a link
+  with the code in it, sent by someone else, cannot sign their machine in
+  as you;
+- before the first sign-up, a self-hosted install's setup token guards key
+  minting as it guards sign-up;
+- only the account's owner can set the account's `RESEND_API_KEY` and
+  `EMAIL_FROM`, because that sender carries everyone's reset links;
+- a member or key limited to some workspaces cannot change what every
+  workspace shares — the library, the account's AGENTS.md defaults, its
+  model provider, its OAuth apps — nor people who work outside its
+  workspaces.
+
+Frontmatter is YAML only: a file opened with `---js` (which some parsers
+run as code) is refused.
+
 ## The dashboard in your browser
 
 Every page is sent with an enforced Content-Security-Policy: scripts run

package/docs/status.md

@@ -46,8 +46,7 @@ not see a network problem between you and the platform — the page saying
 
 ## Incidents and maintenance
 
-The super admin posts them from **Admin → Incidents** (or
-`/api/admin/incidents`): a title, what customers should read, the impact
+The platform's operator posts them from its console: a title, what customers should read, the impact
 (minor or major) and the components affected. Each update adds a line with
 a status — `investigating`, `identified`, `monitoring`, `resolved`.
 Maintenance is a window with a start and an end; it shows as upcoming before

package/docs/tools.md

@@ -1890,7 +1890,13 @@ tool is broken" and "the agent used it wrong", and it costs no model call.
 
 Every tool has a Test button, and `POST /api/workspaces/<ws>/tools/<tool>/test`
 behind it: it calls the tool with typed arguments from where a run would call
-it, shows the raw result, and costs no model call. A single-file tool that
+it, shows the raw result, and costs no model call. On an install that
+isolates runs (the hosted platform, a Docker or Kubernetes self-host) a
+script tool or an MCP server started by `command:` is your own code, which
+runs only inside a step's sandbox — the button says so and points to
+`foldrun tool test` on your machine, or a test run. An HTTP tool is tested
+as before, except that a secret bound to sites
+(`foldrun secrets sites`) is never sent to a host outside them. A single-file tool that
 carries its program in a fenced block is materialised for the test exactly as
 a call materialises it, so the test runs the identical program from the
 identical directory — for a long time it did not, and every fenced-code tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/src/commands.mjs

@@ -3835,6 +3835,13 @@ async function connect(positional, flags) {
 const DEFAULT_PLATFORM = "https://app.foldrun.io";
 
 function openInBrowser(target) {
+  // A server-supplied address: only a web page, never a file, an app or a
+  // custom scheme handed to `open`.
+  try {
+    if (!/^https?:$/.test(new URL(target).protocol)) return Promise.resolve(false);
+  } catch {
+    return Promise.resolve(false);
+  }
   const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   return import("node:child_process")
     .then(({ spawn }) => {
@@ -4872,11 +4879,13 @@ async function pullCmd(layout, flags, only) {
   /** @type {{file: string, content: string}[]} */
   const incoming = [];
   for (const name of names) {
+    if (!SAFE_NAME.test(name)) throw new Error(`the platform named a workspace "${name}", which is not a workspace name — refusing to write it`);
     const there = await remoteWorkspaceFiles(url, flags, name, isSourcePath);
-    for (const [rel, content] of there) incoming.push({ file: path.join(wsRoot, name, rel), content });
+    for (const [rel, content] of there) incoming.push({ file: within(path.join(wsRoot, name), rel), content });
   }
   for (const f of await remoteLibrary(url, flags, LIBRARY_KINDS)) {
-    incoming.push({ file: path.join(root, "library", f.kind, f.path), content: f.content });
+    if (!LIBRARY_KINDS.includes(f.kind)) throw new Error(`the platform sent a library kind "${f.kind}" this CLI does not know — refusing to write it`);
+    incoming.push({ file: within(path.join(root, "library", f.kind), f.path), content: f.content });
   }
 
   const clashes = incoming.filter((f) => {
@@ -9299,6 +9308,22 @@ async function runRmCmd(runId, flags, layout) {
   return 0;
 }
 
+const SAFE_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * `rel` under `base`, or a refusal. Every path a server names is written
+ * through this: a server (or anyone in between) must not be able to say
+ * "../../.ssh/authorized_keys" and have pull write it.
+ */
+function within(base, rel) {
+  const root = path.resolve(base);
+  const to = path.resolve(root, String(rel));
+  if (path.isAbsolute(String(rel)) || (to !== root && !to.startsWith(root + path.sep))) {
+    throw new Error(`the platform sent a path outside ${root} ("${rel}") — refusing to write it`);
+  }
+  return to;
+}
+
 /** Where downloaded bytes go: --file (or - for stdout), else a default name. Refuses to clobber. */
 function writeDownload(bytes, fallback, flags, from) {
   if (flags.file === "-") {
@@ -9361,7 +9386,11 @@ async function remoteBytes(url, flags, apiPath, what) {
     }
     throw new HttpError(`${what}: ${why}${res.status === 401 || res.status === 403 ? refusedHint(url, flags) : ""}`, res.status, {});
   }
-  const name = /filename="([^"]+)"/.exec(res.headers.get("content-disposition") ?? "")?.[1];
+  // The server's name is a suggestion for a file in THIS folder: only its
+  // last segment, and never a dot-file (".zshrc", "..").
+  const said = /filename="([^"]+)"/.exec(res.headers.get("content-disposition") ?? "")?.[1];
+  const base = said ? path.basename(said.replaceAll("\\", "/")) : undefined;
+  const name = base && !base.startsWith(".") ? base : undefined;
   return { bytes: Buffer.from(await res.arrayBuffer()), name };
 }
 

package/src/credentials.mjs

@@ -93,6 +93,13 @@ function write(current, profiles) {
     JSON.stringify({ current, default: current && profiles[current] ? normaliseUrl(profiles[current].url) : null, profiles, platforms }, null, 2) + "\n",
     { mode: 0o600 },
   );
+  // `mode` applies only when the file is created; one made before (or by
+  // hand) keeps whatever it had. It holds tokens: owner-only, every write.
+  try {
+    fs.chmodSync(file(), 0o600);
+  } catch {
+    /* not ours to fix (Windows ACLs, a read-only home) */
+  }
 }
 
 /**