foldrun 8.1.0 → 8.1.2

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.md CHANGED
@@ -337,7 +337,7 @@ Reads return which secrets exist, never their values.
337
337
  | Route | Methods | |
338
338
  |---|---|---|
339
339
  | `/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` |
340
- | `/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 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). 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) |
340
+ | `/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 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces 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) |
341
341
  | `/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` (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 |
342
342
  | `/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 workspaces sees only the invites inside its scope |
343
343
  | `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
package/docs/cli.md CHANGED
@@ -320,6 +320,9 @@ workspaces) and stores the new one, saying so on one dim line. A machine in
320
320
  use never sees its sign-in end; one left unused for 90 days is signed out,
321
321
  and the next command says to run `foldrun login` again. A key handed in with
322
322
  `--token` or `FOLDRUN_TOKEN` is never renewed — its end is its owner's.
323
+ A credentials file the CLI cannot write is not renewed either (the new key
324
+ would be lost); if storing a renewed key fails, the CLI says so, and the next
325
+ command within ten minutes tries again.
323
326
 
324
327
  `foldrun login --url https://foldrun.example.com` signs in to your own
325
328
  installation; the last one signed in to is the default afterwards, and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "8.1.0",
3
+ "version": "8.1.2",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^7.0.0"
14
+ "@foldrun/core": "^7.0.2"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -711,7 +711,7 @@ async function platformLibrary(flags) {
711
711
  if (!url) return { url: undefined, tools: new Set(), skills: new Set(), warning: null };
712
712
  let token;
713
713
  try {
714
- token = tokenFor(url, { ...flags, quiet: true });
714
+ token = await renewedToken(url, { ...flags, quiet: true });
715
715
  } catch {
716
716
  return { url, tools: new Set(), skills: new Set(), warning: `${url} is the platform but this machine is not signed in — library tools there cannot be seen` };
717
717
  }
@@ -1948,7 +1948,7 @@ async function runEvals(name, flags = {}) {
1948
1948
  * read exactly like one refused on disk.
1949
1949
  */
1950
1950
  async function deployOverHttp(url, workspace, files, flags, expectRemoved) {
1951
- const token = tokenFor(url, flags);
1951
+ const token = await renewedToken(url, flags);
1952
1952
  const endpoint = `${url.replace(/\/+$/, "")}/api/workspaces/${encodeURIComponent(workspace)}/deploy`;
1953
1953
 
1954
1954
  let res;
@@ -2542,17 +2542,50 @@ async function renewIfDue(url, flags) {
2542
2542
  const a = /** @type {any} */ (await meRes.json())?.actor ?? {};
2543
2543
  if (a.kind !== "key" || a.origin !== "cli-login") return void save({ renews: false, checkedAt: new Date(now).toISOString() });
2544
2544
  if (!a.expiresAt || Date.parse(a.expiresAt) - now > RENEW_DAYS * DAY_MS) return void save({ renews: true, expiresAt: a.expiresAt ?? null, checkedAt: undefined });
2545
+ // Rotate only what can be kept: the old key ends minutes after the
2546
+ // rotation lands, so a credentials file this CLI cannot write would lose
2547
+ // the new key and sign the machine out. Then the old one runs to its end.
2548
+ if (!credentialsWritable()) return;
2545
2549
  const res = await remoteFetch(at, `/api/keys/${enc(a.id)}/rotate`, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" }, { token: p.token });
2546
2550
  if (!res.ok) return;
2547
2551
  const r = /** @type {any} */ (await res.json());
2548
2552
  if (typeof r.key !== "string") return;
2549
- save({ token: r.key, renews: true, expiresAt: r.expiresAt ?? null, checkedAt: undefined });
2553
+ try {
2554
+ save({ token: r.key, renews: true, expiresAt: r.expiresAt ?? null, checkedAt: undefined });
2555
+ } catch (err) {
2556
+ // Not silent: the old key now ends within minutes. The next command
2557
+ // retries with it (the platform rotates the unused new one), and
2558
+ // `foldrun login` is the way back if that cannot be stored either.
2559
+ console.error(` ${c.amber("!")} renewed this machine's sign-in but could not store it (${err instanceof Error ? err.message : err}) — the next command tries again within 10 minutes; after that, \`foldrun login\``);
2560
+ return;
2561
+ }
2550
2562
  if (flags.quiet !== true) console.error(` ${c.dim(`renewed this machine's sign-in as "${name}"${r.expiresAt ? ` — it now lasts until ${String(r.expiresAt).slice(0, 10)}` : ""}`)}`);
2551
2563
  } catch {
2552
2564
  // Offline, an old platform, a read-only home: the old key still works.
2553
2565
  }
2554
2566
  }
2555
2567
 
2568
+ /** Whether the credentials file can be written in place (or, not there yet,
2569
+ * made) — checked before a renewal, which cannot be undone. */
2570
+ function credentialsWritable() {
2571
+ const dir = credentialsDir();
2572
+ const file = path.join(dir, "credentials.json");
2573
+ try {
2574
+ fs.accessSync(fs.existsSync(file) ? file : dir, fs.constants.W_OK);
2575
+ return true;
2576
+ } catch {
2577
+ return false;
2578
+ }
2579
+ }
2580
+
2581
+ /** tokenFor, after the once-per-command renewal remoteCall does — for the
2582
+ * calls that fetch bytes, uploads or streams themselves (FOL-71). Without
2583
+ * it a machine that only ran those would never renew its sign-in. */
2584
+ async function renewedToken(url, flags) {
2585
+ await renewIfDue(url, flags);
2586
+ return tokenFor(url, flags);
2587
+ }
2588
+
2556
2589
  /**
2557
2590
  * A call to the platform's API, as JSON. A body that is not JSON is not the
2558
2591
  * platform talking — a Cloudflare challenge, a proxy's error page, a tunnel
@@ -2563,8 +2596,7 @@ async function renewIfDue(url, flags) {
2563
2596
  * @returns {Promise<any>}
2564
2597
  */
2565
2598
  async function remoteCall(url, flags, apiPath, init = {}, { seconds } = {}) {
2566
- await renewIfDue(url, flags);
2567
- const token = tokenFor(url, flags);
2599
+ const token = await renewedToken(url, flags);
2568
2600
  const res = await remoteFetch(
2569
2601
  url,
2570
2602
  apiPath,
@@ -2686,7 +2718,7 @@ class StreamIdle extends Error {
2686
2718
  * first, and throws StreamIdle when nothing arrives for streamIdleSeconds.
2687
2719
  */
2688
2720
  async function streamOnce(url, flags, ws, runId, seen, open = new Map()) {
2689
- const token = tokenFor(url, flags);
2721
+ const token = await renewedToken(url, flags);
2690
2722
  const idle = streamIdleSeconds();
2691
2723
  const target = new URL(`/api/workspaces/${ws}/runs/${runId}/stream`, url);
2692
2724
  const ctrl = new AbortController();
@@ -3713,7 +3745,7 @@ async function connect(positional, flags) {
3713
3745
  // this machine's vault otherwise. Decided before the browser opens, so a
3714
3746
  // consent is never spent on a store that then refuses it.
3715
3747
  const url = flags.local === true ? undefined : remoteUrl(flags);
3716
- const token = url ? tokenFor(url, flags) : null;
3748
+ const token = url ? await renewedToken(url, flags) : null;
3717
3749
  const workspaceName = flags.to ?? (flags.workspace ? path.basename(path.resolve(flags.workspace)) : undefined);
3718
3750
 
3719
3751
  // Reconnecting: the platform already holds the client this secret (or this
@@ -5261,7 +5293,7 @@ async function storageCmd(positional, flags, layout) {
5261
5293
  if (jobs.length !== 1) throw new Error("--as names one file; for several use --into <folder/>");
5262
5294
  jobs[0].rel = flags.as;
5263
5295
  }
5264
- const token = tokenFor(url, flags);
5296
+ const token = await renewedToken(url, flags);
5265
5297
  const base = `/api/workspaces/${encodeURIComponent(ws)}/storage`;
5266
5298
  const said = async (res) => {
5267
5299
  const text = await res.text();
@@ -5333,7 +5365,7 @@ async function storageCmd(positional, flags, layout) {
5333
5365
  // streams the bytes on the fs driver, so this is a plain fetch that
5334
5366
  // follows redirects — not remoteCall, which parses JSON and would make a
5335
5367
  // markdown file look like a broken platform.
5336
- const token = tokenFor(url, flags);
5368
+ const token = await renewedToken(url, flags);
5337
5369
  const res = await remoteFetch(url, `/api/workspaces/${ws}/storage/download?path=${encodeURIComponent(rel)}`, {}, { token });
5338
5370
  if (!res.ok) {
5339
5371
  const said = await res.text();
@@ -9457,7 +9489,7 @@ async function apiCmd(positional, flags) {
9457
9489
 
9458
9490
  /** A GET whose answer is a file, not JSON — the error body still is. */
9459
9491
  async function remoteBytes(url, flags, apiPath, what) {
9460
- const token = tokenFor(url, flags);
9492
+ const token = await renewedToken(url, flags);
9461
9493
  const res = await remoteFetch(url, apiPath, {}, { token, seconds: timeoutSeconds(flags) });
9462
9494
  if (!res.ok) {
9463
9495
  const said = await res.text();
@@ -9509,7 +9541,7 @@ async function importCmd(positional, flags, layout) {
9509
9541
  const url = platformFor(flags, "import");
9510
9542
  const ws = platformWorkspace(flags, layout, "import");
9511
9543
  const bytes = fs.readFileSync(file);
9512
- const token = tokenFor(url, flags);
9544
+ const token = await renewedToken(url, flags);
9513
9545
  const send = async (query) => {
9514
9546
  const res = await remoteFetch(
9515
9547
  url,
@@ -11865,7 +11897,7 @@ async function reportLiveCmd(runId, flags, layout) {
11865
11897
  console.log(`\n ${c.dim(`foldrun report ${runId} live --agent <name> saves its newest frame`)}\n`);
11866
11898
  return 0;
11867
11899
  }
11868
- const res = await remoteFetch(url, `${base}?agent=${enc(agent)}`, {}, { token: tokenFor(url, flags), seconds: timeoutSeconds(flags) });
11900
+ const res = await remoteFetch(url, `${base}?agent=${enc(agent)}`, {}, { token: await renewedToken(url, flags), seconds: timeoutSeconds(flags) });
11869
11901
  if (res.status === 204) {
11870
11902
  console.log(`\n ${c.dim(`${agent} has no frame — its browser has not shown anything yet`)}\n`);
11871
11903
  return 0;