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.
- package/README.md +2 -2
- package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
- package/dist/assets/tips/phone-fingers.light.webp +0 -0
- package/dist/assets/tips/tour-agent.webp +0 -0
- package/dist/assets/tips/tour-arrange.webp +0 -0
- package/dist/assets/tips/tour-artwork.webp +0 -0
- package/dist/assets/tips/tour-checks.webp +0 -0
- package/dist/assets/tips/tour-keys.webp +0 -0
- package/dist/assets/tips/tour-library.webp +0 -0
- package/dist/assets/tips/tour-project.webp +0 -0
- package/dist/assets/tips/tour-review.webp +0 -0
- package/dist/assets/tips/tour-share.webp +0 -0
- package/dist/assets/tips/tour-source.webp +0 -0
- package/dist/assets/tips/tour-target.webp +0 -0
- package/dist/assets/tips/tour-view.webp +0 -0
- package/dist/assets/tips/tour.json +125 -115
- package/dist/assets/tips/tour.webp +0 -0
- package/dist/extractor/Extract.lean +13 -3
- package/dist/mcp/visualproof-mcp.mjs +20 -9
- package/dist/server/access.js +28 -0
- package/dist/server/agent.js +130 -2819
- package/dist/server/agentactivity.js +72 -0
- package/dist/server/agentadvice.js +115 -0
- package/dist/server/agentdocs.js +1 -1
- package/dist/server/agententry.js +180 -0
- package/dist/server/agentexport.js +469 -0
- package/dist/server/agentfollow.js +384 -0
- package/dist/server/agentgraph.js +128 -0
- package/dist/server/agentlean.js +144 -0
- package/dist/server/agentlibrary.js +1 -1
- package/dist/server/agentplaces.js +242 -0
- package/dist/server/agentread.js +569 -0
- package/dist/server/agenttalk.js +282 -0
- package/dist/server/agenttcb.js +378 -0
- package/dist/server/agentviews.js +2 -2
- package/dist/server/app.js +377 -0
- package/dist/server/appaccess.js +127 -0
- package/dist/server/appagent.js +110 -0
- package/dist/server/appgraph.js +176 -0
- package/dist/server/appshare.js +179 -0
- package/dist/server/appsite.js +120 -0
- package/dist/server/apptalk.js +178 -0
- package/dist/server/artcmd.js +1 -1
- package/dist/server/askfollow.js +1 -1
- package/dist/server/deploy.js +204 -53
- package/dist/server/events.js +1 -1
- package/dist/server/history.js +51 -3
- package/dist/server/historyapi.js +34 -2
- package/dist/server/hover.js +11 -7
- package/dist/server/identity.js +1 -1
- package/dist/server/invites.js +113 -20
- package/dist/server/libraryroute.js +3 -3
- package/dist/server/live.js +186 -30
- package/dist/server/main.js +31 -1613
- package/dist/server/mcptools.js +33 -20
- package/dist/server/options.js +350 -0
- package/dist/server/outside.js +311 -0
- package/dist/server/pastdoc.js +22 -3
- package/dist/server/presence.js +3 -3
- package/dist/server/project.js +28 -4
- package/dist/server/prompt.js +8 -3
- package/dist/server/readonlygate.js +4 -4
- package/dist/server/reviewapi.js +51 -17
- package/dist/server/send.js +259 -0
- package/dist/server/talk.js +238 -116
- package/dist/server/tokens.js +13 -5
- package/dist/server/view.js +3 -1
- package/dist/server/views.js +1 -1
- package/dist/shared/artrecipe.js +3 -3
- package/dist/shared/build.js +35 -1
- package/dist/shared/collab.js +9 -1
- package/dist/shared/comment.js +1 -1
- package/dist/shared/doc/build.js +30 -14
- package/dist/shared/doc/latex.js +7 -2
- package/dist/shared/doc/model.js +4 -2
- package/dist/shared/doc/sections.js +21 -4
- package/dist/shared/keys.js +66 -37
- package/dist/shared/lostfound.js +1 -0
- package/dist/shared/mentions.js +83 -0
- package/dist/shared/outside.js +16 -0
- package/dist/shared/pastgraph.js +11 -2
- package/dist/shared/query.js +13 -4
- package/dist/shared/review.js +91 -21
- package/dist/shared/reviewqueue.js +6 -1
- package/dist/shared/scope.js +1 -1
- package/dist/web/bundle/app.js +51289 -49853
- package/dist/web/index.html +45 -9
- package/dist/web/src/reviewqueue.js +52 -19
- package/dist/web/src/selection.js +1 -1
- package/dist/web/src/theme.js +1 -1
- package/dist/web/src/trust.js +271 -0
- package/dist/web/src/visitors.js +1 -1
- package/dist/web/style.css +181 -70
- package/docs/agent-api/README.md +13 -11
- package/docs/agent-api/advice.md +8 -2
- package/docs/agent-api/export.md +9 -6
- package/docs/agent-api/following.md +11 -12
- package/docs/agent-api/history.md +6 -3
- package/docs/agent-api/mcp.md +15 -15
- package/docs/agent-api/notes.md +1 -1
- package/docs/agent-api/reading.md +10 -4
- package/docs/agent-api/requests.md +12 -15
- package/docs/agent-api/talking.md +60 -55
- package/docs/agent-api/tcb.md +21 -21
- package/docs/agent-api/views.md +3 -4
- package/docs/agent-api/words.md +8 -8
- package/package.json +2 -1
package/dist/server/history.js
CHANGED
|
@@ -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
|
-
|
|
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. */
|
package/dist/server/hover.js
CHANGED
|
@@ -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(
|
|
364
|
+
async open(file, text, hash) {
|
|
362
365
|
await this.start();
|
|
363
366
|
this.touch();
|
|
364
|
-
const
|
|
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(
|
|
404
|
+
async hover(file, text, hash, line, character, waitMs) {
|
|
401
405
|
let doc;
|
|
402
406
|
try {
|
|
403
|
-
doc = await this.open(
|
|
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(
|
|
424
|
+
async names(file, text, hash, positions, waitMs) {
|
|
421
425
|
let doc;
|
|
422
426
|
try {
|
|
423
|
-
doc = await this.open(
|
|
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)) };
|
package/dist/server/identity.js
CHANGED
|
@@ -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
|
|
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;
|
package/dist/server/invites.js
CHANGED
|
@@ -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
|
|
24
|
-
//
|
|
25
|
-
//
|
|
26
|
-
//
|
|
27
|
-
//
|
|
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
|
|
47
|
-
|
|
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
|
|
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 =
|
|
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
|
|
117
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
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:
|
|
272
|
+
/** A link as Share shows it: nothing of its token. */
|
|
204
273
|
static info(r) {
|
|
205
|
-
const { digest:
|
|
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 (
|
|
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 (
|
|
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
|
|
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 = () => {
|