@mostra/runtime 0.6.2 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mostra/runtime",
3
- "version": "0.6.2",
3
+ "version": "0.7.0",
4
4
  "description": "The Mostra runtime: the supervisor that owns a home, its ledger, its child processes and the host protocol server (mostra-runtime host|daemon).",
5
5
  "license": "Apache-2.0",
6
6
  "author": "The Mostra Authors",
@@ -36,7 +36,7 @@
36
36
  "dependencies": {
37
37
  "@hono/node-server": "2.1.5",
38
38
  "@mdx-js/mdx": "3.1.1",
39
- "@mostra/protocol": "0.6.2",
39
+ "@mostra/protocol": "0.7.0",
40
40
  "@tailwindcss/vite": "4.3.3",
41
41
  "@vitejs/plugin-react": "6.1.2",
42
42
  "better-sqlite3": "13.0.3",
@@ -54,11 +54,11 @@
54
54
  "zod": "4.6.7"
55
55
  },
56
56
  "devDependencies": {
57
- "@mostra/shell": "0.6.2",
57
+ "@mostra/shell": "0.7.0",
58
58
  "@mostra/tools": "0.0.0",
59
- "@mostra/verify": "0.6.2",
59
+ "@mostra/verify": "0.7.0",
60
60
  "@mostra/warm": "0.0.0",
61
- "@mostra/worker": "0.6.2",
61
+ "@mostra/worker": "0.7.0",
62
62
  "@types/better-sqlite3": "9.6.0",
63
63
  "@types/node": "24.19.2",
64
64
  "@types/semver": "7.8.0",
@@ -25,8 +25,11 @@ export const LEASE_LAST_PORT = 32767;
25
25
  /** How many free ports to try before giving up on a lease. */
26
26
  const LEASE_ATTEMPTS = 64;
27
27
 
28
- /** What a lease is for (DATA_MODEL §3 `port_lease.purpose`). */
29
- export type LeasePurpose = "shell" | "artifact" | "demo";
28
+ /** What a lease is for (DATA_MODEL §3 `port_lease.purpose`); `face` from WP-13 (D158). */
29
+ export type LeasePurpose = "shell" | "artifact" | "demo" | "face";
30
+
31
+ /** The address every face listens on: loopback, whatever `--bind` says (D158 item 1). */
32
+ export const FACE_BIND_ADDRESS = "127.0.0.1";
30
33
 
31
34
  /** Who holds a lease: the shell, an artifact ID, or a demo. */
32
35
  export interface LeaseOwner {
@@ -70,6 +73,28 @@ export interface Addressing {
70
73
  * host (same site, D38), worker mode otherwise (cross-site, D70).
71
74
  */
72
75
  frameMode(shellOrigin: string, artifactOrigin: string): FrameMode;
76
+ /**
77
+ * Binds a face's listener on loopback (D158 item 1): on the port leased to `key` when `lease`
78
+ * is set, so the face keeps its address across restarts, else on a port the operating system
79
+ * picks. Resolves with the port.
80
+ */
81
+ listenFace(
82
+ server: Server,
83
+ face: { readonly key: string; readonly lease: boolean },
84
+ ): Promise<number>;
85
+ /** Releases a face's leased port, once the face is gone for good. */
86
+ releaseFace(key: string): void;
87
+ /** The loopback origin of a face listener on `port`: `http://127.0.0.1:<port>`. */
88
+ faceLocal(port: number): string;
89
+ }
90
+
91
+ /**
92
+ * The exact `Host` a browser sends for an origin: its host, with the port only when it isn't the
93
+ * scheme's default (`https://a.ts.net` is `a.ts.net`, `https://a.ts.net:8443` is
94
+ * `a.ts.net:8443`), lowercase. Registered tunnel addresses join the allowlist this way.
95
+ */
96
+ export function hostOf(origin: string): string {
97
+ return new URL(origin).host.toLowerCase();
73
98
  }
74
99
 
75
100
  /** The unspecified addresses, as {@link authorityHost} writes them: each listens everywhere. */
@@ -214,6 +239,46 @@ export function createAddressing(options: {
214
239
  .map((row) => row.port),
215
240
  );
216
241
 
242
+ /**
243
+ * Binds `server` to the owner's leased port on `address`, or to a newly leased one when it has
244
+ * none or another program holds it (`MOSTRA_ENV_PORT_TAKEN`).
245
+ */
246
+ const leaseAndListen = async (
247
+ server: Server,
248
+ owner: LeaseOwner,
249
+ address: string,
250
+ ): Promise<number> => {
251
+ const previous = leased(owner);
252
+ if (previous !== undefined) {
253
+ if (await tryListen(server, previous, address)) return previous;
254
+ log.warn("addressing.port_taken", {
255
+ code: "MOSTRA_ENV_PORT_TAKEN",
256
+ purpose: owner.purpose,
257
+ owner: owner.owner,
258
+ port: previous,
259
+ });
260
+ }
261
+ const others = taken();
262
+ for (let attempt = 0; attempt < LEASE_ATTEMPTS; attempt++) {
263
+ const port = randomInt(LEASE_FIRST_PORT, LEASE_LAST_PORT + 1);
264
+ if (others.has(port)) continue;
265
+ if (!(await tryListen(server, port, address))) continue;
266
+ record(owner, port);
267
+ if (previous !== undefined) {
268
+ log.warn("addressing.port_released", {
269
+ purpose: owner.purpose,
270
+ owner: owner.owner,
271
+ from: previous,
272
+ to: port,
273
+ });
274
+ }
275
+ return port;
276
+ }
277
+ throw bindFailed(
278
+ `No free port between ${LEASE_FIRST_PORT} and ${LEASE_LAST_PORT} on ${address} after ${LEASE_ATTEMPTS} attempts.`,
279
+ );
280
+ };
281
+
217
282
  return {
218
283
  bindAddress,
219
284
  urlHost,
@@ -242,40 +307,29 @@ export function createAddressing(options: {
242
307
  if (address === null || typeof address === "string") throw new Error("not a TCP listener");
243
308
  return address.port;
244
309
  }
245
- const previous = leased(owner);
246
- if (previous !== undefined) {
247
- if (await tryListen(server, previous, bindAddress)) return previous;
248
- log.warn("addressing.port_taken", {
249
- code: "MOSTRA_ENV_PORT_TAKEN",
250
- purpose: owner.purpose,
251
- owner: owner.owner,
252
- port: previous,
253
- });
254
- }
255
- const others = taken();
256
- for (let attempt = 0; attempt < LEASE_ATTEMPTS; attempt++) {
257
- const port = randomInt(LEASE_FIRST_PORT, LEASE_LAST_PORT + 1);
258
- if (others.has(port)) continue;
259
- if (!(await tryListen(server, port, bindAddress))) continue;
260
- record(owner, port);
261
- if (previous !== undefined) {
262
- log.warn("addressing.port_released", {
263
- purpose: owner.purpose,
264
- owner: owner.owner,
265
- from: previous,
266
- to: port,
267
- });
268
- }
269
- return port;
270
- }
271
- throw bindFailed(
272
- `No free port between ${LEASE_FIRST_PORT} and ${LEASE_LAST_PORT} on ${bindAddress} after ${LEASE_ATTEMPTS} attempts.`,
273
- );
310
+ return leaseAndListen(server, owner, bindAddress);
274
311
  },
275
312
  frameMode(shellOrigin, artifactOrigin) {
276
313
  return new URL(shellOrigin).hostname === new URL(artifactOrigin).hostname
277
314
  ? "cookie"
278
315
  : "worker";
279
316
  },
317
+ async listenFace(server, face) {
318
+ if (!face.lease) {
319
+ if (!(await tryListen(server, 0, FACE_BIND_ADDRESS))) {
320
+ throw bindFailed(`No port is free on ${FACE_BIND_ADDRESS}.`);
321
+ }
322
+ const address = server.address();
323
+ if (address === null || typeof address === "string") throw new Error("not a TCP listener");
324
+ return address.port;
325
+ }
326
+ return leaseAndListen(server, { purpose: "face", owner: face.key }, FACE_BIND_ADDRESS);
327
+ },
328
+ releaseFace(key) {
329
+ ledger.write((db) =>
330
+ db.run("DELETE FROM port_lease WHERE purpose = 'face' AND owner_ref = ?", key),
331
+ );
332
+ },
333
+ faceLocal: (port) => `http://${FACE_BIND_ADDRESS}:${port}`,
280
334
  };
281
335
  }
@@ -363,7 +363,9 @@ export function browserRoutes(options: BrowserRoutesOptions): BrowserRoutes {
363
363
  const body = new ReadableStream<Uint8Array>(
364
364
  {
365
365
  start(controller) {
366
- let text = "retry: 2000\n\n";
366
+ // `ready` first, whatever follows: a page that hears nothing has a stream something holds
367
+ // back (a buffering proxy or tunnel, a stalled browser) and long-polls instead (WP-13).
368
+ let text = "retry: 2000\n\nevent: ready\ndata: {}\n\n";
367
369
  if (resume === undefined) text += snapshotText(interaction.pageSnapshot(page));
368
370
  controller.enqueue(encoder.encode(text));
369
371
  },
@@ -40,6 +40,12 @@ export const SECRET_LENGTH = 26;
40
40
  /** How long a frame ticket works (D98). */
41
41
  export const TICKET_TTL_MS = 60_000;
42
42
 
43
+ /** How many frame tickets, and how many stream tickets, a session holds at once (D158 item 5). */
44
+ export const TICKETS_PER_SESSION = 8;
45
+
46
+ /** How often expired tickets are swept at most. */
47
+ const SWEEP_INTERVAL_MS = 1_000;
48
+
43
49
  /**
44
50
  * Failed capability tokens tolerated per artifact and minute (D97 item 8). Tickets don't count:
45
51
  * they are single-use 130-bit secrets that live for a minute, and any page on the host could spend
@@ -54,6 +60,17 @@ export const SESSION_MAX_AGE_S: number = 400 * 24 * 60 * 60;
54
60
  /** How often a session's `last_seen_at` is written at most. */
55
61
  const TOUCH_INTERVAL_MS = 60 * 60 * 1000;
56
62
 
63
+ /** Whether two origins are on the same scheme and host, whatever their ports. */
64
+ function sameHost(a: string, b: string): boolean {
65
+ try {
66
+ const one = new URL(a);
67
+ const two = new URL(b);
68
+ return one.protocol === two.protocol && one.hostname === two.hostname;
69
+ } catch {
70
+ return false;
71
+ }
72
+ }
73
+
57
74
  /** Encodes the first 130 bits of `bytes` as 26 Crockford base32 characters. */
58
75
  function crockford(bytes: Uint8Array): string {
59
76
  let bits = 0;
@@ -161,6 +178,8 @@ export interface ResolvedSession {
161
178
  readonly csrf: string;
162
179
  /** The version a frame session entered (D98 item 5). */
163
180
  readonly versionId?: string;
181
+ /** How the session authenticates: a cookie, or the frame header of worker mode (D70). */
182
+ readonly mode: "cookie" | "worker";
164
183
  readonly grant: Grant;
165
184
  /**
166
185
  * The viewer the session acts as: its link's viewer (D104), else the one the host's identity
@@ -201,6 +220,7 @@ interface SessionRow {
201
220
  id: string;
202
221
  token_id: string;
203
222
  origin: string;
223
+ mode: "cookie" | "worker";
204
224
  csrf: string;
205
225
  version_id: string | null;
206
226
  viewer_id: string | null;
@@ -225,10 +245,21 @@ export interface CapabilitiesOptions {
225
245
  readonly key: Buffer;
226
246
  /** The clock, in milliseconds since the epoch. */
227
247
  readonly now: () => number;
228
- /** The shell's origin, once the gateway listens: links are minted for it and work only there. */
248
+ /**
249
+ * The loopback shell's origin, once the gateway listens: links are minted for it unless the
250
+ * caller names another shell address (a share's, a host's, D158), and work only there.
251
+ */
229
252
  readonly shellOrigin: () => string;
253
+ /**
254
+ * Whether the gateway serves a shell at this origin now (the loopback shell, a share's shell
255
+ * face, a host's): a launch ticket is only minted for a link whose address is served.
256
+ */
257
+ readonly servesShell?: (origin: string) => boolean;
230
258
  }
231
259
 
260
+ /** What a stream ticket opens (D158 item 5). */
261
+ export type StreamTicketPurpose = "stream" | "socket";
262
+
232
263
  /** The capability authority of one instance. */
233
264
  export class Capabilities {
234
265
  readonly #ledger: Ledger;
@@ -236,9 +267,26 @@ export class Capabilities {
236
267
  readonly #key: Buffer;
237
268
  readonly #now: () => number;
238
269
  readonly #shellOrigin: () => string;
270
+ readonly #servesShell: (origin: string) => boolean;
271
+ /** Single-use stream and socket tickets (D158 item 5), by the SHA-256 of their secret. */
272
+ readonly #streamTickets = new Map<
273
+ string,
274
+ {
275
+ readonly sessionId: string;
276
+ readonly origin: string;
277
+ readonly artifactId: string;
278
+ readonly purpose: StreamTicketPurpose;
279
+ readonly expires: number;
280
+ }
281
+ >();
239
282
  readonly #tickets = new Map<string, TicketGrant & { readonly expires: number }>();
240
283
  /** One-time launch tickets (D140 item 15), by the SHA-256 of their secret. */
241
284
  readonly #launches = new Map<string, { readonly tokenId: string; readonly expires: number }>();
285
+ /** The frame tickets and the stream tickets each session holds, oldest first. */
286
+ readonly #ticketsBySession = new Map<string, string[]>();
287
+ readonly #streamTicketsBySession = new Map<string, string[]>();
288
+ /** When the tickets were last swept. */
289
+ #swept = Number.NEGATIVE_INFINITY;
242
290
  /** Failure times per artifact (`""` for tokens of no artifact in this home). */
243
291
  readonly #failures = new Map<string, number[]>();
244
292
  readonly #touched = new Map<string, number>();
@@ -249,6 +297,7 @@ export class Capabilities {
249
297
  this.#key = options.key;
250
298
  this.#now = options.now;
251
299
  this.#shellOrigin = options.shellOrigin;
300
+ this.#servesShell = options.servesShell ?? ((origin) => origin === this.#shellOrigin());
252
301
  }
253
302
 
254
303
  /** Runs `fn` in the caller's transaction, or in a new one. */
@@ -284,12 +333,13 @@ export class Capabilities {
284
333
  readonly isDefault: boolean;
285
334
  readonly tokenId?: string;
286
335
  readonly viewerId?: string | undefined;
336
+ readonly shellOrigin?: string | undefined;
287
337
  },
288
338
  ): MintedToken {
289
339
  const tokenId = input.tokenId ?? TokenId.create();
290
340
  const secret = this.secretOf(tokenId);
291
341
  const scopes = normalizeScopes(input.scopes);
292
- const shellOrigin = this.#shellOrigin();
342
+ const shellOrigin = input.shellOrigin ?? this.#shellOrigin();
293
343
  db.run(
294
344
  "INSERT INTO token (id, secret_hash, artifact_id, scopes_json, viewer_id, expires_at, revoked_at, created_at, is_default, pinned_version, shell_origin) VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?)",
295
345
  tokenId,
@@ -325,6 +375,8 @@ export class Capabilities {
325
375
  readonly pinnedVersion?: number | undefined;
326
376
  /** The viewer the link acts for (D104). */
327
377
  readonly viewerId?: string | undefined;
378
+ /** The shell address the link works at (D97 item 10); default: the loopback shell. */
379
+ readonly shellOrigin?: string | undefined;
328
380
  },
329
381
  within?: LedgerDb,
330
382
  ): MintedToken {
@@ -336,6 +388,7 @@ export class Capabilities {
336
388
  pinnedVersion: input.pinnedVersion,
337
389
  isDefault: false,
338
390
  viewerId: input.viewerId,
391
+ shellOrigin: input.shellOrigin,
339
392
  }),
340
393
  );
341
394
  }
@@ -346,7 +399,8 @@ export class Capabilities {
346
399
  * key was replaced) stays valid for whoever holds it, and a new default takes its place; so does
347
400
  * one minted for another shell address, which works again if the gateway returns there.
348
401
  */
349
- defaultLink(artifactId: string): MintedToken {
402
+ defaultLink(artifactId: string, shellOrigin?: string): MintedToken {
403
+ const origin = shellOrigin ?? this.#shellOrigin();
350
404
  return this.#ledger.write((db) => {
351
405
  const row = db.get<TokenRow>(
352
406
  "SELECT * FROM token WHERE artifact_id = ? AND is_default = 1",
@@ -354,7 +408,7 @@ export class Capabilities {
354
408
  );
355
409
  if (row) {
356
410
  const secret = this.secretOf(row.id);
357
- const here = row.shell_origin === this.#shellOrigin();
411
+ const here = row.shell_origin === origin;
358
412
  if (here && safeEqual(hashSecret(secret), row.secret_hash)) {
359
413
  return { ...grantOf(row), secret };
360
414
  }
@@ -365,7 +419,12 @@ export class Capabilities {
365
419
  reason: here ? "the capability key changed" : "the shell's address changed",
366
420
  });
367
421
  }
368
- return this.#insert(db, { artifactId, scopes: ALL_SCOPES, isDefault: true });
422
+ return this.#insert(db, {
423
+ artifactId,
424
+ scopes: ALL_SCOPES,
425
+ isDefault: true,
426
+ shellOrigin: origin,
427
+ });
369
428
  });
370
429
  }
371
430
 
@@ -377,6 +436,24 @@ export class Capabilities {
377
436
  return row ? { ...grantOf(row), live: this.#live(row) } : undefined;
378
437
  }
379
438
 
439
+ /**
440
+ * The token that stands for `tokenId` now: itself, or the token its rotations led to (D97 item
441
+ * 6), so what holds a token ID (a share) follows its link through `view/rotate`.
442
+ */
443
+ current(tokenId: string): string {
444
+ let id = tokenId;
445
+ for (let hop = 0; hop < 1000; hop++) {
446
+ const next = this.#ledger.read(
447
+ (db) =>
448
+ db.get<{ replaced_by: string | null }>("SELECT replaced_by FROM token WHERE id = ?", id)
449
+ ?.replaced_by ?? null,
450
+ );
451
+ if (next === null) return id;
452
+ id = next;
453
+ }
454
+ return id;
455
+ }
456
+
380
457
  /** The token's link again, from its derived secret, when the current key still derives it. */
381
458
  reveal(tokenId: string): MintedToken | undefined {
382
459
  const row = this.#ledger.read((db) =>
@@ -436,6 +513,14 @@ export class Capabilities {
436
513
  pinnedVersion: grant.pinnedVersion,
437
514
  isDefault: grant.isDefault,
438
515
  viewerId: grant.viewerId,
516
+ // A link stays at the address its holder uses: a share's, a host's external base, served
517
+ // now or not (a share's faces are down while it is set up again after a restart, Opus
518
+ // review of WP-13). Only a loopback link whose shell moved to another port moves to the
519
+ // shell's address now (D97 item 10, GPT review of WP-13).
520
+ shellOrigin:
521
+ sameHost(grant.shellOrigin, this.#shellOrigin()) && !this.#servesShell(grant.shellOrigin)
522
+ ? undefined
523
+ : grant.shellOrigin,
439
524
  });
440
525
  appendEvent(db, {
441
526
  artifactId: grant.artifactId,
@@ -490,6 +575,7 @@ export class Capabilities {
490
575
  presentToken(
491
576
  secret: unknown,
492
577
  artifactId: string,
578
+ shellOrigin?: string,
493
579
  ): Grant | (Refusal & { readonly retryAfter?: number }) {
494
580
  const limited = this.limited(artifactId);
495
581
  if (limited) return limited;
@@ -516,10 +602,10 @@ export class Capabilities {
516
602
  row.revoked_at !== null ? "This link was revoked." : "This link has expired.",
517
603
  );
518
604
  }
519
- if (row.shell_origin !== this.#shellOrigin()) {
605
+ if (row.shell_origin !== (shellOrigin ?? this.#shellOrigin())) {
520
606
  return refusal(
521
607
  "MOSTRA_HYGIENE_TOKEN_REVOKED",
522
- `This link was made for ${row.shell_origin}, an address this Mostra no longer serves.`,
608
+ `This link was made for ${row.shell_origin}, not this address.`,
523
609
  );
524
610
  }
525
611
  return grantOf(row);
@@ -532,6 +618,8 @@ export class Capabilities {
532
618
  readonly versionId?: string;
533
619
  /** The person the host's identity port named, for a link without a viewer (D143 item 2). */
534
620
  readonly viewerId?: string | undefined;
621
+ /** `worker` for a worker-mode frame (D70), whose secret travels in a header; default `cookie`. */
622
+ readonly mode?: "cookie" | "worker";
535
623
  }): {
536
624
  readonly cookie: string;
537
625
  readonly csrf: string;
@@ -543,10 +631,11 @@ export class Capabilities {
543
631
  const now = this.#iso(this.#now());
544
632
  this.#ledger.write((db) =>
545
633
  db.run(
546
- "INSERT INTO session (id, token_id, origin, mode, csrf, version_id, created_at, last_seen_at, viewer_id) VALUES (?, ?, ?, 'cookie', ?, ?, ?, ?, ?)",
634
+ "INSERT INTO session (id, token_id, origin, mode, csrf, version_id, created_at, last_seen_at, viewer_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
547
635
  id,
548
636
  input.tokenId,
549
637
  input.origin,
638
+ input.mode ?? "cookie",
550
639
  hashSecret(csrf),
551
640
  input.versionId ?? null,
552
641
  now,
@@ -566,13 +655,15 @@ export class Capabilities {
566
655
  cookies: readonly string[],
567
656
  origin: string,
568
657
  artifactId: string,
658
+ mode: "cookie" | "worker" = "cookie",
569
659
  ): ResolvedSession | Refusal {
570
660
  let revoked = false;
571
661
  for (const value of cookies) {
572
662
  if (!looksLikeSecret(value)) continue;
573
663
  const found = this.#ledger.read((db) => {
574
664
  const session = db.get<SessionRow>("SELECT * FROM session WHERE id = ?", hashSecret(value));
575
- if (!session || session.origin !== origin) return undefined;
665
+ // A session works only the way it was made: a cookie never stands for a frame header.
666
+ if (!session || session.origin !== origin || session.mode !== mode) return undefined;
576
667
  const token = db.get<TokenRow>("SELECT * FROM token WHERE id = ?", session.token_id);
577
668
  return token && token.artifact_id === artifactId ? { session, token } : undefined;
578
669
  });
@@ -591,6 +682,7 @@ export class Capabilities {
591
682
  return {
592
683
  id: found.session.id,
593
684
  csrf,
685
+ mode,
594
686
  ...(found.session.version_id !== null ? { versionId: found.session.version_id } : {}),
595
687
  grant,
596
688
  ...(viewerId !== undefined ? { viewerId } : {}),
@@ -629,14 +721,33 @@ export class Capabilities {
629
721
  );
630
722
  }
631
723
 
632
- /** Mints a single-use frame ticket (D98 item 3). */
724
+ /** Mints a single-use frame ticket (D98 item 3); a shell session holds at most a few at once. */
633
725
  mintTicket(grant: Omit<TicketGrant, never>): string {
634
726
  const ticket = randomSecret();
635
727
  this.#sweepTickets();
636
- this.#tickets.set(hashSecret(ticket), { ...grant, expires: this.#now() + TICKET_TTL_MS });
728
+ const key = hashSecret(ticket);
729
+ this.#tickets.set(key, { ...grant, expires: this.#now() + TICKET_TTL_MS });
730
+ this.#hold(this.#ticketsBySession, this.#tickets, grant.shellSessionId, key);
637
731
  return ticket;
638
732
  }
639
733
 
734
+ /**
735
+ * Records a session's new ticket and drops its oldest beyond {@link TICKETS_PER_SESSION}, so no
736
+ * link holder can make the maps grow without bound by asking for tickets in a loop (Opus review
737
+ * of WP-13). A page uses one or two at a time.
738
+ */
739
+ #hold(
740
+ bySession: Map<string, string[]>,
741
+ tickets: Map<string, unknown>,
742
+ sessionId: string,
743
+ key: string,
744
+ ): void {
745
+ const held = (bySession.get(sessionId) ?? []).filter((one) => tickets.has(one));
746
+ held.push(key);
747
+ while (held.length > TICKETS_PER_SESSION) tickets.delete(held.shift() as string);
748
+ bySession.set(sessionId, held);
749
+ }
750
+
640
751
  /**
641
752
  * Redeems a ticket on `origin`, once, while the shell session that asked for it lives and its
642
753
  * link is live (D98 item 3).
@@ -646,7 +757,7 @@ export class Capabilities {
646
757
  const key = looksLikeSecret(ticket) ? hashSecret(ticket) : undefined;
647
758
  const entry = key === undefined ? undefined : this.#tickets.get(key);
648
759
  if (key !== undefined) this.#tickets.delete(key);
649
- if (!entry || entry.origin !== origin) {
760
+ if (!entry || entry.expires <= this.#now() || entry.origin !== origin) {
650
761
  return refusal(
651
762
  "MOSTRA_HYGIENE_TOKEN_INVALID",
652
763
  "The frame ticket is unknown, used or expired.",
@@ -675,9 +786,101 @@ export class Capabilities {
675
786
  return rest;
676
787
  }
677
788
 
789
+ /**
790
+ * Mints a single-use ticket that opens one event stream, long poll or WebSocket of a session
791
+ * without the session's credential (D158 item 5): a worker-mode page's streams bypass its
792
+ * service worker, which can't carry them. It lives 60 s in memory and is never recorded.
793
+ */
794
+ mintStreamTicket(input: {
795
+ readonly sessionId: string;
796
+ readonly origin: string;
797
+ readonly artifactId: string;
798
+ readonly purpose: StreamTicketPurpose;
799
+ }): { readonly ticket: string; readonly expiresAt: string } {
800
+ this.#sweepTickets();
801
+ const ticket = randomSecret();
802
+ const expires = this.#now() + TICKET_TTL_MS;
803
+ const key = hashSecret(ticket);
804
+ this.#streamTickets.set(key, { ...input, expires });
805
+ this.#hold(this.#streamTicketsBySession, this.#streamTickets, input.sessionId, key);
806
+ return { ticket, expiresAt: this.#iso(expires) };
807
+ }
808
+
809
+ /**
810
+ * Spends a stream ticket on `origin` for `artifactId` and `purpose`, and resolves its session
811
+ * as a request carrying the session's credential would, its link's liveness included. The
812
+ * session's CSRF token isn't known here: a ticket opens reads only (streams, polls, sockets).
813
+ */
814
+ redeemStreamTicket(
815
+ ticket: unknown,
816
+ origin: string,
817
+ artifactId: string,
818
+ purpose: StreamTicketPurpose,
819
+ ): ResolvedSession | Refusal {
820
+ this.#sweepTickets();
821
+ const key = looksLikeSecret(ticket) ? hashSecret(ticket) : undefined;
822
+ const entry = key === undefined ? undefined : this.#streamTickets.get(key);
823
+ if (key !== undefined) this.#streamTickets.delete(key);
824
+ if (
825
+ !entry ||
826
+ entry.expires <= this.#now() ||
827
+ entry.origin !== origin ||
828
+ entry.artifactId !== artifactId ||
829
+ entry.purpose !== purpose
830
+ ) {
831
+ return refusal(
832
+ "MOSTRA_HYGIENE_TOKEN_INVALID",
833
+ "The stream ticket is unknown, used or expired.",
834
+ );
835
+ }
836
+ const found = this.#ledger.read((db) => {
837
+ const session = db.get<SessionRow>("SELECT * FROM session WHERE id = ?", entry.sessionId);
838
+ if (!session || session.origin !== origin) return undefined;
839
+ const token = db.get<TokenRow>("SELECT * FROM token WHERE id = ?", session.token_id);
840
+ return token && token.artifact_id === artifactId ? { session, token } : undefined;
841
+ });
842
+ if (!found) {
843
+ return refusal("MOSTRA_HYGIENE_SESSION_MISSING", "The session behind this ticket has ended.");
844
+ }
845
+ if (!this.#live(found.token)) {
846
+ return refusal(
847
+ "MOSTRA_HYGIENE_TOKEN_REVOKED",
848
+ "The link this session came from was revoked or has expired.",
849
+ );
850
+ }
851
+ const grant = grantOf(found.token);
852
+ const viewerId = grant.viewerId ?? found.session.viewer_id ?? undefined;
853
+ return {
854
+ id: found.session.id,
855
+ csrf: "",
856
+ mode: found.session.mode,
857
+ ...(found.session.version_id !== null ? { versionId: found.session.version_id } : {}),
858
+ grant,
859
+ ...(viewerId !== undefined ? { viewerId } : {}),
860
+ };
861
+ }
862
+
863
+ /**
864
+ * Drops expired tickets, at most once a second: every use checks a ticket's expiry itself, so a
865
+ * sweep only frees memory, and a burst of requests never makes each one walk every ticket (Opus
866
+ * review of WP-13).
867
+ */
678
868
  #sweepTickets(): void {
679
869
  const now = this.#now();
870
+ if (now - this.#swept < SWEEP_INTERVAL_MS && now >= this.#swept) return;
871
+ this.#swept = now;
872
+ for (const [sessionId, held] of this.#ticketsBySession) {
873
+ if (!held.some((key) => this.#tickets.has(key))) this.#ticketsBySession.delete(sessionId);
874
+ }
875
+ for (const [sessionId, held] of this.#streamTicketsBySession) {
876
+ if (!held.some((key) => this.#streamTickets.has(key))) {
877
+ this.#streamTicketsBySession.delete(sessionId);
878
+ }
879
+ }
680
880
  for (const [key, entry] of this.#tickets) if (entry.expires <= now) this.#tickets.delete(key);
881
+ for (const [key, entry] of this.#streamTickets) {
882
+ if (entry.expires <= now) this.#streamTickets.delete(key);
883
+ }
681
884
  for (const [key, entry] of this.#launches) if (entry.expires <= now) this.#launches.delete(key);
682
885
  }
683
886
 
@@ -695,7 +898,7 @@ export class Capabilities {
695
898
  | undefined {
696
899
  const grant = this.grant(tokenId);
697
900
  if (!grant) return undefined;
698
- if (!grant.live || grant.shellOrigin !== this.#shellOrigin()) return "dead";
901
+ if (!grant.live || !this.#servesShell(grant.shellOrigin)) return "dead";
699
902
  this.#sweepTickets();
700
903
  const ticket = randomSecret();
701
904
  const expires = this.#now() + TICKET_TTL_MS;
@@ -714,12 +917,14 @@ export class Capabilities {
714
917
  ticket: unknown,
715
918
  artifactId: string,
716
919
  spend: boolean,
920
+ shellOrigin?: string,
717
921
  ): Grant | (Refusal & { readonly retryAfter?: number }) {
718
922
  const limited = this.limited(artifactId);
719
923
  if (limited) return limited;
720
924
  this.#sweepTickets();
721
925
  const key = looksLikeSecret(ticket) ? hashSecret(ticket) : undefined;
722
- const entry = key === undefined ? undefined : this.#launches.get(key);
926
+ const found = key === undefined ? undefined : this.#launches.get(key);
927
+ const entry = found && found.expires > this.#now() ? found : undefined;
723
928
  const grant = entry ? this.grant(entry.tokenId) : undefined;
724
929
  if (!entry || !grant || grant.artifactId !== artifactId) {
725
930
  this.#fail(artifactId);
@@ -728,10 +933,10 @@ export class Capabilities {
728
933
  "The launch ticket is unknown, used or expired.",
729
934
  );
730
935
  }
731
- if (!grant.live || grant.shellOrigin !== this.#shellOrigin()) {
936
+ if (!grant.live || grant.shellOrigin !== (shellOrigin ?? this.#shellOrigin())) {
732
937
  return refusal(
733
938
  "MOSTRA_HYGIENE_TOKEN_REVOKED",
734
- "The link behind this launch ticket was revoked or has expired.",
939
+ "The link behind this launch ticket was revoked, has expired, or is for another address.",
735
940
  );
736
941
  }
737
942
  if (spend && key !== undefined) this.#launches.delete(key);
@@ -745,9 +950,13 @@ export class Capabilities {
745
950
  * session between them (GPT review of WP-12, finding 1).
746
951
  */
747
952
  spendLaunch(ticket: unknown): boolean {
748
- // An expired ticket is swept first, so it can't be spent (Opus review of WP-12, finding 3).
953
+ // An expired ticket can't be spent (Opus review of WP-12, finding 3).
749
954
  this.#sweepTickets();
750
- return looksLikeSecret(ticket) && this.#launches.delete(hashSecret(ticket));
955
+ if (!looksLikeSecret(ticket)) return false;
956
+ const key = hashSecret(ticket);
957
+ const entry = this.#launches.get(key);
958
+ if (!entry || entry.expires <= this.#now()) return false;
959
+ return this.#launches.delete(key);
751
960
  }
752
961
 
753
962
  /** Removes sessions unseen for longer than their cookie lives; no browser holds them any more. */