@raibitsi/tiresias 1.0.1 → 1.2.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.
Files changed (67) hide show
  1. package/CHANGELOG.md +88 -0
  2. package/README.md +72 -33
  3. package/data/README.md +33 -0
  4. package/data/guard-ordinary-urls.txt +102 -0
  5. package/data/guard-starter.jsonl +424 -0
  6. package/dist/aimed.js +23 -0
  7. package/dist/anchor.js +26 -13
  8. package/dist/browsecli.js +17 -13
  9. package/dist/cdp.js +22 -1
  10. package/dist/cleanup.js +3 -1
  11. package/dist/cli.js +216 -68
  12. package/dist/config.js +75 -1
  13. package/dist/confirm.js +20 -5
  14. package/dist/cooldown.js +57 -32
  15. package/dist/dailylog.js +11 -5
  16. package/dist/dom.js +13 -8
  17. package/dist/doors.js +1 -1
  18. package/dist/engine.js +9 -4
  19. package/dist/envelope.js +10 -1
  20. package/dist/fetcher.js +29 -2
  21. package/dist/filereply.js +7 -1
  22. package/dist/formflow.js +21 -3
  23. package/dist/forms.js +337 -42
  24. package/dist/getactions.js +119 -0
  25. package/dist/guard.js +1240 -0
  26. package/dist/guardclient.js +245 -0
  27. package/dist/guardnetwork.js +22 -0
  28. package/dist/history.js +11 -5
  29. package/dist/hook.js +2 -0
  30. package/dist/hosts.js +34 -27
  31. package/dist/keys.js +420 -18
  32. package/dist/local.js +537 -0
  33. package/dist/mcp.js +56 -25
  34. package/dist/needs.js +9 -5
  35. package/dist/parentwatch.js +6 -16
  36. package/dist/pdf.js +4 -1
  37. package/dist/pdfchild.js +0 -2
  38. package/dist/pdfproc.js +26 -11
  39. package/dist/pdfwatch.js +14 -0
  40. package/dist/pipeline.js +117 -26
  41. package/dist/preformatted.js +12 -0
  42. package/dist/profiles.js +3 -3
  43. package/dist/queue.js +24 -20
  44. package/dist/reader.js +441 -87
  45. package/dist/receipts.js +7 -2
  46. package/dist/render.js +156 -27
  47. package/dist/renderactions.js +69 -0
  48. package/dist/resume.js +8 -6
  49. package/dist/rules.js +24 -5
  50. package/dist/safebrowsing.js +3 -3
  51. package/dist/safety.js +15 -7
  52. package/dist/sandbox.js +1 -1
  53. package/dist/saved.js +24 -9
  54. package/dist/savedlock.js +99 -5
  55. package/dist/settings.js +10 -3
  56. package/dist/shelf.js +1 -1
  57. package/dist/shield.js +15 -0
  58. package/dist/slips.js +43 -1
  59. package/dist/store.js +119 -25
  60. package/dist/tabs.js +1 -1
  61. package/dist/textview.js +16 -0
  62. package/dist/translate.js +22 -2
  63. package/dist/types.js +9 -2
  64. package/dist/watchflow.js +1 -2
  65. package/dist/work.js +10 -2
  66. package/docs/LOCAL-MODELS.md +271 -0
  67. package/package.json +5 -2
package/dist/keys.js CHANGED
@@ -8,7 +8,8 @@ import os from "node:os";
8
8
  import path from "node:path";
9
9
  import { verifierFromJWK } from "web-bot-auth/crypto";
10
10
  import { SigningError, SlipError } from "./errors.js";
11
- import { NOFOLLOW, NONBLOCK, homeDir, isPrivate, ownFile, randomTmp, subDir } from "./store.js";
11
+ import { releaseLock, takeLock } from "./savedlock.js";
12
+ import { NOFOLLOW, NONBLOCK, homeDir, isPrivate, ownFile, randomTmp, rmRegular, subDir } from "./store.js";
12
13
  export const KEY_FILE = "ed25519.private.jwk";
13
14
  // A synced folder (OneDrive, iCloud Drive, Dropbox, Google Drive) would copy the private key to
14
15
  // other machines and the cloud. Judged on the REAL path (links are followed), and only by real
@@ -240,7 +241,7 @@ function inspectKeyFile(name, k, knownStamp) {
240
241
  }
241
242
  if (!isKey(jwk))
242
243
  throw damagedKey(k, "not an Ed25519 key");
243
- return { stamp, jwk: derive(jwk, k) };
244
+ return { stamp, jwk: derive(jwk, k), raw: jwk };
244
245
  }
245
246
  catch (e) {
246
247
  if (e instanceof k.Err)
@@ -255,9 +256,12 @@ function inspectKeyFile(name, k, knownStamp) {
255
256
  export function readPrivateJwk() {
256
257
  return inspectKey()?.jwk ?? null;
257
258
  }
258
- export async function publicInfo(jwk) {
259
+ export async function publicInfo(jwk, previous) {
259
260
  const pub = { kty: "OKP", crv: "Ed25519", x: jwk.x };
260
- return { public_jwk: pub, keyid: (await verifierFromJWK(pub)).keyid, directory: { keys: [pub] } };
261
+ const keys = [pub];
262
+ if (previous && previous.x !== jwk.x)
263
+ keys.push({ kty: "OKP", crv: "Ed25519", x: previous.x });
264
+ return { public_jwk: pub, keyid: (await verifierFromJWK(pub)).keyid, directory: { keys } };
261
265
  }
262
266
  export const DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
263
267
  export const DIRECTORY_TYPE = "application/http-message-signatures-directory+json";
@@ -279,24 +283,46 @@ export async function signDirectory(opts) {
279
283
  }
280
284
  if (!Number.isInteger(opts.days) || opts.days < 1 || opts.days > 90)
281
285
  throw new Error("--days must be a whole number from 1 to 90.");
282
- const jwk = readPrivateJwk();
283
- if (!jwk)
284
- throw new Error("No signing key yet. Run: tiresias keys init");
285
- const info = await publicInfo(jwk);
286
- const created = Math.floor((opts.now ?? Date.now()) / 1000);
287
- const expires = created + opts.days * 86_400;
288
- const nonce = randomBytes(64).toString("base64");
289
- const params = `("@authority";req);created=${created};keyid="${info.keyid}";alg="ed25519";expires=${expires};nonce="${nonce}";tag="http-message-signatures-directory"`;
290
- const base = `"@authority";req: ${host}\n"@signature-params": ${params}`;
291
- const sig = edSign(null, Buffer.from(base), createPrivateKey({ key: { kty: "OKP", crv: "Ed25519", d: jwk.d, x: jwk.x }, format: "jwk" })).toString("base64");
286
+ const now = opts.now ?? Date.now();
287
+ const pub = await publishedKeys(now);
288
+ const created = Math.floor(now / 1000);
289
+ let expires = created + opts.days * 86_400;
290
+ // v1.1: during a rotation's overlap window the directory lists two keys and carries one signature per key.
291
+ // Its signatures end when the window does, so a static copy never keeps publishing the old key past it.
292
+ const signers = [pub.jwk];
293
+ let capped;
294
+ if (pub.previous) {
295
+ const end = Math.floor(Date.parse(pub.previous.until) / 1000);
296
+ if (end > created) {
297
+ signers.push(pub.previous.jwk);
298
+ if (end < expires) {
299
+ expires = end;
300
+ capped = pub.previous.until;
301
+ }
302
+ }
303
+ }
304
+ const body = { keys: signers.map((j) => ({ kty: "OKP", crv: "Ed25519", x: j.x })) };
305
+ const sigs = [];
306
+ const inputs = [];
307
+ for (const [i, j] of signers.entries()) {
308
+ const keyid = (await verifierFromJWK({ kty: "OKP", crv: "Ed25519", x: j.x })).keyid;
309
+ const nonce = randomBytes(64).toString("base64");
310
+ const params = `("@authority";req);created=${created};keyid="${keyid}";alg="ed25519";expires=${expires};nonce="${nonce}";tag="http-message-signatures-directory"`;
311
+ const base = `"@authority";req: ${host}\n"@signature-params": ${params}`;
312
+ const sig = edSign(null, Buffer.from(base), createPrivateKey({ key: { kty: "OKP", crv: "Ed25519", d: j.d, x: j.x }, format: "jwk" })).toString("base64");
313
+ sigs.push(`sig${i + 1}=:${sig}:`);
314
+ inputs.push(`sig${i + 1}=${params}`);
315
+ }
292
316
  return {
293
317
  host,
294
318
  path: DIRECTORY_PATH,
295
319
  created_at: new Date(created * 1000).toISOString(),
296
320
  expires_at: new Date(expires * 1000).toISOString(),
297
- body: JSON.stringify(info.directory, null, 2) + "\n",
298
- headers: { "Content-Type": DIRECTORY_TYPE, Signature: `sig1=:${sig}:`, "Signature-Input": `sig1=${params}` },
299
- keyid: info.keyid,
321
+ body: JSON.stringify(body, null, 2) + "\n",
322
+ headers: { "Content-Type": DIRECTORY_TYPE, Signature: sigs.join(", "), "Signature-Input": inputs.join(", ") },
323
+ keyid: pub.info.keyid,
324
+ ...(pub.previous && signers.length > 1 ? { previous_keyid: pub.previous.keyid, previous_until: pub.previous.until } : {}),
325
+ ...(capped ? { capped_by_rotation: capped } : {}),
300
326
  };
301
327
  }
302
328
  // Make a key. Never overwrites unless force. Returns only public facts.
@@ -307,6 +333,14 @@ export async function initKey(force = false) {
307
333
  if (why)
308
334
  throw new Error(why);
309
335
  const d = keysDir(true);
336
+ // Codex K.8: replacing the key and dropping the previous one hold the rotation lock, like a rotation does, so a
337
+ // rotation running at the same moment cannot have its freshly kept key deleted.
338
+ const r = withRotateLock(d, 1000, () => initLocked(d, force));
339
+ if (r === BUSY)
340
+ throw new Error("A key rotation is under way. Try again in a moment. Nothing was changed.");
341
+ return { ...(await publicInfo(r.jwk)), file: r.file, replaced: r.replaced };
342
+ }
343
+ function initLocked(d, force) {
310
344
  const file = path.join(d, KEY_FILE);
311
345
  let exists = false;
312
346
  try {
@@ -341,7 +375,257 @@ export async function initKey(force = false) {
341
375
  fs.closeSync(fd);
342
376
  if (exists)
343
377
  fs.renameSync(target, file);
344
- return { ...(await publicInfo(jwk)), file, replaced: exists };
378
+ // v1.1: a fresh start leaves no earlier key in the directory (a rotation's previous key goes too).
379
+ rmRegular(path.join(d, PREVIOUS_KEY_FILE));
380
+ sweepPreviousTmp(d);
381
+ return { jwk, file, replaced: exists };
382
+ }
383
+ // ---- v1.1 workstream 4: rotating the signing key ----
384
+ // `keys rotate` makes a new key and keeps the old one for an overlap window (default 7 days, 0 to 30), so sites
385
+ // that cached the old directory still recognise requests signed before the switch, and so the new directory can
386
+ // carry one signature per key, as Cloudflare asks. During the window:
387
+ // - new requests are signed with the NEW key only (signing.ts reads only ed25519.private.jwk);
388
+ // - keys show, keys directory and keys sign-directory publish both public keys;
389
+ // - the old private key is kept in keys/ed25519.previous.jwk (same storage rules), used for nothing but signing
390
+ // the directory response, and deleted when the window ends (at the next keys command that looks) or on
391
+ // `keys rotate --finish`. `--overlap 0` keeps nothing: the old key is gone at once (the choice after a leak).
392
+ // A second rotation inside the window is refused until --finish, so no key is ever lost silently.
393
+ export const PREVIOUS_KEY_FILE = "ed25519.previous.jwk";
394
+ export const DEFAULT_OVERLAP_DAYS = 7;
395
+ export const MAX_OVERLAP_DAYS = 30;
396
+ const DAY_MS = 86_400_000;
397
+ const PREVIOUS = { label: "previous signing key", refuse: "Refusing to publish the key directory.", fix: "run `tiresias keys rotate --finish` to drop it", Err: SigningError };
398
+ // Write a private key file whole: a temp file made exclusively (0600, never following a link), synced, then put
399
+ // in place by rename (replace) or hard link (exclusive: fails with EEXIST when the name is taken). A reader never
400
+ // sees a half-written file. The temp file is always removed.
401
+ function writeSecret(file, body, how) {
402
+ const tmp = randomTmp(file);
403
+ const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW | NONBLOCK, 0o600);
404
+ try {
405
+ try {
406
+ for (let off = 0; off < body.length;)
407
+ off += fs.writeSync(fd, body, off, body.length - off);
408
+ fs.fchmodSync(fd, 0o600);
409
+ fs.fsyncSync(fd);
410
+ }
411
+ finally {
412
+ fs.closeSync(fd);
413
+ }
414
+ if (how === "replace")
415
+ fs.renameSync(tmp, file);
416
+ else
417
+ fs.linkSync(tmp, file);
418
+ }
419
+ finally {
420
+ fs.rmSync(tmp, { force: true });
421
+ }
422
+ }
423
+ const newKeyBody = (extra = {}) => {
424
+ const { privateKey } = generateKeyPairSync("ed25519");
425
+ const j = privateKey.export({ format: "jwk" });
426
+ const jwk = { kty: "OKP", crv: "Ed25519", x: j.x, d: j.d };
427
+ return { jwk, body: Buffer.from(JSON.stringify({ ...jwk, ...extra }) + "\n") };
428
+ };
429
+ // Rotations hold a lock (savedlock.ts: a dead owner is recovered, a live one never timed out), and anything that
430
+ // deletes a previous key holds it too and looks again first. Without it a `keys show` that read the current key just
431
+ // before a rotation could take the freshly kept old key for a leftover and delete it (Codex K.1).
432
+ export const ROTATE_LOCK = "ed25519.rotate"; // keys/ed25519.rotate.lock
433
+ const PREV_TMP = /^ed25519\.previous\.jwk\.[0-9a-f]{16}\.tmp$/;
434
+ function withRotateLock(d, tryMs, fn, name = ROTATE_LOCK) {
435
+ const lock = path.join(d, name);
436
+ const token = takeLock(lock, tryMs);
437
+ if (!token)
438
+ return BUSY;
439
+ try {
440
+ return fn();
441
+ }
442
+ finally {
443
+ releaseLock(lock, token);
444
+ }
445
+ }
446
+ const BUSY = Symbol("busy");
447
+ // A rotation killed between linking the previous-key temp file and removing it leaves a copy of the old private key
448
+ // under a temp name (Codex K.2). Only rotations make these, and only under the lock, so under the lock any is a leftover.
449
+ function sweepPreviousTmp(d) {
450
+ for (const n of fs.readdirSync(d))
451
+ if (PREV_TMP.test(n))
452
+ rmRegular(path.join(d, n));
453
+ }
454
+ // Under the rotation lock: look again, and drop the previous key only if it is STILL expired or the same as the
455
+ // current key. Busy (a rotation is running): nothing is deleted.
456
+ function cleanPrevious(now) {
457
+ if (isPrivate())
458
+ return; // a private session changes nothing; the expired key is only ignored
459
+ const d = keysDir(false);
460
+ if (!d)
461
+ return;
462
+ withRotateLock(d, 250, () => cleanPreviousLocked(d, now));
463
+ }
464
+ function cleanPreviousLocked(d, now) {
465
+ const s = inspectKeyFile(PREVIOUS_KEY_FILE, PREVIOUS);
466
+ if (s?.jwk) {
467
+ const until = typeof s.raw?.until === "string" ? Date.parse(s.raw.until) : NaN;
468
+ const cur = readPrivateJwk();
469
+ if (now >= until || (cur && cur.x === s.jwk.x))
470
+ rmRegular(path.join(d, PREVIOUS_KEY_FILE));
471
+ }
472
+ if (!fs.lstatSync(path.join(d, PREVIOUS_KEY_FILE), { throwIfNoEntry: false }))
473
+ sweepPreviousTmp(d);
474
+ }
475
+ // The previous key while its window is open, or null. An expired window, and the leftover of a rotation cut short
476
+ // (the same key as the current one), are removed here, under the rotation lock and after a second look; a stale
477
+ // `current` from a caller never causes a delete. A damaged file is a SigningError (fix: --finish).
478
+ export async function previousKey(now = Date.now(), current = readPrivateJwk(), locked = false) {
479
+ const s = inspectKeyFile(PREVIOUS_KEY_FILE, PREVIOUS);
480
+ if (!s?.jwk)
481
+ return null;
482
+ const until = typeof s.raw?.until === "string" ? Date.parse(s.raw.until) : NaN;
483
+ const rotated = typeof s.raw?.rotated_at === "string" ? Date.parse(s.raw.rotated_at) : NaN;
484
+ if (Number.isNaN(until) || Number.isNaN(rotated))
485
+ throw damagedKey(PREVIOUS, "its overlap dates are missing");
486
+ if (now >= until || (current && current.x === s.jwk.x)) {
487
+ if (locked) {
488
+ const d = keysDir(false);
489
+ if (d)
490
+ cleanPreviousLocked(d, now);
491
+ }
492
+ else
493
+ cleanPrevious(now);
494
+ // Looked at again: a rotation may have finished meanwhile, making this a real previous key after all.
495
+ const again = inspectKeyFile(PREVIOUS_KEY_FILE, PREVIOUS);
496
+ const cur = readPrivateJwk();
497
+ if (!again?.jwk || now >= until || again.jwk.x !== s.jwk.x || !cur || cur.x === s.jwk.x)
498
+ return null;
499
+ }
500
+ const keyid = (await verifierFromJWK({ kty: "OKP", crv: "Ed25519", x: s.jwk.x })).keyid;
501
+ return { jwk: s.jwk, keyid, rotated_at: new Date(rotated).toISOString(), until: new Date(until).toISOString() };
502
+ }
503
+ // What the directory publishes now: the current key, plus the previous one while its window is open.
504
+ export async function publishedKeys(now = Date.now()) {
505
+ // A rotation can complete between these reads (and previousKey may await a verifier). Publish
506
+ // only a pair whose current key is still current after all async work. Retrying also leaves the
507
+ // existing busy-lock behaviour of read-only key commands intact.
508
+ for (let attempt = 0; attempt < 4; attempt++) {
509
+ const jwk = readPrivateJwk();
510
+ if (!jwk)
511
+ throw new Error("No signing key yet. Run: tiresias keys init");
512
+ const previous = await previousKey(now, jwk);
513
+ const info = await publicInfo(jwk, previous?.jwk);
514
+ if (readPrivateJwk()?.x === jwk.x)
515
+ return { jwk, info, previous };
516
+ }
517
+ throw new Error("The signing key changed while reading the directory. Try again in a moment.");
518
+ }
519
+ // The overlap value from the command line: whole days, 0 to 30.
520
+ export function parseOverlap(raw) {
521
+ if (raw === undefined)
522
+ return DEFAULT_OVERLAP_DAYS;
523
+ if (!/^\d{1,3}$/.test(raw.trim()) || Number(raw) > MAX_OVERLAP_DAYS)
524
+ throw new Error(`--overlap takes whole days from 0 to ${MAX_OVERLAP_DAYS} (default ${DEFAULT_OVERLAP_DAYS}).`);
525
+ return Number(raw);
526
+ }
527
+ // Rotate the signing key. Returns only public facts; nothing private is ever returned or printed.
528
+ export async function rotateKey(opts = {}) {
529
+ if (isPrivate())
530
+ throw new Error("Private mode: nothing is written, so no key is rotated.");
531
+ const why = syncedFolderReason();
532
+ if (why)
533
+ throw new Error(why);
534
+ const days = opts.overlapDays ?? DEFAULT_OVERLAP_DAYS;
535
+ if (!Number.isInteger(days) || days < 0 || days > MAX_OVERLAP_DAYS)
536
+ throw new Error(`--overlap takes whole days from 0 to ${MAX_OVERLAP_DAYS} (default ${DEFAULT_OVERLAP_DAYS}).`);
537
+ const now = opts.now ?? Date.now();
538
+ if (!readPrivateJwk())
539
+ throw new Error("No signing key yet. Run: tiresias keys init");
540
+ const d = keysDir(true);
541
+ const r = await withRotateLockAsync(d, () => rotateLocked(d, days, now));
542
+ if (r === BUSY)
543
+ throw new Error("Another key rotation is under way. Try again in a moment. Nothing was changed.");
544
+ return r;
545
+ }
546
+ // The lock is synchronous and the key checks are async, so the async version releases in its own finally.
547
+ async function withRotateLockAsync(d, fn) {
548
+ const lock = path.join(d, ROTATE_LOCK);
549
+ const token = takeLock(lock);
550
+ if (!token)
551
+ return BUSY;
552
+ try {
553
+ return await fn();
554
+ }
555
+ finally {
556
+ releaseLock(lock, token);
557
+ }
558
+ }
559
+ async function rotateLocked(d, days, now) {
560
+ const cur = readPrivateJwk();
561
+ if (!cur)
562
+ throw new Error("No signing key yet. Run: tiresias keys init");
563
+ const open = await previousKey(now, cur, true);
564
+ if (open)
565
+ throw new Error(`A rotation is still in its overlap window: the previous key (${open.keyid}) stays in your directory until ${open.until}. Run \`tiresias keys rotate --finish\` to drop it now, then rotate again. Nothing was changed.`);
566
+ sweepPreviousTmp(d);
567
+ const file = path.join(d, KEY_FILE);
568
+ const prevFile = path.join(d, PREVIOUS_KEY_FILE);
569
+ const rotatedAt = new Date(now).toISOString();
570
+ const until = days > 0 ? new Date(now + days * DAY_MS).toISOString() : null;
571
+ let kept = false;
572
+ if (until) {
573
+ try {
574
+ writeSecret(prevFile, Buffer.from(JSON.stringify({ kty: "OKP", crv: "Ed25519", x: cur.x, d: cur.d, rotated_at: rotatedAt, until }) + "\n"), "exclusive");
575
+ }
576
+ catch (e) {
577
+ if (e.code === "EEXIST")
578
+ throw new Error("Another rotation is under way (a previous key appeared meanwhile). Run `tiresias keys show` to see where things stand. Nothing was changed.");
579
+ throw e;
580
+ }
581
+ kept = true;
582
+ }
583
+ const fresh = newKeyBody();
584
+ try {
585
+ // `keys init --force` since we read the key: stop, rather than lose a key nobody kept.
586
+ const again = readPrivateJwk();
587
+ if (!again || again.x !== cur.x)
588
+ throw new Error("The signing key changed while rotating (another rotate or keys init ran). Nothing was replaced. Run `tiresias keys show` and try again.");
589
+ writeSecret(file, fresh.body, "replace");
590
+ }
591
+ catch (e) {
592
+ if (kept)
593
+ rmRegular(prevFile);
594
+ throw e;
595
+ }
596
+ const info = await publicInfo(fresh.jwk, until ? cur : null);
597
+ return { ...info, file, previous_keyid: (await publicInfo(cur)).keyid, overlap_days: days, overlap_until: until, rotated_at: rotatedAt };
598
+ }
599
+ // End the overlap now: the previous key leaves the directory and its private half is deleted.
600
+ export async function finishRotation() {
601
+ if (isPrivate())
602
+ throw new Error("Private mode: nothing is written, so nothing is changed.");
603
+ const d = keysDir(false);
604
+ if (!d)
605
+ return { finished: false };
606
+ const r = await withRotateLockAsync(d, () => finishLocked(d));
607
+ if (r === BUSY)
608
+ throw new Error("A key rotation is under way. Try again in a moment. Nothing was changed.");
609
+ return r;
610
+ }
611
+ async function finishLocked(d) {
612
+ const file = path.join(d, PREVIOUS_KEY_FILE);
613
+ sweepPreviousTmp(d); // a copy left by a rotation cut short goes too (Codex K.2)
614
+ if (!fs.lstatSync(file, { throwIfNoEntry: false }))
615
+ return { finished: false };
616
+ let keyid;
617
+ try {
618
+ const s = inspectKeyFile(PREVIOUS_KEY_FILE, PREVIOUS);
619
+ if (s?.jwk)
620
+ keyid = (await verifierFromJWK({ kty: "OKP", crv: "Ed25519", x: s.jwk.x })).keyid;
621
+ }
622
+ catch {
623
+ // damaged: removed all the same (that is the fix the error message names)
624
+ }
625
+ rmRegular(file);
626
+ if (fs.lstatSync(file, { throwIfNoEntry: false }))
627
+ throw new Error(`${file} is not a plain file, so it was not removed. Look at it yourself.`);
628
+ return { finished: true, ...(keyid ? { previous_keyid: keyid } : {}) };
345
629
  }
346
630
  // ---- W-05: the slip key ----
347
631
  // A SEPARATE Ed25519 key per profile, used only to sign and check permission slips (slips.ts), never
@@ -402,3 +686,121 @@ export function ensureSlipKey() {
402
686
  throw new SlipError("The slip key could not be made.");
403
687
  return k;
404
688
  }
689
+ // ---- v1.1 workstream 4: rotating the slip key ----
690
+ // The slip key signs permission slips, their use files and saved-page manifests (saved.ts). Replacing it makes
691
+ // every existing slip fail its signature check, so slips.rotateSlipKey revokes them all first (and again after,
692
+ // for any granted meanwhile). The old key's PUBLIC half is kept in keys/slips.retired.json, so `saved verify` can
693
+ // still check snapshots signed before the rotation and say which key signed them. A retired key never checks a
694
+ // slip. The private half is gone with the old file.
695
+ export const SLIP_RETIRED_FILE = "slips.retired.json";
696
+ // Every retired public half is kept (each is under 100 bytes); none is ever dropped (Codex K.5). The caps only stop a
697
+ // planted giant file; a rotation that would pass them is refused before anything changes.
698
+ const MAX_RETIRED = 100_000;
699
+ const MAX_RETIRED_BYTES = 16 * 1024 * 1024;
700
+ export const SLIP_ROTATE_LOCK = "slips.rotate"; // keys/slips.rotate.lock
701
+ const X_RE = /^[A-Za-z0-9_-]{43}$/;
702
+ // The retired public halves, oldest first. Absent file: none. Anything else wrong is a SlipError.
703
+ function readRetired() {
704
+ const d = keysDir(false);
705
+ if (!d)
706
+ return [];
707
+ const file = path.join(d, SLIP_RETIRED_FILE);
708
+ let fd;
709
+ try {
710
+ fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW | NONBLOCK);
711
+ }
712
+ catch (e) {
713
+ if (e.code === "ENOENT")
714
+ return [];
715
+ throw new SlipError(`The list of retired slip keys cannot be opened (${e.code ?? "error"}).`);
716
+ }
717
+ try {
718
+ ownFile(fd, file);
719
+ const st = fs.fstatSync(fd);
720
+ if (st.size > MAX_RETIRED_BYTES)
721
+ throw new SlipError("The list of retired slip keys is too large to be one of Tiresias's.");
722
+ let o;
723
+ try {
724
+ o = JSON.parse(fs.readFileSync(fd, "utf8"));
725
+ }
726
+ catch {
727
+ throw new SlipError("The list of retired slip keys is damaged (not valid JSON). Look at keys/slips.retired.json.");
728
+ }
729
+ const keys = o?.keys;
730
+ if (o?.v !== 1 || !Array.isArray(keys) || keys.length > MAX_RETIRED)
731
+ throw new SlipError("The list of retired slip keys is damaged. Look at keys/slips.retired.json.");
732
+ return keys.map((k) => {
733
+ const x = k?.x;
734
+ const at = k?.retired_at;
735
+ if (typeof x !== "string" || !X_RE.test(x) || typeof at !== "string" || Number.isNaN(Date.parse(at)))
736
+ throw new SlipError("The list of retired slip keys is damaged. Look at keys/slips.retired.json.");
737
+ return { x, retired_at: at };
738
+ });
739
+ }
740
+ catch (e) {
741
+ if (e instanceof SlipError)
742
+ throw e;
743
+ throw new SlipError(`The list of retired slip keys cannot be used (${e.message.replace(/[\r\n]/g, " ").slice(0, 120)}).`);
744
+ }
745
+ finally {
746
+ fs.closeSync(fd);
747
+ }
748
+ }
749
+ // The retired slip keys as public key objects, newest first, for checking old saved pages only.
750
+ export function retiredSlipKeys() {
751
+ return readRetired()
752
+ .reverse()
753
+ .map((k) => ({ pub: createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: k.x }, format: "jwk" }), retired_at: k.retired_at }));
754
+ }
755
+ // Put a new slip key in place of the old one. The old public half goes to the retired list FIRST, so a rotation cut
756
+ // short never leaves a saved page that nothing can check. A slip key that cannot be read (damaged, readable by
757
+ // others) is replaced all the same, without a retired entry: that is the fix. Callers (slips.rotateSlipKey) revoke
758
+ // the slips and check the confirmation; this only swaps the key.
759
+ export function replaceSlipKey(now = Date.now(), beforeSwap) {
760
+ if (isPrivate())
761
+ throw new SlipError("Private mode: nothing is written, so the slip key is not rotated.");
762
+ const why = syncedFolderReason();
763
+ if (why)
764
+ throw new SlipError(why.replace("your private signing key", "your private keys"));
765
+ const d = keysDir(true);
766
+ // One slip rotation at a time (Codex K.3): two at once could both retire the same old key, losing the middle one.
767
+ const r = withRotateLock(d, 1000, () => replaceSlipLocked(d, now, beforeSwap), SLIP_ROTATE_LOCK);
768
+ if (r === BUSY)
769
+ throw new SlipError("Another slip key rotation is under way. Try again in a moment. Nothing was changed.");
770
+ return r;
771
+ }
772
+ function replaceSlipLocked(d, now, beforeSwap) {
773
+ const file = path.join(d, SLIP_KEY_FILE);
774
+ const had = !!fs.lstatSync(file, { throwIfNoEntry: false });
775
+ let x = null;
776
+ try {
777
+ x = inspectKeyFile(SLIP_KEY_FILE, SLIP)?.jwk?.x ?? null;
778
+ }
779
+ catch {
780
+ x = null; // unusable: replaced without a retired entry
781
+ }
782
+ let body = null;
783
+ if (x) {
784
+ const list = readRetired().filter((k) => k.x !== x);
785
+ list.push({ x, retired_at: new Date(now).toISOString() });
786
+ body = Buffer.from(JSON.stringify({ v: 1, keys: list }) + "\n");
787
+ if (list.length > MAX_RETIRED || body.length > MAX_RETIRED_BYTES)
788
+ throw new SlipError(`The list of retired slip keys is full (${MAX_RETIRED.toLocaleString("en-US")} keys). Rotating again would drop a key that old saved pages need, so it is refused. Nothing was changed.`);
789
+ }
790
+ // Every refusal is above this line: only now do the callers' irreversible steps (revoking the slips) run (Codex K.4).
791
+ beforeSwap?.();
792
+ // Looked at again just before the swap: the key being retired must still be the current one.
793
+ let again = null;
794
+ try {
795
+ again = inspectKeyFile(SLIP_KEY_FILE, SLIP)?.jwk?.x ?? null;
796
+ }
797
+ catch {
798
+ again = null;
799
+ }
800
+ if (again !== x)
801
+ throw new SlipError("The slip key changed while rotating. Nothing was replaced. Run the rotation again.");
802
+ if (body)
803
+ writeSecret(path.join(d, SLIP_RETIRED_FILE), body, "replace");
804
+ writeSecret(file, newKeyBody().body, "replace");
805
+ return { had_key: had, retired: !!x };
806
+ }