visualproof 0.4.4 → 0.6.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 (82) hide show
  1. package/README.md +16 -7
  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 +132 -117
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/mcp/visualproof-mcp.mjs +20 -9
  19. package/dist/server/access.js +31 -1
  20. package/dist/server/accesspage.js +130 -0
  21. package/dist/server/agent.js +143 -50
  22. package/dist/server/askfollow.js +1 -1
  23. package/dist/server/buildwatch.js +133 -0
  24. package/dist/server/deploy.js +995 -0
  25. package/dist/server/doctor.js +15 -3
  26. package/dist/server/film.js +1 -1
  27. package/dist/server/historyapi.js +100 -50
  28. package/dist/server/historythread.js +206 -0
  29. package/dist/server/hover.js +8 -0
  30. package/dist/server/invites.js +113 -20
  31. package/dist/server/live.js +308 -60
  32. package/dist/server/main.js +450 -77
  33. package/dist/server/mcptools.js +33 -20
  34. package/dist/server/presence.js +3 -3
  35. package/dist/server/prompt.js +8 -3
  36. package/dist/server/readonlygate.js +4 -4
  37. package/dist/server/review.js +27 -7
  38. package/dist/server/reviewapi.js +51 -17
  39. package/dist/server/status.js +119 -46
  40. package/dist/server/talk.js +231 -115
  41. package/dist/server/tokens.js +10 -2
  42. package/dist/server/usage.js +51 -0
  43. package/dist/shared/board.js +2 -1
  44. package/dist/shared/build.js +35 -1
  45. package/dist/shared/collab.js +8 -0
  46. package/dist/shared/deploy.js +35 -0
  47. package/dist/shared/keys.js +66 -37
  48. package/dist/shared/layout.js +297 -70
  49. package/dist/shared/libm.js +366 -0
  50. package/dist/shared/lostfound.js +1 -0
  51. package/dist/shared/mentions.js +83 -0
  52. package/dist/shared/palette.js +1 -1
  53. package/dist/shared/query.js +13 -4
  54. package/dist/shared/review.js +91 -21
  55. package/dist/shared/reviewqueue.js +6 -1
  56. package/dist/shared/separate.js +556 -32
  57. package/dist/web/bundle/app.js +5022 -2736
  58. package/dist/web/bundle/edges.js +2 -1
  59. package/dist/web/bundle/layout.js +1026 -80
  60. package/dist/web/index.html +45 -9
  61. package/dist/web/src/canvas.js +47 -34
  62. package/dist/web/src/overview.js +4 -1
  63. package/dist/web/src/reviewqueue.js +52 -19
  64. package/dist/web/src/scene.js +13 -12
  65. package/dist/web/src/status.js +28 -0
  66. package/dist/web/src/theme.js +108 -0
  67. package/dist/web/src/trust.js +271 -0
  68. package/dist/web/style.css +283 -105
  69. package/docs/agent-api/README.md +13 -11
  70. package/docs/agent-api/advice.md +8 -2
  71. package/docs/agent-api/export.md +1 -1
  72. package/docs/agent-api/following.md +11 -12
  73. package/docs/agent-api/history.md +6 -2
  74. package/docs/agent-api/mcp.md +15 -15
  75. package/docs/agent-api/notes.md +1 -1
  76. package/docs/agent-api/reading.md +2 -2
  77. package/docs/agent-api/requests.md +16 -18
  78. package/docs/agent-api/talking.md +60 -55
  79. package/docs/agent-api/tcb.md +21 -21
  80. package/docs/agent-api/views.md +3 -4
  81. package/docs/agent-api/words.md +8 -8
  82. package/package.json +2 -1
@@ -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
+ }