foldrun 26.3.6 → 26.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/api-usage.md +5 -0
- package/docs/api.md +1 -0
- package/docs/cli.md +3 -2
- package/docs/team-and-access.md +6 -0
- package/package.json +1 -1
- package/src/commands.mjs +11 -1
package/docs/api-usage.md
CHANGED
|
@@ -139,10 +139,15 @@ Idempotency-Key: <a UUID you generate, one per operation>
|
|
|
139
139
|
response — same status, same body — and `Idempotent-Replayed: true`. No
|
|
140
140
|
second run, no second charge.
|
|
141
141
|
- The **same key with a different body** is a `422`: a key names one request.
|
|
142
|
+
`?wait` and `?timeout` do not count: a start retried with or without
|
|
143
|
+
`?wait=true`, or with another timeout, is the same request and gets the
|
|
144
|
+
first answer back (the run's id is in it, waited or not).
|
|
142
145
|
- The same key while the first request is still being answered is a `409`
|
|
143
146
|
with `Retry-After: 1`.
|
|
144
147
|
- A `5xx` is not remembered, so a retry after a server failure is a real
|
|
145
148
|
second attempt.
|
|
149
|
+
- A `503` with `Retry-After: 2` means the store that keeps keys is not
|
|
150
|
+
answering: nothing ran, and the same key is safe to send again.
|
|
146
151
|
- A request that never finished (the server restarted mid-answer) holds its
|
|
147
152
|
key for at most two minutes, then the key is free for a real retry.
|
|
148
153
|
- Minting or rotating a key: a replay says what was done but its `key` is
|
package/docs/api.md
CHANGED
|
@@ -393,6 +393,7 @@ Reads return which secrets exist, never their values.
|
|
|
393
393
|
|---|---|---|
|
|
394
394
|
| `/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 }`. A key's prefix says what it is: `fr_api_` an API key, `fr_a2a_` an A2A key (`fr_dep_` is reserved for deploy keys); keys minted before 11 Nov 2026 start `mda_` (or `mdk_`) and keep working — a key is looked up by its hash, never its prefix, and `prefix` is its first 12 characters. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, 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 project 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` |
|
|
395
395
|
| `/api/keys/<id>` | PATCH | `{ requireCustomer: true \| false }` — whether every run the key starts must name an end customer ([end customers](runs#end-customers)); a run without one is refused `400`, code `customer_required`. Not for an A2A key. An admin of every project; audited as `apikey.require_customer`. `POST /api/keys` takes `requireCustomer` too |
|
|
396
|
+
| `/api/keys/<id>` | DELETE | delete a key: revoked in the same moment if it is live (anything using it stops), and listed nowhere again — `GET /api/keys`, Settings, `foldrun keys ls`. The audit log keeps it (`apikey.deleted`, with `wasLive`). Answers `{ ok, id, revoked }` — `revoked` is whether this call ended a live key. `keys:manage`; a key outside the caller's scope, or one already deleted, is 404 |
|
|
396
397
|
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, projects 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 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, projects and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation). A `foldrun login` key stays one only when it renews itself or its own person rotates it, signed in; rotated by any other caller the new key is an ordinary one |
|
|
397
398
|
| `/api/team` | GET, POST | members with their roles and project scope; mint an invite (a session, or the person's own `foldrun login` key, which invites no admin) — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
398
399
|
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some projects sees only the invites inside its scope |
|
package/docs/cli.md
CHANGED
|
@@ -212,7 +212,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
212
212
|
| `foldrun backups` | how the account is backed up: the schedule, how many are kept, the last snapshot (verified? copied off the server? encrypted?), the snapshots that hold the account, each marked encrypted or not, each project's last change, and earlier restore requests (`--limit`, `--json`). `backups request --what runs\|state\|storage\|everything --at "<when>" [--to <workspace>] [--backup <id>] [--note "…"]` asks the platform team for a restore from a snapshot — recorded and emailed; nothing is restored until they do it. `backups requests` lists every request this account has made, and where each stands (`GET /api/account/backups/requests`, `--json`) |
|
|
213
213
|
| `foldrun accounts` | every account signed in on this machine whose sign-in still works, and which one a bare command acts as. Each is asked once (`GET /api/me`, in parallel); one whose key is refused (revoked, expired, an account that is gone) or whose platform does not answer is left out and counted in one line — the active one is always shown, marked when it fails. `--all` lists every one with what it answered; `accounts prune` forgets the refused ones on this machine (asks first; `--yes` on a pipe; `--unreachable` also those that did not answer). `foldrun profiles` is the same command |
|
|
214
214
|
| `foldrun use <name>` | act as one of them from here on. `foldrun switch <name>` is the same command |
|
|
215
|
-
| `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires; a key `foldrun login` minted is tagged `CLI sign-in · renews itself` (revoke it to sign that machine out) — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` |
|
|
215
|
+
| `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires; a key `foldrun login` minted is tagged `CLI sign-in · renews itself` (revoke it to sign that machine out) — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` (it stops working and stays listed as revoked) |
|
|
216
|
+
| `foldrun keys delete <id>` | delete a key (`DELETE /api/keys/<id>`): a live one is revoked in the same moment, so anything using it stops; a revoked or expired one just leaves `keys ls` and Settings. The audit log keeps the record (`apikey.deleted`). Asks first; `--yes` on a pipe. An admin's |
|
|
216
217
|
| `foldrun keys rotate <id>` | a new key with the old one's label, role, projects and deploy scope, printed once; the old key is revoked at once (asks first; `--yes` on a pipe), or keeps working for `--grace 1h` / `24h` while you swap the new one in. A key already rotated is refused (409) and the command names the key that replaced it — rotate that one, also if its secret was lost; `keys ls` shows `rotated → <id>`. The owner is emailed a week before any key expires |
|
|
217
218
|
| `foldrun keys set <id> --customer required\|optional` | whether every run the key starts must name an end customer ([end customers](runs#end-customers)); make one that requires it from the start with `foldrun keys create <label> --require-customer`. `PATCH /api/keys/<id>` |
|
|
218
219
|
| `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each published with `a2a:` (a flow not published when the key is minted is refused: publish first) — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
|
|
@@ -290,7 +291,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
290
291
|
| `--event-wait` | `reject`: refuse a step waiting on `wait: event` rather than a person's gate |
|
|
291
292
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
292
293
|
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run`, `create_workspace`, `write_file` or `delete_file` |
|
|
293
|
-
| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
|
|
294
|
+
| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `keys delete`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
|
|
294
295
|
| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
295
296
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
|
296
297
|
| `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
|
package/docs/team-and-access.md
CHANGED
|
@@ -157,6 +157,12 @@ and ends the old key: at once, or after a grace of an hour or a day so a CI
|
|
|
157
157
|
job can be moved across first. In the dashboard it is the Rotate button on
|
|
158
158
|
the key; `foldrun keys rotate <id> --grace 1h`; `POST /api/keys/<id>/rotate`.
|
|
159
159
|
|
|
160
|
+
**Revoke** ends a key: anything using it stops at once, and it stays in the
|
|
161
|
+
list marked revoked. **Delete** removes a key from the list: a live one is
|
|
162
|
+
revoked in the same moment, a revoked or expired one just goes. The audit log
|
|
163
|
+
keeps the record (`apikey.deleted`). In the dashboard it is the Delete button
|
|
164
|
+
on the key; `foldrun keys delete <id>`; `DELETE /api/keys/<id>`.
|
|
165
|
+
|
|
160
166
|
A key is rotated **once**. While the old key runs out its grace it shows
|
|
161
167
|
**rotated → <new key>** (in `foldrun keys ls` too), and rotating it again is
|
|
162
168
|
refused with `this key was already rotated to <prefix>…; rotate that one`.
|
package/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -4724,7 +4724,8 @@ async function doctor(flags) {
|
|
|
4724
4724
|
* keys ls every key, live and revoked
|
|
4725
4725
|
* keys create <label> [--role r] an account key (editor unless said)
|
|
4726
4726
|
* keys create <label> --to <ws> (or --workspaces a,b) one that opens those workspaces alone
|
|
4727
|
-
* keys revoke <id>
|
|
4727
|
+
* keys revoke <id> it stops working; it stays listed as revoked
|
|
4728
|
+
* keys delete <id> revoked (if live) and gone from the list
|
|
4728
4729
|
* keys create <label> --expires 90d it stops working in 90 days (30d, 365d, never)
|
|
4729
4730
|
* keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
|
|
4730
4731
|
* keys create <label> --gateway --cap <usd> [--daily <usd>] a coding agent's key (Claude Code): the gateway only
|
|
@@ -4828,6 +4829,15 @@ async function keysCmd(positional, flags) {
|
|
|
4828
4829
|
console.log(`\n ${c.green("✓")} revoked ${arg}\n`);
|
|
4829
4830
|
return 0;
|
|
4830
4831
|
}
|
|
4832
|
+
// Delete (17 Nov 2026): a live key is revoked in the same moment, and the
|
|
4833
|
+
// key leaves `keys ls` and Settings; the audit log keeps the record.
|
|
4834
|
+
if (verb === "delete") {
|
|
4835
|
+
if (!arg) throw new Error("which key? foldrun keys delete <id> — ids are in `foldrun keys ls`");
|
|
4836
|
+
if (!(await sureToDelete(flags, "keys delete", `API key ${arg} on ${url} (revoked first if it is live — anything using it stops working — then removed from the list)`))) return 1;
|
|
4837
|
+
const done = await remoteCall(url, flags, `/api/keys/${encodeURIComponent(arg)}`, { method: "DELETE" });
|
|
4838
|
+
console.log(`\n ${c.green("✓")} deleted ${arg}${done?.revoked ? " (it was live: revoked now)" : ""}\n`);
|
|
4839
|
+
return 0;
|
|
4840
|
+
}
|
|
4831
4841
|
if (verb === "rotate") {
|
|
4832
4842
|
if (!arg) throw new Error("which key? foldrun keys rotate <id> [--grace 1h] — ids are in `foldrun keys ls`");
|
|
4833
4843
|
const grace = typeof flags.grace === "string" ? flags.grace : "0";
|