visualproof 0.11.2 → 0.12.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.
@@ -0,0 +1,373 @@
1
+ // The call (CallSpec): one per server, on the LiveKit server the operator names (decisions 1 and 2).
2
+ // The server gives each page that joins a token for the room, and keeps a seat for it: whose page it
3
+ // is, under which name. Who is in the call is LiveKit's list of the room's participants, read while
4
+ // a call may be going on; the server keeps what it reads, tells every page of it (`call`), and
5
+ // removes a participant whose page went and did not come back, one removed on purpose that came back
6
+ // with a token it already had, and one that is no page's at all. A session lasts from its first
7
+ // participant until it has had none for 60 seconds. Nothing of a call is written but the room's id
8
+ // and the secret identities are made with (`<site>/call.json`): no recording, no transcript, nothing
9
+ // in the timeline (decision 7).
10
+ //
11
+ // A participant's identity is `p_` and 22 characters of an HMAC of what the page's tab calls itself
12
+ // in the call (shared/call.ts, CALL_TAB), which nobody else is told: a page that reloads joins as
13
+ // the participant it was, which LiveKit then replaces; nobody can take another page's place by the
14
+ // identity everyone in the call sees; and a server that restarts knows its pages again as they ask
15
+ // for a token anew, the call going on meanwhile on LiveKit.
16
+ import { createHmac, randomBytes } from "node:crypto";
17
+ import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
18
+ import { join } from "node:path";
19
+ import { accessToken, RoomService } from "./livekit.js";
20
+ const FILE = "call.json";
21
+ /** how long a page's token lasts: LiveKit gives a page in the call fresh ones meanwhile */
22
+ export const TOKEN_TTL_S = 600;
23
+ /** how long a call without anyone in it is still the same session */
24
+ export const SESSION_GRACE_MS = 60_000;
25
+ /** how long a page whose stream closed may take to come back before its participant goes */
26
+ export const PAGE_GONE_MS = 45_000;
27
+ /** how often LiveKit is asked who is in the call, while one may be going on */
28
+ export const LOOK_MS = 2_000;
29
+ /** how long after a token was given a call may be starting */
30
+ export const STARTING_MS = 120_000;
31
+ /** how long a participant removed on purpose is kept out, unless a token is given for it again */
32
+ export const REMOVED_MS = 15 * 60_000;
33
+ /** at most this many tokens a minute per page, invites the same */
34
+ export const PER_MINUTE = 10;
35
+ const IDENTITY = /^p_[A-Za-z0-9_-]{22}$/;
36
+ export class CallRoom {
37
+ /** where pages reach LiveKit */
38
+ url;
39
+ /** the LiveKit room: `visualproof-<id>` */
40
+ room;
41
+ service;
42
+ keys;
43
+ secret;
44
+ hooks;
45
+ seats = new Map();
46
+ /** removed on purpose, by identity: when; kept out until a token is given for it again */
47
+ removed = new Map();
48
+ /** who LiveKit listed last, of the pages' participants */
49
+ present = [];
50
+ session = null;
51
+ emptySince = null;
52
+ lastToken = 0;
53
+ started = Date.now();
54
+ /** what the pages were told last */
55
+ told = "";
56
+ timer = null;
57
+ soon = null;
58
+ looking = null;
59
+ again = false;
60
+ rates = new Map();
61
+ /** why LiveKit could not be asked, the last time it could not; null since it answered */
62
+ unavailable = null;
63
+ constructor(o) {
64
+ this.url = o.url;
65
+ this.keys = o.keys;
66
+ this.hooks = o.hooks;
67
+ this.service = new RoomService(o.api, o.keys, o.fetch);
68
+ const kept = o.site ? readKept(join(o.site, FILE)) : null;
69
+ const made = kept ?? { room: randomBytes(6).toString("hex"), secret: randomBytes(32).toString("base64url") };
70
+ if (o.site && !kept)
71
+ writeKept(join(o.site, FILE), made);
72
+ this.room = `visualproof-${made.room}`;
73
+ this.secret = Buffer.from(made.secret, "base64url");
74
+ }
75
+ /** Ask LiveKit who is in the call now, and from then on while a call may be going on. */
76
+ start() {
77
+ void this.look();
78
+ this.timer = setInterval(() => {
79
+ if (this.active())
80
+ void this.look();
81
+ }, LOOK_MS);
82
+ this.timer.unref?.();
83
+ }
84
+ stop() {
85
+ if (this.timer)
86
+ clearInterval(this.timer);
87
+ if (this.soon)
88
+ clearTimeout(this.soon);
89
+ this.timer = this.soon = null;
90
+ }
91
+ /** Whether a call may be going on: one has a session, someone is in it, a token was given lately,
92
+ * or the server has just started and may find one. */
93
+ active(now = Date.now()) {
94
+ return this.session !== null || this.present.length > 0 || now - this.lastToken < STARTING_MS || now - this.started < PAGE_GONE_MS + LOOK_MS;
95
+ }
96
+ /** The identity of the participant a tab joins as. */
97
+ identityOf(tab) {
98
+ return `p_${createHmac("sha256", this.secret).update(`visualproof call\0${tab}`).digest("base64url").slice(0, 22)}`;
99
+ }
100
+ /** 0 where `key` may go now (and it is counted), else the seconds to wait. */
101
+ allow(key, now = Date.now()) {
102
+ const ts = (this.rates.get(key) ?? []).filter((t) => now - t < 60_000);
103
+ if (ts.length >= PER_MINUTE) {
104
+ this.rates.set(key, ts);
105
+ return Math.max(1, Math.ceil((ts[0] + 60_000 - now) / 1000));
106
+ }
107
+ ts.push(now);
108
+ this.rates.set(key, ts);
109
+ if (this.rates.size > 1000)
110
+ for (const [k, v] of this.rates)
111
+ if (!v.some((t) => now - t < 60_000))
112
+ this.rates.delete(k);
113
+ return 0;
114
+ }
115
+ /** A token for `page`'s tab, under `name`; `link` the read-only link it came by, if it did. A token
116
+ * given for an identity removed on purpose lets it in again: joining is deliberate. */
117
+ give(page, tab, name, link, now = Date.now()) {
118
+ const identity = this.identityOf(tab);
119
+ this.removed.delete(identity);
120
+ this.seats.set(identity, { token: page.token, name, link, person: page.person, verified: page.person !== null, gone: null });
121
+ this.lastToken = now;
122
+ const token = accessToken(this.keys, {
123
+ identity,
124
+ name,
125
+ ttl: TOKEN_TTL_S,
126
+ video: {
127
+ room: this.room,
128
+ roomJoin: true,
129
+ canPublish: true,
130
+ canPublishSources: ["camera", "microphone", "screen_share", "screen_share_audio"],
131
+ canSubscribe: true,
132
+ canPublishData: true,
133
+ // the raised hand is the participant's own attribute
134
+ canUpdateOwnMetadata: true,
135
+ },
136
+ }, now);
137
+ this.lookSoon();
138
+ return { url: this.url, token, identity, room: this.room };
139
+ }
140
+ /** The identity of the participant a page has in the call now, or null. */
141
+ inCall(token) {
142
+ for (const p of this.present)
143
+ if (this.seats.get(p.identity)?.token === token)
144
+ return p.identity;
145
+ return null;
146
+ }
147
+ /** Whether a page holds a seat: it was given a token, and has not left. */
148
+ seated(token) {
149
+ for (const s of this.seats.values())
150
+ if (s.token === token)
151
+ return true;
152
+ return false;
153
+ }
154
+ /** A page leaves: its participant is removed now, nothing kept out. */
155
+ async leave(token) {
156
+ const mine = [...this.seats].filter(([, s]) => s.token === token).map(([id]) => id);
157
+ for (const id of mine)
158
+ this.seats.delete(id);
159
+ await Promise.all(mine.map((id) => this.service.remove(this.room, id).catch((e) => this.said(e))));
160
+ this.lookSoon();
161
+ }
162
+ /** Someone in the call removes a participant: it is disconnected, its page told, and kept out
163
+ * until it asks for a token again. False where it is not in the call. */
164
+ async remove(identity, by) {
165
+ if (!this.present.some((p) => p.identity === identity))
166
+ return false;
167
+ const seat = this.seats.get(identity);
168
+ await this.cut(identity);
169
+ if (seat)
170
+ this.hooks.sendTo(seat.token, "call-removed", { by });
171
+ return true;
172
+ }
173
+ /** Remove on purpose, telling nobody: a participant whose read-only or personal link ended. */
174
+ async cut(identity) {
175
+ this.removed.set(identity, Date.now());
176
+ this.seats.delete(identity);
177
+ await this.service.remove(this.room, identity);
178
+ this.lookSoon();
179
+ }
180
+ /** The participants of a page's stream go, on purpose: its link was revoked, or stopped joining
181
+ * the call. */
182
+ cutPage(token) {
183
+ for (const [id, s] of [...this.seats])
184
+ if (s.token === token)
185
+ void this.cut(id).catch((e) => this.said(e));
186
+ }
187
+ /** The participants of read-only link `link` go, on purpose: it no longer joins the call, or was
188
+ * revoked — a page whose stream had closed already too. */
189
+ cutLink(link) {
190
+ for (const [id, s] of [...this.seats])
191
+ if (s.link === link)
192
+ void this.cut(id).catch((e) => this.said(e));
193
+ }
194
+ /** The participants of personal link `person` go, on purpose: it was revoked — a page whose stream
195
+ * had closed already too. */
196
+ cutPerson(person) {
197
+ for (const [id, s] of [...this.seats])
198
+ if (s.person === person)
199
+ void this.cut(id).catch((e) => this.said(e));
200
+ }
201
+ /** End the call for everyone: the room is deleted, every page told; whoever was in it is kept out
202
+ * until they ask for a token again. */
203
+ async end(by) {
204
+ await this.service.deleteRoom(this.room);
205
+ const now = Date.now();
206
+ for (const p of this.present)
207
+ this.removed.set(p.identity, now);
208
+ for (const id of this.seats.keys())
209
+ this.removed.set(id, now);
210
+ this.seats.clear();
211
+ this.present = [];
212
+ this.session = null;
213
+ this.emptySince = null;
214
+ this.hooks.send("call-ended", { by });
215
+ this.publish();
216
+ }
217
+ /** Someone in the call invites the reader of page `to`: their page is told. */
218
+ invite(to, from) {
219
+ const page = this.hooks.pageById(to);
220
+ if (!page || page.private)
221
+ return "none";
222
+ if (this.inCall(page.token))
223
+ return "in";
224
+ this.hooks.sendTo(page.token, "call-invite", { from, at: new Date().toISOString() });
225
+ return "ok";
226
+ }
227
+ /** A page's event stream closed: its participant has a while to come back (a reload, a lost
228
+ * connection) before it goes. */
229
+ streamClosed(token, now = Date.now()) {
230
+ for (const s of this.seats.values())
231
+ if (s.token === token && s.gone === null)
232
+ s.gone = now;
233
+ }
234
+ /** The call as the pages are told it. */
235
+ state() {
236
+ return { session: this.session, participants: this.present.map((p) => this.entry(p)) };
237
+ }
238
+ entry(p) {
239
+ const seat = this.seats.get(p.identity);
240
+ const page = seat && seat.gone === null ? this.hooks.page(seat.token) : null;
241
+ // a page's name as its heartbeats say it now; a read-only reader's as they gave it
242
+ const name = seat ? (seat.link === null ? (page?.name ?? seat.name) : seat.name) : null;
243
+ return {
244
+ id: p.identity,
245
+ name,
246
+ ...(page && !page.private && page.readOnly === null ? { page: page.id } : {}),
247
+ ...(seat?.verified ? { verified: true } : {}),
248
+ ...(seat?.link ? { readOnly: true } : {}),
249
+ joined: p.joinedAt ? new Date(p.joinedAt * 1000).toISOString() : null,
250
+ };
251
+ }
252
+ /** Tell the pages, where something changed. */
253
+ publish() {
254
+ const s = this.state();
255
+ const text = JSON.stringify(s);
256
+ if (text === this.told)
257
+ return;
258
+ this.told = text;
259
+ this.hooks.send("call", s);
260
+ }
261
+ /** Ask LiveKit again in a moment: someone joins, leaves or is removed. */
262
+ lookSoon(ms = 400) {
263
+ if (this.soon)
264
+ return;
265
+ this.soon = setTimeout(() => {
266
+ this.soon = null;
267
+ void this.look();
268
+ }, ms);
269
+ this.soon.unref?.();
270
+ }
271
+ /** Ask LiveKit who is in the call, and act on it: keep out who is to be kept out, start and end
272
+ * the session, tell the pages. One look at a time; one asked meanwhile follows it. */
273
+ look(now) {
274
+ if (this.looking) {
275
+ this.again = true;
276
+ return this.looking;
277
+ }
278
+ this.looking = this.lookNow(now).finally(() => {
279
+ this.looking = null;
280
+ if (this.again) {
281
+ this.again = false;
282
+ void this.look();
283
+ }
284
+ });
285
+ return this.looking;
286
+ }
287
+ async lookNow(at) {
288
+ let list;
289
+ try {
290
+ list = await this.service.participants(this.room);
291
+ }
292
+ catch (e) {
293
+ this.said(e);
294
+ return;
295
+ }
296
+ if (this.unavailable)
297
+ this.hooks.log("call: LiveKit answers again");
298
+ this.unavailable = null;
299
+ const now = at ?? Date.now();
300
+ for (const [id, t] of this.removed)
301
+ if (now - t > REMOVED_MS)
302
+ this.removed.delete(id);
303
+ const out = [];
304
+ const ours = [];
305
+ for (const p of list) {
306
+ // an egress, an agent and the like are no page's: left alone
307
+ if (p.kind && p.kind !== "STANDARD")
308
+ continue;
309
+ if (p.state === "DISCONNECTED")
310
+ continue;
311
+ const seat = this.seats.get(p.identity);
312
+ const page = seat && seat.gone === null ? this.hooks.page(seat.token) : null;
313
+ if (seat && seat.gone === null && !page)
314
+ seat.gone = now;
315
+ const keep = IDENTITY.test(p.identity) &&
316
+ !this.removed.has(p.identity) &&
317
+ // a page the server does not know (it restarted) has a while to ask for a token again
318
+ (seat ? seat.gone === null || now - seat.gone < PAGE_GONE_MS : now - this.started < PAGE_GONE_MS) &&
319
+ // a page that went private leaves: in a call one is seen
320
+ !page?.private;
321
+ if (keep)
322
+ ours.push(p);
323
+ else
324
+ out.push(p.identity);
325
+ }
326
+ for (const id of out)
327
+ this.seats.delete(id);
328
+ await Promise.all(out.map((id) => this.service.remove(this.room, id).catch((e) => this.said(e))));
329
+ // the seats of pages gone that LiveKit no longer lists are forgotten
330
+ for (const [id, s] of [...this.seats])
331
+ if (s.gone !== null && now - s.gone >= PAGE_GONE_MS && !ours.some((p) => p.identity === id))
332
+ this.seats.delete(id);
333
+ this.present = ours;
334
+ if (ours.length) {
335
+ this.emptySince = null;
336
+ this.session ??= { id: randomBytes(6).toString("hex"), started: new Date(now).toISOString() };
337
+ }
338
+ else if (this.session) {
339
+ this.emptySince ??= now;
340
+ if (now - this.emptySince >= SESSION_GRACE_MS) {
341
+ this.session = null;
342
+ this.emptySince = null;
343
+ }
344
+ }
345
+ this.publish();
346
+ }
347
+ /** LiveKit could not be asked: said once, until it answers again. */
348
+ said(e) {
349
+ const why = e instanceof Error ? e.message : String(e);
350
+ if (this.unavailable === null)
351
+ this.hooks.log(`call: ${why}`);
352
+ this.unavailable = why;
353
+ }
354
+ }
355
+ function readKept(file) {
356
+ if (!existsSync(file))
357
+ return null;
358
+ try {
359
+ const k = JSON.parse(readFileSync(file, "utf8"));
360
+ if (typeof k.room === "string" && /^[0-9a-f]{12}$/.test(k.room) && typeof k.secret === "string" && /^[A-Za-z0-9_-]{43}$/.test(k.secret))
361
+ return { room: k.room, secret: k.secret };
362
+ }
363
+ catch {
364
+ // made anew below
365
+ }
366
+ renameSync(file, `${file}.broken-${Date.now()}`);
367
+ return null;
368
+ }
369
+ function writeKept(file, k) {
370
+ const tmp = `${file}.tmp`;
371
+ writeFileSync(tmp, JSON.stringify(k, null, 1) + "\n", { mode: 0o600 });
372
+ renameSync(tmp, file);
373
+ }
@@ -47,7 +47,7 @@ export function tracked(child) {
47
47
  }
48
48
  /** The environment a program the server runs is given: the server's own, without what is the
49
49
  * server's alone (`VISUALPROOF_*`: the supervisor's word to it, its test hooks; UpdateSpec decision
50
- * 9) and without Claude's and Anthropic's credentials (CREDENTIAL), with `extra` over it. */
50
+ * 9) and without Claude's, Anthropic's and LiveKit's credentials (CREDENTIAL), with `extra` over it. */
51
51
  export function childEnv(extra = {}) {
52
52
  const env = {};
53
53
  for (const [k, v] of Object.entries(process.env))
@@ -55,10 +55,11 @@ export function childEnv(extra = {}) {
55
55
  env[k] = v;
56
56
  return { ...env, ...extra };
57
57
  }
58
- /** Claude's and Anthropic's credentials, where the server's environment has them: no program the
59
- * server runs is given them (Lake, Lean, git, a branch's build, which runs whatever its code says);
60
- * the server's own agent is given the --claude-oauth token alone (server/hosted.ts). */
61
- const CREDENTIAL = (k) => k === "CLAUDE_CODE_OAUTH_TOKEN" || k.startsWith("ANTHROPIC_");
58
+ /** Claude's, Anthropic's and LiveKit's credentials, where the server's environment has them: no
59
+ * program the server runs is given them (Lake, Lean, git, a branch's build, which runs whatever its
60
+ * code says); the server's own agent is given the --claude-oauth token alone (server/hosted.ts),
61
+ * and the call's keys (--livekit-keys env) stay the server's (CallSpec). */
62
+ const CREDENTIAL = (k) => k === "CLAUDE_CODE_OAUTH_TOKEN" || k.startsWith("ANTHROPIC_") || k.startsWith("LIVEKIT_");
62
63
  /** How many tracked programs run now. */
63
64
  export function childCount() {
64
65
  return running.size;
@@ -160,6 +160,8 @@ export class Live {
160
160
  /** the requests to follow going on (CollabSpec decision 10, server/askfollow.ts): relayed to the
161
161
  * pages asked through their streams, and their answers to the page that asked */
162
162
  asks;
163
+ /** the call (CallSpec), where the server has one (--livekit-url): null without */
164
+ call = null;
163
165
  /** the "Open in editor" template the server was started with (shared/editor.ts) */
164
166
  editor;
165
167
  /** the usage pass, `jobs` workers at a time (0: none) */
@@ -209,15 +211,24 @@ export class Live {
209
211
  // given the new cookie, come back as they were
210
212
  this.invites.onChanged = () => this.send("people", this.invites.people());
211
213
  this.invites.onEnded = (r, keep) => {
214
+ // revoked (not made anew): its participants leave the call at once, wherever their pages are
215
+ if (keep === undefined)
216
+ this.call?.cutPerson(r.id);
212
217
  for (const st of [...this.streams.values()])
213
- if (st.person === r.id && (keep === undefined || st.token !== keep))
218
+ if (st.person === r.id && (keep === undefined || st.token !== keep)) {
219
+ // a revoked link's page leaves the call at once, kept out (CallSpec, "As built")
220
+ this.call?.cutPage(st.token);
214
221
  this.close(st);
222
+ }
215
223
  };
216
224
  this.readOnly = new ReadOnlyLinks(dirs.site);
217
225
  this.readOnly.onEnded = (l) => {
226
+ this.call?.cutLink(l.id);
218
227
  for (const st of [...this.streams.values()])
219
- if (st.readOnly === l.id)
228
+ if (st.readOnly === l.id) {
229
+ this.call?.cutPage(st.token);
220
230
  this.close(st);
231
+ }
221
232
  };
222
233
  this.talk = new Talk(dirs.site);
223
234
  // the server's own agent hears what is written to it as it is written, and says its state itself
@@ -319,6 +330,28 @@ export class Live {
319
330
  const st = typeof token === "string" ? this.byToken.get(token) : undefined;
320
331
  return st ? { id: st.id, private: st.private } : null;
321
332
  }
333
+ /** The open page whose stream holds secret `token`, as the call needs it (server/call.ts). */
334
+ callPage(token) {
335
+ const st = this.byToken.get(token);
336
+ return st ? callPageOf(st) : null;
337
+ }
338
+ /** The open page presence lists as `id`, as the call needs it. */
339
+ callPageById(id) {
340
+ for (const st of this.streams.values())
341
+ if (st.id === id)
342
+ return callPageOf(st);
343
+ return null;
344
+ }
345
+ /** Every open page is told (the call's news). */
346
+ broadcast(event, data) {
347
+ this.send(event, data);
348
+ }
349
+ /** The page whose stream holds secret `token` is told, and no other. */
350
+ sendTo(token, event, data) {
351
+ const st = this.byToken.get(token);
352
+ if (st)
353
+ this.write(st.res, event, data);
354
+ }
322
355
  /** The list of who is here goes out now, or with the next one if one went out just now: at most
323
356
  * one every PRESENCE_EVERY ms, and always the latest. */
324
357
  presenceChanged() {
@@ -1382,6 +1415,8 @@ export class Live {
1382
1415
  end(why) {
1383
1416
  // the server's own agent stops with it; a turn cut short is answered at the next start
1384
1417
  this.hosted?.close();
1418
+ // the call goes on on LiveKit: the pages come back to it with the server
1419
+ this.call?.stop();
1385
1420
  const text = "update" in why ? `event: update\ndata: ${JSON.stringify(why.update)}\n\n` : `event: bye\ndata: ${JSON.stringify({ why: "stopped" })}\n\n`;
1386
1421
  for (const st of [...this.streams.values()]) {
1387
1422
  this.streams.delete(st.res);
@@ -1448,6 +1483,9 @@ export class Live {
1448
1483
  this.write(res, "presence", this.presence.list());
1449
1484
  this.write(res, "private", this.privateNow(st));
1450
1485
  this.write(res, "people", this.invites.people());
1486
+ // who is in the call, where the server has one (CallSpec)
1487
+ if (this.call)
1488
+ this.write(res, "call", this.call.state());
1451
1489
  // the views as they are: a page that was away (a restart, a lost connection) catches up, and
1452
1490
  // reads again the boards it has open
1453
1491
  this.write(res, "views", { views: this.views.list(), changes: [], all: true });
@@ -1592,6 +1630,8 @@ export class Live {
1592
1630
  this.streams.delete(st.res);
1593
1631
  this.byToken.delete(st.token);
1594
1632
  this.presence.drop(st.id);
1633
+ // its participant in the call has a while to come back (a reload) before it goes
1634
+ this.call?.streamClosed(st.token);
1595
1635
  // what its page was asked goes unanswered, and what it asked is withdrawn
1596
1636
  this.asks.closed(st.token);
1597
1637
  st.res.destroy();
@@ -1644,3 +1684,7 @@ function mayRead(st, t, channel) {
1644
1684
  return personalChannel(t.id, { name: st.name, person: st.person }) === channel;
1645
1685
  return madeBy(t, { name: st.name, person: st.person });
1646
1686
  }
1687
+ /** An open stream as the call needs it (server/call.ts). */
1688
+ function callPageOf(st) {
1689
+ return { token: st.token, id: st.id, private: st.private, readOnly: st.readOnly, name: st.name, person: st.person };
1690
+ }