@botiverse/porthole 0.14.3 → 0.14.5

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 (45) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/conformance/harness-source.js +1 -1
  4. package/dist/host/create-host.js +2 -0
  5. package/dist/host/locate.d.ts +1 -1
  6. package/dist/host/locate.js +2 -2
  7. package/dist/host/outcome.d.ts +4 -0
  8. package/dist/host/outcome.js +43 -0
  9. package/dist/host/types.d.ts +12 -4
  10. package/dist/isolation/served.d.ts +17 -1
  11. package/dist/isolation/served.js +24 -1
  12. package/dist/isolation/types.d.ts +5 -0
  13. package/dist/isolation/types.js +5 -0
  14. package/dist/platform/focus-guard.d.ts +40 -0
  15. package/dist/platform/focus-guard.js +176 -32
  16. package/dist/platform/web.js +24 -9
  17. package/dist/react/frame.d.ts +2 -1
  18. package/dist/server/files.js +7 -7
  19. package/dist/server/index.d.ts +1 -1
  20. package/dist/server/index.js +1 -1
  21. package/dist/server/nested.d.ts +13 -7
  22. package/dist/server/nested.js +31 -9
  23. package/dist/server/server.js +5 -2
  24. package/dist/shell/frame.d.ts +5 -2
  25. package/dist/shell/frame.js +41 -18
  26. package/docs/ADOPTING.md +37 -14
  27. package/docs/ARCHITECTURE.md +5 -1
  28. package/docs/DECISIONS.md +404 -2
  29. package/docs/DESIGN.md +11 -4
  30. package/docs/THREAT_MODEL.md +116 -32
  31. package/package.json +1 -1
  32. package/src/host/create-host.ts +2 -0
  33. package/src/host/locate.ts +2 -2
  34. package/src/host/outcome.ts +49 -0
  35. package/src/host/types.ts +12 -4
  36. package/src/isolation/served.ts +29 -0
  37. package/src/isolation/types.ts +6 -0
  38. package/src/platform/focus-guard.ts +218 -34
  39. package/src/platform/web.ts +29 -12
  40. package/src/react/frame.tsx +2 -1
  41. package/src/server/files.ts +5 -6
  42. package/src/server/index.ts +1 -0
  43. package/src/server/nested.ts +44 -12
  44. package/src/server/server.ts +5 -4
  45. package/src/shell/frame.ts +43 -18
@@ -18,6 +18,15 @@
18
18
  * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
19
  * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
20
  * (measured: 5.04 to 5.10 s).
21
+ *
22
+ * A nested page's shell (P111) says when its activation turned on, which a press in the page does,
23
+ * and so does a key the person typed into it: one meant for the host's composer, after the page took
24
+ * the keyboard and before the guard took it back (the audit of P111's guard, NG-1). Neither the
25
+ * shell nor the host's page can tell the two apart from the activation (the shell gets no event as
26
+ * focus comes into its child, measured), so (P120): in a fight over a text field the shell's word
27
+ * isn't asked; a wait on a move from a text field doesn't end with the frame holding focus unjudged;
28
+ * and where the host's page sees the pointer over its frames, an activation while it isn't over the
29
+ * frame and the person was typing is no press.
21
30
  */
22
31
  /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
23
32
  export const TAB_MS = 1_000;
@@ -28,6 +37,16 @@ export const TAB_MS = 1_000;
28
37
  export const ACTIVATION_SPAN_MS = 5_000;
29
38
  /** The person is typing: a key on the host's page within this long. */
30
39
  export const TYPING_MS = 1_000;
40
+ /**
41
+ * No press of the person's lands on a frame this soon after a key they typed on the host's page
42
+ * (P122): a hand on the keys doesn't reach the pointer and press that fast (the Keystroke-Level
43
+ * Model gives 400 ms to the hand's move from the keys to the mouse alone; Card, Moran and Newell,
44
+ * 1980). A move into a nested page's frame, or its shell's activation turning on, within this long
45
+ * is the person's next key landing in the page, which turns its activation on as a press does.
46
+ * Where neither the host's page nor the shell sees the pointer (full Chromium), it holds a page that
47
+ * takes the keyboard while the person types even when their key outruns the shell's answer.
48
+ */
49
+ export const KEY_PRESS_MS = 250;
31
50
  /**
32
51
  * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
33
52
  * text field this long: a page that takes it again at once (on its own blur, which the take-back
@@ -106,10 +125,15 @@ export function personMoved(move) {
106
125
  return true;
107
126
  }
108
127
  // A nested page (P111): its shell's activation turned on within the last second, and the host's
109
- // page had no press or key of its own since (the person went back to it); or, where the engine
110
- // tells it, a press on the frame. Nothing else: no pointer over it, no host-wide activation.
128
+ // page had no press or key of its own since (the person went back to it), where it may have been
129
+ // a press (P120) and not within `KEY_PRESS_MS` of the person's last key (P122); or, where the
130
+ // engine tells it, a press on the frame. Nothing else: no pointer over it, no host-wide
131
+ // activation.
111
132
  if (move.shell !== undefined && move.shell.word.supported) {
112
- return ((move.seen && move.pressed) || shellGesture(move.shell.word, move.shell.hostInputAt, move.now));
133
+ return ((move.seen && move.pressed) ||
134
+ (move.now - move.typedAt >= KEY_PRESS_MS &&
135
+ shellGesture(move.shell.word, move.shell.hostInputAt, move.now) &&
136
+ !(move.shell.pointerShown === true && move.shell.word.keyed === true)));
113
137
  }
114
138
  if (move.seen ? move.pressed : move.over && move.overSince > Math.max(move.typedAt, move.focusedAt)) {
115
139
  return true;
@@ -127,6 +151,17 @@ export function shellGesture(word, hostInputAt, now) {
127
151
  now >= word.activatedAt &&
128
152
  hostInputAt < word.activatedAt);
129
153
  }
154
+ /**
155
+ * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
156
+ * says its activation turned on, which a key typed into the page does as well as a press. Where the
157
+ * host's page sees the pointer over its frames (`shown`: Firefox; Chromium and WebKit where the frame
158
+ * is in their process, not full Chromium), a press needs the pointer over the frame, come over it
159
+ * since the person last typed on the host's page; within `TYPING_MS` of that typing, an activation
160
+ * with the pointer elsewhere is their keys landing in the page. Anywhere else it may be a press.
161
+ */
162
+ export function pressPossible(shown, over, overSince, typedAt, at) {
163
+ return !shown || at - typedAt > TYPING_MS || (over && overSince > typedAt);
164
+ }
130
165
  /** Keys that type nothing on their own: they don't count as typing (a gesture still). */
131
166
  const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "Fn"]);
132
167
  /** The `<input>` types that take typed text (an unknown type is `text`). */
@@ -167,6 +202,25 @@ export function focusGuard(view) {
167
202
  let focusedAt = now();
168
203
  let lastKey = null;
169
204
  let typedAt = -Infinity;
205
+ /** When the person typed on the host's page, the last two seconds of it (P122). */
206
+ const typings = [];
207
+ const typed = (at) => {
208
+ typedAt = at;
209
+ typings.push(at);
210
+ while (typings.length > 0 && at - typings[0] > 2 * TYPING_MS) {
211
+ typings.shift();
212
+ }
213
+ };
214
+ /** The person's last typing on the host's page at or before `at` (-Infinity: none known). */
215
+ const typedBefore = (at) => {
216
+ for (let index = typings.length - 1; index >= 0; index -= 1) {
217
+ const each = typings[index];
218
+ if (each <= at) {
219
+ return each;
220
+ }
221
+ }
222
+ return -Infinity;
223
+ };
170
224
  let gestureAt = -Infinity;
171
225
  let pressAt = -Infinity;
172
226
  /** The host's page's last trusted press or key (P111: a nested page's gesture must be later). */
@@ -177,6 +231,13 @@ export function focusGuard(view) {
177
231
  * whether the frame is the person's for a gesture gate).
178
232
  */
179
233
  let waiting = null;
234
+ /**
235
+ * Whether the host's page sees the pointer over its frames (P120): learned once the pointer comes
236
+ * over one (`pointerover` on its element: Firefox, and Chromium and WebKit where frames are in their
237
+ * process), or a move from a text field into one doesn't blur the window (Firefox, which shows
238
+ * the pointer over a frame, measured). Full Chromium shows neither, and never learns it.
239
+ */
240
+ let pointerShown = false;
180
241
  /** When focus last went into a guarded frame, and whether the person moved it there. */
181
242
  let enteredAt = -Infinity;
182
243
  let earned = false;
@@ -187,7 +248,9 @@ export function focusGuard(view) {
187
248
  /**
188
249
  * A take-back in progress: the field focus goes back to, the frame it came from, when focus was
189
250
  * last given back, and since when it has stayed in the field. Ends once it has stayed `HELD_MS`,
190
- * the person moves focus somewhere of their own, or the field or frame is gone.
251
+ * the person moves focus somewhere of their own, or the field or frame is gone. A `fight` undoes
252
+ * the page's own move (a take-back, `focusField`, or the person leaving a frame that took focus
253
+ * itself), not the person leaving a frame they moved into (P120).
191
254
  */
192
255
  let contest = null;
193
256
  const activation = () => {
@@ -202,15 +265,19 @@ export function focusGuard(view) {
202
265
  };
203
266
  /**
204
267
  * What the person's move would need, read now: see `personMoved`. Into a nested page's frame
205
- * whose shell hasn't spoken of this move yet, `wait` (P111).
268
+ * whose shell hasn't spoken of this move yet, `wait` (P111). In a fight over a text field
269
+ * (`fight`, P120), a nested page's frame is judged as any frame is, its shell's word not asked:
270
+ * an activation it says turned on then is the person's keys landing in it far more often than a
271
+ * press (a press back into the page within `HELD_MS` of focus landing in the field).
206
272
  */
207
- const judge = (frame, guarded, seen, at) => {
208
- const word = guarded.word;
273
+ const judge = (frame, guarded, seen, at, fight = false) => {
274
+ const word = fight ? null : guarded.word;
275
+ const over = frame.matches(":hover");
209
276
  const moved = personMoved({
210
277
  now: at,
211
278
  seen,
212
279
  pressed: frame.matches(":active"),
213
- over: frame.matches(":hover"),
280
+ over,
214
281
  overSince: guarded.overSince,
215
282
  lastKey,
216
283
  typedAt,
@@ -218,19 +285,31 @@ export function focusGuard(view) {
218
285
  gestureAt,
219
286
  activation: activation(),
220
287
  hostMoved: hostMove !== null && hostMove.frame === frame && at - hostMove.at <= TAB_MS,
221
- ...(word === null ? {} : { shell: { word, hostInputAt: inputAt } }),
288
+ ...(word === null ? {} : { shell: { word, hostInputAt: inputAt, pointerShown } }),
222
289
  });
223
290
  hostMove = null;
224
291
  // The shell tells a move at its next frame, the host's page hears it first: until the shell
225
- // said focus came in (around now), its activation may be on its way.
226
- if (!moved && word !== null && word.supported && word.focusedAt < at - SHELL_EARLY_MS) {
292
+ // said focus came in (around now), its activation may be on its way; unless no press could
293
+ // have made the move (P120), which nothing the shell says changes.
294
+ if (!moved &&
295
+ word !== null &&
296
+ word.supported &&
297
+ word.focusedAt < at - SHELL_EARLY_MS &&
298
+ at - typedAt >= KEY_PRESS_MS &&
299
+ pressPossible(pointerShown, over, guarded.overSince, typedAt, at)) {
227
300
  return "wait";
228
301
  }
229
302
  return moved;
230
303
  };
231
304
  /** Waits for a nested page's shell's word on a move (P111): decided by `settle`. */
232
- const wait = (field, frame, guarded, at, failed) => {
233
- waiting = { field, frame, guarded, since: at, failed };
305
+ const wait = (field, frame, guarded, at) => {
306
+ waiting = { field, frame, guarded, since: at };
307
+ // The shell looks at its next frame, and a key the person types into the page before then
308
+ // turns its activation on as a press does: asked to look now, it says what it saw as the move
309
+ // was heard (P120).
310
+ guarded.asked += 1;
311
+ guarded.answered = false;
312
+ guarded.ask?.(guarded.asked);
234
313
  known = frame;
235
314
  enteredAt = at;
236
315
  earned = false;
@@ -246,15 +325,34 @@ export function focusGuard(view) {
246
325
  return;
247
326
  }
248
327
  const { field, frame, guarded } = held;
249
- if (deepActive(document) !== frame || !frames.has(frame)) {
250
- // Moved on since: from the frame, as the next look judges it.
328
+ const active = deepActive(document);
329
+ if (active !== frame || !frames.has(frame)) {
251
330
  waiting = null;
331
+ // Moved on since to nothing, or back to the field, with no press of the person's on the
332
+ // host's page: still the page's move from that field (P120, after the audit of P111's guard:
333
+ // NG-1, where the frame took it again at once and was then let be), watched as a take-back
334
+ // is, focus on nothing given back and counted.
335
+ if (field !== null &&
336
+ field.isConnected &&
337
+ pressAt <= held.since &&
338
+ (active === null || active === document.body || active === field)) {
339
+ known = field;
340
+ contest = { field, frame, guarded, fight: true, gaveAt: held.since, heldSince: null };
341
+ schedule();
342
+ return;
343
+ }
344
+ // Anywhere else: from the frame, as the next look judges it.
252
345
  known = frame;
253
346
  return;
254
347
  }
255
348
  const word = guarded.word;
256
- const theirs = word !== null && shellGesture(word, inputAt, at);
257
- const spoke = word !== null && word.focusedAt >= held.since - SHELL_EARLY_MS;
349
+ // The shell's activation, where a press could have made it: within a second of the person's
350
+ // typing on the host's page with the pointer elsewhere, it is their keys landing in the page
351
+ // (P120). Read as of the move.
352
+ const theirs = word !== null && shellGesture(word, inputAt, at) && !(pointerShown && word.keyed === true);
353
+ // It said focus came in around the move, or answered the ask the move made with focus in it.
354
+ const spoke = word !== null &&
355
+ (word.focusedAt >= held.since - SHELL_EARLY_MS || (guarded.answered && word.focused));
258
356
  if (theirs) {
259
357
  waiting = null;
260
358
  known = frame;
@@ -266,7 +364,7 @@ export function focusGuard(view) {
266
364
  }
267
365
  waiting = null;
268
366
  if (field !== null && field.isConnected) {
269
- takeBack(field, frame, guarded, at, held.failed);
367
+ takeBack(field, frame, guarded, at, false);
270
368
  }
271
369
  };
272
370
  /**
@@ -289,7 +387,7 @@ export function focusGuard(view) {
289
387
  // Until it is back, the field counts as the page's focus, so a move that didn't take is seen.
290
388
  known = field;
291
389
  focusedAt = at;
292
- contest = { field, frame, guarded, gaveAt: at, heldSince: null };
390
+ contest = { field, frame, guarded, fight: true, gaveAt: at, heldSince: null };
293
391
  giveBack(field, frame);
294
392
  schedule();
295
393
  const take = { typing: at - typedAt <= TYPING_MS, failed };
@@ -337,7 +435,10 @@ export function focusGuard(view) {
337
435
  return false;
338
436
  }
339
437
  if (active === frame) {
340
- const verdict = judge(frame, guarded, seen, at);
438
+ // The frame has it again. In a fight, the person's only by a Tab, the host's own move, or a
439
+ // press the engine shows: a nested page's too, its shell's word not asked (P120, after the
440
+ // audit of P111's guard, NG-1, where waiting for it let the frame keep the keyboard).
441
+ const verdict = judge(frame, guarded, seen, at, watched.fight);
341
442
  if (verdict === true) {
342
443
  contest = null;
343
444
  known = frame;
@@ -346,10 +447,11 @@ export function focusGuard(view) {
346
447
  return true;
347
448
  }
348
449
  if (verdict === "wait") {
349
- // A nested page's frame took it again (P111): its shell decides, as it would at first.
450
+ // The person left a nested page they had moved into, and focus went back in (P111): its
451
+ // shell decides, as it would at first.
350
452
  if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
351
453
  contest = null;
352
- wait(field, frame, guarded, at, true);
454
+ wait(field, frame, guarded, at);
353
455
  }
354
456
  return true;
355
457
  }
@@ -406,7 +508,7 @@ export function focusGuard(view) {
406
508
  const verdict = takesText(was) || judge(active, entered, seen, at);
407
509
  if (verdict === "wait") {
408
510
  // A nested page's (P111): theirs once its shell says so; nothing to take back.
409
- wait(null, active, entered, at, false);
511
+ wait(null, active, entered, at);
410
512
  return;
411
513
  }
412
514
  earned = verdict;
@@ -420,6 +522,7 @@ export function focusGuard(view) {
420
522
  field: active,
421
523
  frame: was,
422
524
  guarded: left,
525
+ fight: !earned,
423
526
  gaveAt: at,
424
527
  heldSince: at,
425
528
  };
@@ -430,12 +533,17 @@ export function focusGuard(view) {
430
533
  return;
431
534
  }
432
535
  const frame = active;
536
+ if (!seen) {
537
+ // A move out of a text field the window didn't blur for: Firefox, which shows the host's
538
+ // page the pointer over a frame (P120).
539
+ pointerShown = true;
540
+ }
433
541
  const verdict = judge(frame, guarded, seen, at);
434
542
  if (verdict === true) {
435
543
  return;
436
544
  }
437
545
  if (verdict === "wait") {
438
- wait(was, frame, guarded, at, false);
546
+ wait(was, frame, guarded, at);
439
547
  return;
440
548
  }
441
549
  takeBack(was, frame, guarded, at, false);
@@ -478,7 +586,7 @@ export function focusGuard(view) {
478
586
  inputAt = at;
479
587
  }
480
588
  if (event.key !== "Tab" && !MODIFIERS.has(event.key)) {
481
- typedAt = at;
589
+ typed(at);
482
590
  }
483
591
  }, true);
484
592
  // A click too (an assistive technology's click on the host's own UI dispatches no press), and
@@ -490,7 +598,7 @@ export function focusGuard(view) {
490
598
  view.addEventListener(type, press, true);
491
599
  }
492
600
  view.addEventListener("input", () => {
493
- typedAt = now();
601
+ typed(now());
494
602
  gestureAt = typedAt;
495
603
  }, true);
496
604
  // Focus moving within the page: what had it, for the next move out of a text field.
@@ -517,12 +625,16 @@ export function focusGuard(view) {
517
625
  taken: new Set(),
518
626
  overSince: -Infinity,
519
627
  heardAt: -Infinity,
628
+ ask: options?.nested === true ? options.ask : undefined,
629
+ asked: 0,
630
+ answered: false,
520
631
  word: options?.nested === true
521
632
  ? { supported: true, activatedAt: -Infinity, focused: false, focusedAt: -Infinity }
522
633
  : null,
523
634
  };
524
635
  frame.addEventListener("pointerover", () => {
525
636
  entry.overSince = now();
637
+ pointerShown = true;
526
638
  });
527
639
  frames.set(frame, entry);
528
640
  guarded = entry;
@@ -545,17 +657,42 @@ export function focusGuard(view) {
545
657
  }
546
658
  const at = now();
547
659
  // Off to on after a stall, the shell's or the host's (no word for longer than its beat
548
- // allows): uncertain, and so until it goes off (P111, after its review).
660
+ // allows): uncertain, and so until it goes off (P111, after its review). So is one that
661
+ // turned on while the guard fights this frame for a text field (P120): the person's keys,
662
+ // meant for the field, landing in the page.
663
+ // So is one that turned on within `KEY_PRESS_MS` of a key the person typed on the host's page
664
+ // before it (P122): that key's successor, landing in the page.
549
665
  const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
550
666
  const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
551
- const uncertain = said.ago !== null && (before.uncertain === true || (turnedOn && stalled));
667
+ const fought = contest !== null && contest.fight && contest.frame === frame;
668
+ // The typing before it, never after: a key the person typed on the host's page after they
669
+ // pressed the page, before the shell's word came, says nothing of that press (P122, after
670
+ // CI). The shell saw it turn on at its look, so it turned on at most a look's gap before:
671
+ // only a key before then counts.
672
+ const turnedAt = said.ago === null ? -Infinity : at - said.ago - Math.min(said.gap, SHELL_STALL_MS);
673
+ const typing = typedBefore(turnedAt);
674
+ const soon = said.ago !== null && turnedAt - typing < KEY_PRESS_MS;
675
+ const uncertain = said.ago !== null &&
676
+ (before.uncertain === true || (turnedOn && (stalled || fought || soon)));
552
677
  guarded.heardAt = at;
678
+ if (said.asked !== undefined && said.asked === guarded.asked) {
679
+ guarded.answered = true;
680
+ }
681
+ // Whether a press could have turned it on, judged as it did (P120, after its review): the
682
+ // person's typing then, and the pointer then, not when a move is later judged.
683
+ const activatedAt = said.ago === null || uncertain ? -Infinity : at - said.ago;
684
+ const keyed = activatedAt === -Infinity
685
+ ? false
686
+ : turnedOn
687
+ ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, typing, turnedAt)
688
+ : before.keyed === true;
553
689
  guarded.word = {
554
690
  supported: said.supported,
555
- activatedAt: said.ago === null || uncertain ? -Infinity : at - said.ago,
691
+ activatedAt,
556
692
  focused: said.focused,
557
693
  focusedAt: said.focused && !before.focused ? at : before.focusedAt,
558
694
  ...(uncertain ? { uncertain: true } : {}),
695
+ ...(keyed ? { keyed: true } : {}),
559
696
  };
560
697
  if (waiting?.frame === frame) {
561
698
  settle(at);
@@ -568,8 +705,15 @@ export function focusGuard(view) {
568
705
  }
569
706
  },
570
707
  gesture(frame) {
571
- const word = frames.get(frame)?.word ?? null;
572
- return word !== null && shellGesture(word, inputAt, now());
708
+ const guarded = frames.get(frame);
709
+ const word = guarded?.word ?? null;
710
+ const at = now();
711
+ // Where a press could have made it (P120): a key the person typed into the page, meant for
712
+ // the host's composer, turns the shell's activation on too.
713
+ return (guarded !== undefined &&
714
+ word !== null &&
715
+ shellGesture(word, inputAt, at) &&
716
+ !(pointerShown && word.keyed === true));
573
717
  },
574
718
  focus(frame) {
575
719
  hostMove = { frame, at: now() };
@@ -596,7 +740,7 @@ export function focusGuard(view) {
596
740
  field.focus({ preventScroll: true });
597
741
  known = field;
598
742
  focusedAt = now();
599
- contest = { field, frame, guarded, gaveAt: focusedAt, heldSince: null };
743
+ contest = { field, frame, guarded, fight: true, gaveAt: focusedAt, heldSince: null };
600
744
  schedule();
601
745
  },
602
746
  };
@@ -1,4 +1,4 @@
1
- import { FRAME_STATUS_METHOD, SHELL_BEAT_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
1
+ import { FRAME_STATUS_METHOD, SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
2
2
  import { postMessageTransport } from "../transport/post-message.js";
3
3
  import { focusGuard } from "./focus-guard.js";
4
4
  /** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
@@ -28,7 +28,7 @@ function shellWords(opened, frame, guard) {
28
28
  if (params === null || typeof params !== "object") {
29
29
  return;
30
30
  }
31
- const { supported, ago, focused, gap } = params;
31
+ const { supported, ago, focused, gap, asked } = params;
32
32
  const span = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
33
33
  if (message.method === SHELL_BEAT_METHOD) {
34
34
  if (span(gap)) {
@@ -40,10 +40,17 @@ function shellWords(opened, frame, guard) {
40
40
  typeof supported !== "boolean" ||
41
41
  typeof focused !== "boolean" ||
42
42
  !(ago === null || span(ago)) ||
43
- !span(gap)) {
43
+ !span(gap) ||
44
+ !(asked === undefined || (Number.isSafeInteger(asked) && asked >= 0))) {
44
45
  return;
45
46
  }
46
- guard.shell(frame, { supported, ago: ago, focused, gap: gap });
47
+ guard.shell(frame, {
48
+ supported,
49
+ ago: ago,
50
+ focused,
51
+ gap: gap,
52
+ ...(asked === undefined ? {} : { asked: asked }),
53
+ });
47
54
  });
48
55
  return {
49
56
  send: (message) => opened.send(message),
@@ -113,17 +120,25 @@ export const webPlatform = {
113
120
  const guard = focusGuard(view);
114
121
  const taken = new Set();
115
122
  const nested = spec.nested === true && spec.source.kind === "url";
116
- const unguard = guard.add(frame, (take) => {
117
- for (const listener of taken) {
118
- listener(take);
119
- }
120
- }, { nested });
121
123
  // A served frame may pass through the host's own pages (a redirect entry's, P068): what they
122
124
  // say of the frame's status is heard too, and nothing else from there.
123
125
  const own = view.origin;
124
126
  const opened = postMessageTransport(() => frame.contentWindow, origin, view, origin === "null" || own === "null" || own === origin
125
127
  ? undefined
126
128
  : { origin: own, accept: isFrameStatus });
129
+ const unguard = guard.add(frame, (take) => {
130
+ for (const listener of taken) {
131
+ listener(take);
132
+ }
133
+ }, {
134
+ nested,
135
+ // A nested page's shell is asked to look as the guard hears a move into its frame (P120).
136
+ ...(nested
137
+ ? {
138
+ ask: (n) => opened.send({ jsonrpc: "2.0", method: SHELL_LOOK_METHOD, params: { n } }),
139
+ }
140
+ : {}),
141
+ });
127
142
  // A nested page's shell (P111): its own words go to the guard, by the frame's window and the
128
143
  // content origin (the transport's checks); the page's pass on. The shell drops any page
129
144
  // message in its namespace, so there none is the page's.
@@ -223,7 +223,8 @@ export interface PortholeFrameProps {
223
223
  readonly onContentError?: (message: string) => void;
224
224
  /**
225
225
  * What failed on the host's side: its locator (`locate`), a display that couldn't be made
226
- * (`mount`), an annotation call refused (`annotations`). Never the agent's.
226
+ * (`mount`), an annotation call refused (`annotations`), a frame status the content forged and
227
+ * the host didn't take (`frame-status`, P124). Never the agent's.
227
228
  */
228
229
  readonly onHostError?: (error: {
229
230
  readonly message: string;
@@ -3,7 +3,7 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath } from "../files/paths.js";
3
3
  import { fileTypeOf } from "../files/types.js";
4
4
  import { isCodeAsset } from "../runtime/requests.js";
5
5
  import { sha256, utf8 } from "./crypto.js";
6
- import { NESTED_FILE_HEADERS } from "./nested.js";
6
+ import { NESTED_FILE_HEADERS, nestedFileCsp } from "./nested.js";
7
7
  const HEX = /^[0-9a-f]{64}$/u;
8
8
  const YEAR = 31_536_000;
9
9
  const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -174,12 +174,12 @@ export async function serveFile(serving) {
174
174
  // sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
175
175
  // origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
176
176
  // a script's gets one too).
177
- const csp = role === "file"
178
- ? INERT_FILE_CSP
179
- : role === "page"
180
- ? servedDocumentCsp(serving.compiled.config, directives)
181
- : nested
182
- ? `${serializeCsp(directives)}; sandbox`
177
+ const csp = nested
178
+ ? nestedFileCsp(role, directives)
179
+ : role === "file"
180
+ ? INERT_FILE_CSP
181
+ : role === "page"
182
+ ? servedDocumentCsp(serving.compiled.config, directives)
183
183
  : serializeCsp(directives);
184
184
  const headers = new Headers({
185
185
  "content-type": type,
@@ -37,7 +37,7 @@ export { createContentHost, HEALTH_PATH, ISSUE_BODY_BYTES, type ContentHealthVie
37
37
  export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
38
38
  export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
39
39
  export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
40
- export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
40
+ export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
41
41
  export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
42
42
  export { conformancePage } from "../conformance/page.ts";
43
43
  export type { PortholeConfig } from "../config/schema.ts";
@@ -41,7 +41,7 @@ export { FRAME_STATUS_METHOD } from "../isolation/types.js";
41
41
  // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
42
42
  // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
43
43
  // pages").
44
- export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
44
+ export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
45
45
  export { isHostLabel, prefixedName } from "./naming.js";
46
46
  // The page an app serves in conformance test mode (P071).
47
47
  export { conformancePage } from "../conformance/page.js";
@@ -1,5 +1,7 @@
1
1
  import type { CompiledConfig } from "../compile/compile.ts";
2
+ import { type CspDirective } from "../compile/policy.ts";
2
3
  import { type FrameShellOptions } from "../shell/frame.ts";
4
+ export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
3
5
  /**
4
6
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
5
7
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
@@ -11,11 +13,6 @@ import { type FrameShellOptions } from "../shell/frame.ts";
11
13
  * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
12
14
  * address.
13
15
  */
14
- /**
15
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
16
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
17
- */
18
- export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
19
16
  /**
20
17
  * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
21
18
  * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
@@ -26,8 +23,6 @@ export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
26
23
  * serves its nested pages on it too.
27
24
  */
28
25
  export declare function nestedLabelOf(label: string): string;
29
- /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
30
- export declare const isNestedLabel: (label: string) => boolean;
31
26
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
32
27
  export declare const NESTED_FILES_PREFIX = "/__porthole/f/";
33
28
  /**
@@ -50,6 +45,17 @@ export declare function nestedShellResponse(compiled: CompiledConfig, options: F
50
45
  * above it, the host origins (`frame-ancestors` names every ancestor).
51
46
  */
52
47
  export declare const nestedAncestors: (origin: string, frameAncestors: string) => string;
48
+ /**
49
+ * A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
50
+ * `/server` and a content Worker of a host's own, P121): a page its directives and
51
+ * `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
52
+ * (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
53
+ * directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
54
+ * the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
55
+ * config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
56
+ * a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
57
+ */
58
+ export declare function nestedFileCsp(role: "page" | "script" | "file", directives: readonly CspDirective[]): string;
53
59
  /**
54
60
  * What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
55
61
  * origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
@@ -1,7 +1,9 @@
1
- import { servedPermissionsPolicy, serializeCsp } from "../compile/policy.js";
1
+ import { INERT_FILE_CSP, PAGE_SANDBOX_TOKENS, servedPermissionsPolicy, serializeCsp, } from "../compile/policy.js";
2
2
  import { frameShellDocument, frameShellScript } from "../shell/frame.js";
3
+ import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
3
4
  import { sha256, utf8 } from "./crypto.js";
4
5
  import { base32 } from "./keys.js";
6
+ export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
5
7
  /**
6
8
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
7
9
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
@@ -13,12 +15,6 @@ import { base32 } from "./keys.js";
13
15
  * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
14
16
  * address.
15
17
  */
16
- /**
17
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
18
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
19
- */
20
- export const PORTHOLE_LABEL_PREFIX = "porthole-";
21
- const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
22
18
  /**
23
19
  * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
24
20
  * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
@@ -31,8 +27,6 @@ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
31
27
  export function nestedLabelOf(label) {
32
28
  return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
33
29
  }
34
- /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
35
- export const isNestedLabel = (label) => NESTED_LABEL.test(label);
36
30
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
37
31
  export const NESTED_FILES_PREFIX = "/__porthole/f/";
38
32
  const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
@@ -60,6 +54,14 @@ export function nestedShellCsp(script, origin, hostOrigins) {
60
54
  * stored (it carries the page's sealed address), its page at `options.page`.
61
55
  */
62
56
  export function nestedShellResponse(compiled, options) {
57
+ // On the shell's own label alone (P114), its page on that origin (P121): a content Worker of a
58
+ // host's own that would serve it beside other content is refused here, not left to its routes.
59
+ if (!onNestedLabel(options.origin)) {
60
+ throw new TypeError(`nestedShellResponse: origin ${options.origin} isn't on a nested page's own label (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf)`);
61
+ }
62
+ if (new URL(options.page).origin !== options.origin) {
63
+ throw new TypeError("nestedShellResponse: page is on the shell's own origin");
64
+ }
63
65
  const script = frameShellScript(options);
64
66
  const headers = new Headers({
65
67
  "content-type": "text/html; charset=utf-8",
@@ -84,6 +86,26 @@ export function nestedShellResponse(compiled, options) {
84
86
  * above it, the host origins (`frame-ancestors` names every ancestor).
85
87
  */
86
88
  export const nestedAncestors = (origin, frameAncestors) => `${origin} ${frameAncestors}`;
89
+ /**
90
+ * A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
91
+ * `/server` and a content Worker of a host's own, P121): a page its directives and
92
+ * `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
93
+ * (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
94
+ * directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
95
+ * the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
96
+ * config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
97
+ * a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
98
+ */
99
+ export function nestedFileCsp(role, directives) {
100
+ switch (role) {
101
+ case "page":
102
+ return serializeCsp([...directives, ["sandbox", ...PAGE_SANDBOX_TOKENS]]);
103
+ case "script":
104
+ return serializeCsp([...directives, ["sandbox"]]);
105
+ case "file":
106
+ return INERT_FILE_CSP;
107
+ }
108
+ }
87
109
  /**
88
110
  * What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
89
111
  * origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and