visualproof 0.5.0 → 0.7.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 (107) hide show
  1. package/README.md +2 -2
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-keys.webp +0 -0
  9. package/dist/assets/tips/tour-library.webp +0 -0
  10. package/dist/assets/tips/tour-project.webp +0 -0
  11. package/dist/assets/tips/tour-review.webp +0 -0
  12. package/dist/assets/tips/tour-share.webp +0 -0
  13. package/dist/assets/tips/tour-source.webp +0 -0
  14. package/dist/assets/tips/tour-target.webp +0 -0
  15. package/dist/assets/tips/tour-view.webp +0 -0
  16. package/dist/assets/tips/tour.json +125 -115
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/extractor/Extract.lean +13 -3
  19. package/dist/mcp/visualproof-mcp.mjs +20 -9
  20. package/dist/server/access.js +28 -0
  21. package/dist/server/agent.js +130 -2819
  22. package/dist/server/agentactivity.js +72 -0
  23. package/dist/server/agentadvice.js +115 -0
  24. package/dist/server/agentdocs.js +1 -1
  25. package/dist/server/agententry.js +180 -0
  26. package/dist/server/agentexport.js +469 -0
  27. package/dist/server/agentfollow.js +384 -0
  28. package/dist/server/agentgraph.js +128 -0
  29. package/dist/server/agentlean.js +144 -0
  30. package/dist/server/agentlibrary.js +1 -1
  31. package/dist/server/agentplaces.js +242 -0
  32. package/dist/server/agentread.js +569 -0
  33. package/dist/server/agenttalk.js +282 -0
  34. package/dist/server/agenttcb.js +378 -0
  35. package/dist/server/agentviews.js +2 -2
  36. package/dist/server/app.js +377 -0
  37. package/dist/server/appaccess.js +127 -0
  38. package/dist/server/appagent.js +110 -0
  39. package/dist/server/appgraph.js +176 -0
  40. package/dist/server/appshare.js +179 -0
  41. package/dist/server/appsite.js +120 -0
  42. package/dist/server/apptalk.js +178 -0
  43. package/dist/server/artcmd.js +1 -1
  44. package/dist/server/askfollow.js +1 -1
  45. package/dist/server/deploy.js +204 -53
  46. package/dist/server/events.js +1 -1
  47. package/dist/server/history.js +51 -3
  48. package/dist/server/historyapi.js +34 -2
  49. package/dist/server/hover.js +11 -7
  50. package/dist/server/identity.js +1 -1
  51. package/dist/server/invites.js +113 -20
  52. package/dist/server/libraryroute.js +3 -3
  53. package/dist/server/live.js +186 -30
  54. package/dist/server/main.js +31 -1613
  55. package/dist/server/mcptools.js +33 -20
  56. package/dist/server/options.js +350 -0
  57. package/dist/server/outside.js +311 -0
  58. package/dist/server/pastdoc.js +22 -3
  59. package/dist/server/presence.js +3 -3
  60. package/dist/server/project.js +28 -4
  61. package/dist/server/prompt.js +8 -3
  62. package/dist/server/readonlygate.js +4 -4
  63. package/dist/server/reviewapi.js +51 -17
  64. package/dist/server/send.js +259 -0
  65. package/dist/server/talk.js +238 -116
  66. package/dist/server/tokens.js +13 -5
  67. package/dist/server/view.js +3 -1
  68. package/dist/server/views.js +1 -1
  69. package/dist/shared/artrecipe.js +3 -3
  70. package/dist/shared/build.js +35 -1
  71. package/dist/shared/collab.js +9 -1
  72. package/dist/shared/comment.js +1 -1
  73. package/dist/shared/doc/build.js +30 -14
  74. package/dist/shared/doc/latex.js +7 -2
  75. package/dist/shared/doc/model.js +4 -2
  76. package/dist/shared/doc/sections.js +21 -4
  77. package/dist/shared/keys.js +66 -37
  78. package/dist/shared/lostfound.js +1 -0
  79. package/dist/shared/mentions.js +83 -0
  80. package/dist/shared/outside.js +16 -0
  81. package/dist/shared/pastgraph.js +11 -2
  82. package/dist/shared/query.js +13 -4
  83. package/dist/shared/review.js +91 -21
  84. package/dist/shared/reviewqueue.js +6 -1
  85. package/dist/shared/scope.js +1 -1
  86. package/dist/web/bundle/app.js +51289 -49853
  87. package/dist/web/index.html +45 -9
  88. package/dist/web/src/reviewqueue.js +52 -19
  89. package/dist/web/src/selection.js +1 -1
  90. package/dist/web/src/theme.js +1 -1
  91. package/dist/web/src/trust.js +271 -0
  92. package/dist/web/src/visitors.js +1 -1
  93. package/dist/web/style.css +181 -70
  94. package/docs/agent-api/README.md +13 -11
  95. package/docs/agent-api/advice.md +8 -2
  96. package/docs/agent-api/export.md +9 -6
  97. package/docs/agent-api/following.md +11 -12
  98. package/docs/agent-api/history.md +6 -3
  99. package/docs/agent-api/mcp.md +15 -15
  100. package/docs/agent-api/notes.md +1 -1
  101. package/docs/agent-api/reading.md +10 -4
  102. package/docs/agent-api/requests.md +12 -15
  103. package/docs/agent-api/talking.md +60 -55
  104. package/docs/agent-api/tcb.md +21 -21
  105. package/docs/agent-api/views.md +3 -4
  106. package/docs/agent-api/words.md +8 -8
  107. package/package.json +2 -1
@@ -19,6 +19,11 @@
19
19
  // history/sources/<sha256>.gz one text of a project file (server/sourcestore.ts)
20
20
  // history/snapshots/<id>.json.gz a snapshot's manifest: module → content hash, and module →
21
21
  // the text its build compiled (`sources`)
22
+ //
23
+ // The sources outside the project — the packages', Lean's core's — are not kept (HistorySpec
24
+ // decision 24, the owner's of 2026-10-20): a snapshot records each package's revision as the
25
+ // lake-manifest pinned it (`packages`; the core's is its toolchain), and a past build shows an
26
+ // outside declaration's source only where its package is at that revision now.
22
27
  // history/index.jsonl one line per snapshot (SnapshotInfo), appended; the last line
23
28
  // of an id is what it is (a build read again supersedes)
24
29
  //
@@ -72,6 +77,42 @@ export function commitNow(root) {
72
77
  const status = git(root, "status", "--porcelain", "--untracked-files=no", "--", "*.lean");
73
78
  return { hash, branch: branch && branch !== "HEAD" ? branch : null, ...(status ? { dirty: true } : {}) };
74
79
  }
80
+ /** Each package's revision as a lake-manifest's text pins it (a past build's, from its commit):
81
+ * name → rev; null where the text is not a manifest. */
82
+ export function manifestRevisions(text) {
83
+ try {
84
+ const m = JSON.parse(text);
85
+ if (!Array.isArray(m.packages))
86
+ return null;
87
+ const out = {};
88
+ for (const p of m.packages)
89
+ if (typeof p?.name === "string" && p.name && typeof p.rev === "string" && p.rev)
90
+ out[p.name] = p.rev;
91
+ return out;
92
+ }
93
+ catch {
94
+ return null;
95
+ }
96
+ }
97
+ /** Give the snapshots read before 0.7.0 recorded them their packages' revisions (HistorySpec
98
+ * decision 24): each one's commit's lake-manifest.json, where its commit is known (not guessed) and
99
+ * its `.lean` files were that commit's (not dirty); read-only git, once (a snapshot given them is
100
+ * not looked at again). How many were given theirs. */
101
+ export function backfillPackages(h, root) {
102
+ let n = 0;
103
+ for (const s of h.list()) {
104
+ const c = s.commit;
105
+ if (s.packages || !c || c.guessed || c.dirty || !/^[0-9a-f]{7,64}$/.test(c.hash))
106
+ continue;
107
+ const text = git(root, "show", `${c.hash}:./lake-manifest.json`);
108
+ const revs = text === null ? null : manifestRevisions(text);
109
+ if (!revs)
110
+ continue;
111
+ h.annotate(s.id, { packages: { revs, from: "commit" } });
112
+ n++;
113
+ }
114
+ return n;
115
+ }
75
116
  /** The project's git source and the commit checked out, as a page may show them (an artwork's foot,
76
117
  * ExportSpec decision 19): the remote's address (`origin`, else the first) with no user name or
77
118
  * password (sourceAddress); null where the project is not a git repository. Read-only, as `git`. */
@@ -213,7 +254,7 @@ function records(g) {
213
254
  r.out.push([src, at.get(dst), m]);
214
255
  }
215
256
  }
216
- const externals = g.externals.map((e) => ({ name: e.name, kind: e.kind, module: e.module, ax: axNames(e.ax) })).sort((a, b) => (a.name < b.name ? -1 : 1));
257
+ const externals = g.externals.map((e) => ({ name: e.name, kind: e.kind, module: e.module, ax: axNames(e.ax), ...(e.range ? { range: e.range } : {}) })).sort((a, b) => (a.name < b.name ? -1 : 1));
217
258
  return { modules: [...byModule.values()].sort((a, b) => (a.module < b.module ? -1 : 1)), externals, edges };
218
259
  }
219
260
  function snapNode(v, g, ax) {
@@ -419,6 +460,8 @@ export class History {
419
460
  ...(same?.renames ? { renames: same.renames } : {}),
420
461
  ...(texts ? { sources: texts } : {}),
421
462
  ...(o.tool ? { tool: o.tool } : {}),
463
+ // the packages' revisions as read now; a build read again before 0.7.0 keeps what was found
464
+ ...(o.packages ? { packages: { revs: o.packages, from: "read" } } : same?.packages ? { packages: same.packages } : {}),
422
465
  };
423
466
  this.save(info);
424
467
  this.readOf(id).add(o.fingerprint);
@@ -474,6 +517,11 @@ export class History {
474
517
  const text = ref.blob ? this.sources.text(ref.blob) : null;
475
518
  return { ref: ref.blob && text === null ? { ...ref, blob: undefined, why: "its kept text cannot be read" } : ref, text };
476
519
  }
520
+ /** The modules snapshot `id`'s outside declarations are in. */
521
+ outsideModulesOf(id) {
522
+ const g = this.graph(id);
523
+ return new Set(g ? g.nodes.slice(g.projectCount).map((v) => v.module) : []);
524
+ }
477
525
  /** The modules snapshot `id` holds. */
478
526
  modulesOf(id) {
479
527
  return Object.keys(this.manifest(id)?.modules ?? {}).sort();
@@ -523,7 +571,7 @@ export class History {
523
571
  }
524
572
  const projectCount = nodes.length;
525
573
  for (const e of externals)
526
- nodes.push({ name: e.name, kind: e.kind, module: e.module, type: "", ax: e.ax, hash: "", ext: true });
574
+ nodes.push({ name: e.name, kind: e.kind, module: e.module, type: "", ax: e.ax, hash: "", ext: true, ...(e.range ? { range: e.range } : {}) });
527
575
  const index = new Map(nodes.map((v, i) => [v.name, i]));
528
576
  const edges = [];
529
577
  recs.forEach((r, k) => {
@@ -770,7 +818,7 @@ export function pageGraph(g, identity) {
770
818
  };
771
819
  const nodes = g.nodes.map((v) => {
772
820
  if (v.ext)
773
- return { name: v.name, kind: v.kind, module: v.module, ax: axOf(v.ax), ext: true };
821
+ return { name: v.name, kind: v.kind, module: v.module, ax: axOf(v.ax), ext: true, ...(v.range ? { range: v.range } : {}) };
774
822
  const { ax, hash, shape: _s, refs: _r, ...rest } = v;
775
823
  return { ...rest, ax: axOf(ax), hash: snapVersion(v, identity), ...(v.shape ? { kernel: hash } : {}) };
776
824
  });
@@ -18,6 +18,7 @@
18
18
  import { dirname } from "node:path";
19
19
  import { MAX_ARCHIVE_KEYS, validKey } from "./lostfound.js";
20
20
  import { offThread, runJob } from "./historythread.js";
21
+ import { outsideSource } from "./outside.js";
21
22
  const no = (status, error) => ({ status, body: { error } });
22
23
  const ok = (body) => ({ status: 200, body });
23
24
  /** the parts of the last snapshots asked, per history, by snapshot, build read and renames */
@@ -87,10 +88,13 @@ export async function snapshotParts(w, id) {
87
88
  /** Module `module`'s text at snapshot `id`'s build (GET /source; HistorySpec decision 23): the
88
89
  * text its build was compiled from, with its Lake hash and how it was matched to the build, or
89
90
  * why it is not kept. Never another text. */
90
- export function pastSource(h, id, module) {
91
+ export function pastSource(h, id, module, outsideNow) {
91
92
  const s = h.get(id);
92
93
  const t = h.textOf(id, module);
93
94
  const build = { snapshot: id, at: s.at, commit: s.commit };
95
+ // a module of the outside world that build referred to (HistorySpec decision 24)
96
+ if (!t && outsideNow && !h.modulesOf(id).includes(module) && h.outsideModulesOf(id).has(module))
97
+ return pastOutside(s, module, outsideNow);
94
98
  if (!t) {
95
99
  const why = h.sourcesOf(id) === null ? "the texts of this build are still being looked for" : h.modulesOf(id).includes(module) ? "its module has no file of the project" : `the build has no module ${module.slice(0, 300)}`;
96
100
  return { status: 404, body: { error: `The text of ${module.slice(0, 300)} at this build is not kept: ${why}.`, kept: false, why, ...build } };
@@ -99,6 +103,32 @@ export function pastSource(h, id, module) {
99
103
  return { status: 404, body: { error: `The text of ${module} at this build is not kept: ${t.ref.why ?? "it was not found"}.`, kept: false, why: t.ref.why ?? null, file: t.ref.file, ...build } };
100
104
  return { status: 200, body: { module, file: t.ref.file, text: t.text, lake: t.ref.lake ?? null, check: t.ref.check, from: t.ref.from ?? null, ...build } };
101
105
  }
106
+ /** A short revision, as the answers say it: a commit's first seven characters, a release whole. */
107
+ const shortRev = (r) => (!r ? "an unrecorded revision" : /^[0-9a-f]{40,64}$/.test(r) ? r.slice(0, 7) : r);
108
+ /** Outside module `module`'s text at snapshot `s`'s build (HistorySpec decision 24, the owner's of
109
+ * 2026-10-20): outside sources are not kept per build, so it is the file as it is now where its
110
+ * package is at the revision that build had — the lake-manifest's `rev` then, recorded with the
111
+ * snapshot; for Lean's core, its toolchain — and otherwise not kept, said so with both revisions.
112
+ * `check: "rev"`: matched to the build by its package's revision. */
113
+ export function pastOutside(s, module, outsideNow) {
114
+ const build = { snapshot: s.id, at: s.at, commit: s.commit };
115
+ const no = (why, file) => ({ status: 404, body: { error: `The text of ${module.slice(0, 300)} at this build was not kept: ${why}.`, kept: false, why, outside: true, ...(file ? { file } : {}), ...build } });
116
+ const now = outsideNow(module);
117
+ if (!now)
118
+ return no("outside sources are not kept per build, and its file is not found outside the project now");
119
+ const p = now.file.package;
120
+ const revs = s.packages?.revs;
121
+ const then = p.core ? s.toolchain : revs && Object.hasOwn(revs, p.name) ? revs[p.name] : null;
122
+ const rev = p.core ? now.toolchain : p.rev;
123
+ if (!p.core && !s.packages)
124
+ return no(`outside sources are not kept per build, and the revisions of this build's packages were not recorded`, now.file.file);
125
+ if (!then || !rev || then !== rev)
126
+ return no(`outside sources are not kept per build, and ${p.core ? `the toolchain, whose core it is in, was ${then} then and is ${rev} now` : `${p.name} was at ${shortRev(then)} then and is at ${shortRev(rev)} now`}`, now.file.file);
127
+ const src = outsideSource(now.file);
128
+ if (!src)
129
+ return no("outside sources are not kept per build, and its file cannot be read now", now.file.file);
130
+ return { status: 200, body: { module, file: src.file, text: src.text, lake: null, check: "rev", from: "outside", outside: src.outside, ...build } };
131
+ }
102
132
  /** A snapshot named in the query, `id` (or another key): the snapshot, or why not. The latest
103
133
  * build's where it is left out and `dflt` says so. */
104
134
  function snapshotOf(w, a, key, dflt) {
@@ -198,7 +228,8 @@ export async function historyAnswer(w, a, refuse = () => null) {
198
228
  const module = a.query.get("module") ?? "";
199
229
  if (!module || module.length > 2000)
200
230
  return no(400, "Say which module: module=<its name>.");
201
- return pastSource(h, id, module);
231
+ // asked of the world as a method: the live server's reads its own state
232
+ return pastSource(h, id, module, w.outsideNow && ((m) => w.outsideNow(m)));
202
233
  }
203
234
  if (path === "/diff") {
204
235
  const from = snapshotOf(w, a, "from", false);
@@ -273,6 +304,7 @@ export function historyWorld(world) {
273
304
  lastHad: (name) => world.lastHad?.(name) ?? null,
274
305
  archiveEntries: (keys, on, who) => world.archiveEntries?.(keys, on, who) ?? { status: 404, body: { error: "not found" } },
275
306
  following: () => world.following?.() ?? null,
307
+ outsideNow: (module) => world.outsideNow?.(module) ?? null,
276
308
  };
277
309
  }
278
310
  /** The same, as endpoints of the agents' API (server/agent.ts): reading only, at every level. */
@@ -6,7 +6,10 @@
6
6
  // lakefile in the directory it was started from. Started elsewhere with the project's LEAN_PATH,
7
7
  // it reads the `.olean` files the owner's builds left and writes nothing (SPEC.md: "No .lake
8
8
  // conflict"). It elaborates the file it is asked about once, then answers hovers in milliseconds.
9
- // At most two files are kept open; the server stops after ten idle minutes.
9
+ // At most two files are kept open; the server stops after ten idle minutes. A file outside the
10
+ // project — a package's, Lean's core's, whose source the window shows too (the owner's decision of
11
+ // 2026-10-20; server/outside.ts) — is opened by the same Lean in the same way: elaborated against
12
+ // the `.olean` files of what it imports, nothing built.
10
13
  //
11
14
  // A name in a hover card opens a card of its own: what Lean says about a declaration by name is
12
15
  // asked in a scratch file of VisualProof's (in the project's cache, never in the project) that
@@ -358,10 +361,11 @@ export class LeanHover {
358
361
  this.idle.unref();
359
362
  }
360
363
  /** Have Lean elaborate a file (its present text), keeping at most KEEP_OPEN open. */
361
- async open(rel, text, hash) {
364
+ async open(file, text, hash) {
362
365
  await this.start();
363
366
  this.touch();
364
- const uri = pathToFileURL(join(this.project.root, rel)).href;
367
+ const rel = typeof file === "string" ? file : file.name;
368
+ const uri = pathToFileURL(typeof file === "string" ? join(this.project.root, file) : file.path).href;
365
369
  let doc = this.docs.get(rel);
366
370
  if (doc)
367
371
  this.unstall(doc, doc.processing >= 0);
@@ -397,10 +401,10 @@ export class LeanHover {
397
401
  }
398
402
  /** What is at (line, character) of the file — UTF-16 columns, as the page counts them. Waits
399
403
  * up to `waitMs` for Lean to elaborate that far, then says how far it is. */
400
- async hover(rel, text, hash, line, character, waitMs) {
404
+ async hover(file, text, hash, line, character, waitMs) {
401
405
  let doc;
402
406
  try {
403
- doc = await this.open(rel, text, hash);
407
+ doc = await this.open(file, text, hash);
404
408
  }
405
409
  catch (e) {
406
410
  return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
@@ -417,10 +421,10 @@ export class LeanHover {
417
421
  * hover's code — a declaration's full name where the position refers to one, a variable's name
418
422
  * where it is one — or null where Lean has nothing to say. This is how the source window links
419
423
  * every name to what it means, dot notation and `open`s included, as go-to-definition would. */
420
- async names(rel, text, hash, positions, waitMs) {
424
+ async names(file, text, hash, positions, waitMs) {
421
425
  let doc;
422
426
  try {
423
- doc = await this.open(rel, text, hash);
427
+ doc = await this.open(file, text, hash);
424
428
  }
425
429
  catch (e) {
426
430
  return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
@@ -131,7 +131,7 @@ export function headerText(s) {
131
131
  * in the agents' answers. This is where a private reader's anonymity lives: whatever arranges a
132
132
  * board — pins, folds, re-layouts, scopes and clusterings, views made, renamed and deleted, notes
133
133
  * left on a board — takes its author from here, through server/views.ts (`handle`, whose `me` is
134
- * this) and main.ts (an undo). The review is not layout: opinions, targets, key marks and trust
134
+ * this) and appsite.ts (an undo). The review is not layout: opinions, targets, key marks and trust
135
135
  * take the caller's own name, and need one. */
136
136
  export function layoutAuthor(caller) {
137
137
  return caller.private ? null : caller.name;
@@ -20,11 +20,22 @@
20
20
  // Share lists every link in force with when it was last used, so that one nobody uses any more is
21
21
  // seen and revoked, which cuts it off at once — its pages' event streams too.
22
22
  //
23
- // The token is shown once, to whoever made it, for them to send: the server keeps only its digest,
24
- // in `<site>/person-invites.json` (readable by its owner alone, as the access key and the agents'
25
- // tokens are). Showing it again would let anyone on the server be that person. Revoked links are
26
- // kept, with every name their holders went by, so that what they did keeps its name; they never let
27
- // anyone in again. When a link was last used is written at most once a minute, as an agent token's.
23
+ // The token is shown once to whoever made it, for them to send, and again to its holder alone (the
24
+ // owner's decision of 2026-10-19): someone who wants to open the site as themselves in another
25
+ // browser, on another device, finds it in the menu under their name. So the server keeps it in
26
+ // full, in `<site>/person-invites.json` (readable by its owner alone, as the access key, the agents'
27
+ // tokens and the read-only links are), beside its digest — what a link opened is compared with, what
28
+ // its cookie is made from, and all that a server before 0.6.0 kept: such a link cannot be shown, and
29
+ // its holder is offered to make it anew. Shown to anyone else, it would let them be that person.
30
+ //
31
+ // Made anew, a link keeps its id — the same person, log and names — under a new secret: the old
32
+ // link, and every cookie made from it, let nobody in from now on, and its pages' event streams end
33
+ // but the one of the page that made it anew, whose browser is given the new cookie. The old digests
34
+ // are kept (the last few), so that a browser the old link let in is told that it no longer does, as
35
+ // a revoked link's is, rather than its page trying again as if the server were down. Revoked links
36
+ // are kept, with every name their holders went by, so that what they did keeps its name; they never
37
+ // let anyone in again. When a link was last used is written at most once a minute, as an agent
38
+ // token's.
28
39
  import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
29
40
  import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
30
41
  import { join } from "node:path";
@@ -41,10 +52,14 @@ const COOKIE = "visualproof_person";
41
52
  const MAX_AGE = 400 * 24 * 3600;
42
53
  const FLUSH_MS = 60_000;
43
54
  const SECRET = /^[A-Za-z0-9_-]{43}$/;
55
+ /** how many of a link's old digests are kept once it was made anew: the browsers they let in are
56
+ * told the link no longer does */
57
+ const REPLACED_KEPT = 16;
44
58
  const sha = (s) => createHash("sha256").update(s).digest();
45
59
  const digestOf = (token) => sha(`visualproof person link\0${token}`).toString("base64url");
46
- /** the cookie's value for a link: its id, and a digest of what is kept of its token */
47
- const cookieValue = (r) => `${r.id}.${sha(`visualproof person cookie\0${r.digest}`).toString("base64url")}`;
60
+ /** the cookie's value for a link: its id, and a digest of the digest of its token (`digest`: an
61
+ * old one of a link made anew) */
62
+ const cookieValue = (r, digest = r.digest) => `${r.id}.${sha(`visualproof person cookie\0${digest}`).toString("base64url")}`;
48
63
  /** Whether `a` and `b` are the same, in constant time whatever they are. */
49
64
  function same(a, b) {
50
65
  return timingSafeEqual(sha(a), sha(b));
@@ -56,7 +71,8 @@ export class Invites {
56
71
  cookieName;
57
72
  dirty = false;
58
73
  timer = null;
59
- /** told when a link is revoked: its pages' event streams end (server/live.ts) */
74
+ /** told when a link no longer lets in the browsers it let in — revoked, or made anew: its pages'
75
+ * event streams end (server/live.ts), but `keep`, the one of the page that made it anew */
60
76
  onEnded = () => { };
61
77
  /** told when a link was made, renamed or revoked: every page is told the names (`people`) */
62
78
  onChanged = () => { };
@@ -70,7 +86,7 @@ export class Invites {
70
86
  if (typeof data.cookie === "string" && /^[0-9a-f]{12}$/.test(data.cookie))
71
87
  own = data.cookie;
72
88
  if (Array.isArray(data.invites))
73
- this.records = data.invites.filter(isRecord);
89
+ this.records = data.invites.filter(isRecord).map(kept);
74
90
  }
75
91
  catch {
76
92
  // a file that cannot be read lets nobody in by a link; it is kept aside, not overwritten
@@ -99,32 +115,46 @@ export class Invites {
99
115
  do
100
116
  id = randomBytes(5).toString("hex");
101
117
  while (this.records.some((r) => r.id === id));
102
- const token = `${INVITE_PREFIX}${id}_${randomBytes(32).toString("base64url")}`;
103
- const record = { id, digest: digestOf(token), name, names: [{ name, at: now }], by: o.by, created: now, revoked: null, revokedBy: null, lastUsed: null };
118
+ const token = newToken(id);
119
+ const record = { id, digest: digestOf(token), token, name, names: [{ name, at: now }], by: o.by, created: now, revoked: null, revokedBy: null, lastUsed: null };
104
120
  this.records.push(record);
105
121
  this.save();
106
122
  this.onChanged();
107
123
  return { token, record };
108
124
  }
109
125
  /** What a link's token is. Compared in constant time, by digests of one length whatever was sent,
110
- * whether or not its id is known. */
126
+ * whether or not its id is known; then with the link's old ones, if it was made anew. */
111
127
  check(token, now = Date.now()) {
112
128
  if (!token.startsWith(INVITE_PREFIX))
113
129
  return null;
114
130
  const id = token.slice(INVITE_PREFIX.length, INVITE_PREFIX.length + 10);
115
131
  const r = validPersonId(id) && token[INVITE_PREFIX.length + 10] === "_" && SECRET.test(token.slice(INVITE_PREFIX.length + 11)) ? this.get(id) : undefined;
116
- const ok = same(digestOf(token), r?.digest ?? "no such link");
117
- return r && ok ? this.seen(r, now) : null;
132
+ const given = digestOf(token);
133
+ const ok = same(given, r?.digest ?? "no such link");
134
+ if (r && ok)
135
+ return this.seen(r, now);
136
+ return r ? this.old(r, (d) => same(given, d)) : null;
118
137
  }
119
- /** What the cookie a request carries says (its `Cookie` header): a link in force, one revoked
120
- * (whose cookie the browser should forget), or none. */
138
+ /** What the cookie a request carries says (its `Cookie` header): a link in force, one revoked or
139
+ * made anew since the cookie was given (which the browser should forget), or none. */
121
140
  ofCookie(header, now = Date.now()) {
122
141
  const given = cookieOf(header, this.cookieName);
123
142
  if (given === null)
124
143
  return null;
125
144
  const r = given.indexOf(".") === 10 ? this.get(given.slice(0, 10)) : undefined;
126
145
  const ok = same(given, r ? cookieValue(r) : "no such link");
127
- return r && ok ? this.seen(r, now) : null;
146
+ if (r && ok)
147
+ return this.seen(r, now);
148
+ return r ? this.old(r, (d) => same(given, cookieValue(r, d))) : null;
149
+ }
150
+ /** A link's old token or cookie, by `is`, which says whether it is the one of an old digest: the
151
+ * link revoked since, or made anew (when, the latest such); null when it is none of them. */
152
+ old(r, is) {
153
+ // every old digest compared, whichever matches
154
+ const at = (r.replaced ?? []).reduce((found, d) => (is(d.digest) ? d.at : found), null);
155
+ if (at === null)
156
+ return null;
157
+ return r.revoked ? { ended: "revoked", record: r } : { ended: "replaced", record: r, at };
128
158
  }
129
159
  seen(r, now) {
130
160
  if (r.revoked)
@@ -184,6 +214,45 @@ export class Invites {
184
214
  this.onChanged();
185
215
  return true;
186
216
  }
217
+ /** The link of the holder of `id` in force, to show them again (the owner's decision of
218
+ * 2026-10-19): its token; null for a link made before 0.6.0, of which only the digest was kept;
219
+ * undefined for no such link in force. */
220
+ tokenOf(id) {
221
+ const r = this.get(id);
222
+ if (!r || r.revoked)
223
+ return undefined;
224
+ return r.token ?? null;
225
+ }
226
+ /** Make the link in force `id` anew, for its holder (the owner's decision of 2026-10-19): a new
227
+ * secret under the same id, so the same person, log and names. The old link and every cookie it
228
+ * gave let nobody in from now on, and are told so; its pages' event streams end, but `keep` (the
229
+ * page that made it anew, whose browser is given the new cookie). The new token and the record,
230
+ * or null for no such link in force. */
231
+ renew(id, o = {}) {
232
+ const r = this.get(id);
233
+ if (!r || r.revoked)
234
+ return null;
235
+ const token = newToken(r.id);
236
+ const was = { digest: r.digest, token: r.token, replaced: r.replaced };
237
+ r.replaced = [...(r.replaced ?? []), { digest: r.digest, at: new Date(o.now ?? Date.now()).toISOString() }].slice(-REPLACED_KEPT);
238
+ r.digest = digestOf(token);
239
+ r.token = token;
240
+ try {
241
+ this.save();
242
+ }
243
+ catch (e) {
244
+ // not written: the link stays as it was, its browsers in, rather than made anew until the
245
+ // server restarts and reads the old one again
246
+ Object.assign(r, was);
247
+ if (was.token === undefined)
248
+ delete r.token;
249
+ if (was.replaced === undefined)
250
+ delete r.replaced;
251
+ throw e;
252
+ }
253
+ this.onEnded(r, o.keep);
254
+ return { token, record: r };
255
+ }
187
256
  /** Every holder of a link, revoked ones too, as every page is told them (`Invited`). */
188
257
  people() {
189
258
  return this.records.map((r) => ({ id: r.id, name: r.name, was: [...new Set(r.names.map((n) => n.name).filter((n) => n !== r.name))], ...(r.revoked ? { revoked: true } : {}) }));
@@ -200,9 +269,9 @@ export class Invites {
200
269
  this.timer = null;
201
270
  this.flush();
202
271
  }
203
- /** A link as Share shows it: no digest. */
272
+ /** A link as Share shows it: nothing of its token. */
204
273
  static info(r) {
205
- const { digest: _, ...rest } = r;
274
+ const { digest: _d, token: _t, replaced: _r, ...rest } = r;
206
275
  return { ...rest, names: rest.names.map((n) => ({ ...n })) };
207
276
  }
208
277
  save() {
@@ -214,6 +283,10 @@ export class Invites {
214
283
  renameSync(tmp, this.file);
215
284
  }
216
285
  }
286
+ /** A new token for the link of id `id`: its prefix, its id, and 32 random bytes. */
287
+ function newToken(id) {
288
+ return `${INVITE_PREFIX}${id}_${randomBytes(32).toString("base64url")}`;
289
+ }
217
290
  /** Why a name is not to be had: someone with a personal link goes by it. */
218
291
  export function taken(r) {
219
292
  return `“${r.name}” is the name of someone invited with a personal link: choose another.`;
@@ -233,9 +306,29 @@ export function cookieOf(header, name) {
233
306
  }
234
307
  return null;
235
308
  }
236
- /** A record as this server keeps it; anything else is dropped when the file is read. */
309
+ /** A record as this server keeps it; anything else is dropped when the file is read. A record of
310
+ * a server before 0.6.0 has no token. */
237
311
  function isRecord(x) {
238
312
  const r = x;
239
313
  return (!!r && typeof r === "object" && validPersonId(r.id) && typeof r.digest === "string" && typeof r.name === "string" && validName(r.name) &&
240
314
  Array.isArray(r.names) && r.names.every((n) => n && typeof n.name === "string" && typeof n.at === "string") && typeof r.by === "string" && typeof r.created === "string");
241
315
  }
316
+ /** A record as it is kept from now on: its token only where it is this link's own — of its id, and
317
+ * of the digest the link is compared with; one that is not (written in by hand, a copy mended
318
+ * wrongly) is never shown, and the link is as one made before 0.6.0, which its holder may make
319
+ * anew. Its old digests only where they are digests. */
320
+ function kept(r) {
321
+ const out = { ...r };
322
+ const t = r.token;
323
+ const own = typeof t === "string" && t.startsWith(`${INVITE_PREFIX}${r.id}_`) && SECRET.test(t.slice(INVITE_PREFIX.length + 11)) && digestOf(t) === r.digest;
324
+ if (!own)
325
+ delete out.token;
326
+ if (r.replaced !== undefined) {
327
+ const ds = Array.isArray(r.replaced) ? r.replaced.filter((d) => d && typeof d.digest === "string" && typeof d.at === "string") : [];
328
+ if (ds.length)
329
+ out.replaced = ds.slice(-REPLACED_KEPT);
330
+ else
331
+ delete out.replaced;
332
+ }
333
+ return out;
334
+ }
@@ -1,5 +1,5 @@
1
1
  // The library's routes for pages (AttachmentSpec decisions 1–11): `/api/library/…`, behind the same
2
- // access check as the page (main.ts lets a request get here only once it is in). What they do is
2
+ // access check as the page (app.ts lets a request get here only once it is in). What they do is
3
3
  // server/library.ts's, which the agents' endpoints call too (server/agentlibrary.ts); here are only
4
4
  // what HTTP needs: who asks, the body — a file's bytes as they are, sent with the file's name in the
5
5
  // query, or JSON — and answers that are bytes (a file, a page, a clip), sent so that a browser never
@@ -55,7 +55,7 @@ function readBytes(req, limit) {
55
55
  });
56
56
  }
57
57
  /** An uploaded file's bytes, the body as it is; or null, the request answered already (413) where it
58
- * is larger than a file of the library may be. The agents' upload reads its body so too (main.ts). */
58
+ * is larger than a file of the library may be. The agents' upload reads its body so too (appagent.ts). */
59
59
  export async function readUpload(req, res) {
60
60
  try {
61
61
  return await readBytes(req, MAX_FILE);
@@ -63,7 +63,7 @@ export async function readUpload(req, res) {
63
63
  catch (e) {
64
64
  if (!(e instanceof TooLarge))
65
65
  throw e;
66
- // the rest is read and thrown away, and the answer goes once it has all come, as main.ts's
66
+ // the rest is read and thrown away, and the answer goes once it has all come, as send.ts's
67
67
  // tooLarge does: a connection closed while the client still sends is reset on some systems
68
68
  let done = false;
69
69
  const answer = () => {