@botiverse/porthole 0.9.0 → 0.10.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.
@@ -65,12 +65,18 @@ async function expectNoChild(
65
65
  display: LaunchedDisplay,
66
66
  udp: UdpOracle,
67
67
  ): Promise<Record<string, unknown>> {
68
- const verdict = await context.result(display, 15_000);
68
+ // A document written over (`document.write`, once the shell's lock is gone) or navigated away
69
+ // is started again before it reports: that is the escape itself, the probe's verdict (P096).
70
+ const verdict = await context.result(display, 15_000).catch(async (error: unknown) => {
71
+ const restarts = (await display.events()).filter((event) => event.type === "navigated");
72
+ expect(restarts, "probe: the content's document was replaced before it reported").toEqual([]);
73
+ throw error;
74
+ });
69
75
  await settle(1_000);
70
76
  expect(verdict.error, "the attack itself failed").toBeUndefined();
71
- expect(verdict.childRan ?? false, "a nested frame's script ran").toBe(false);
72
- expect(verdict.frames ?? 0, "a nested frame is still in the tree").toBe(0);
73
- expect(udp.packets(), "STUN packets reached the oracle").toBe(0);
77
+ expect(verdict.childRan ?? false, "probe: a nested frame's script ran").toBe(false);
78
+ expect(verdict.frames ?? 0, "probe: a nested frame is still in the tree").toBe(0);
79
+ expect(udp.packets(), "probe: STUN packets reached the oracle").toBe(0);
74
80
  if (verdict.reached !== undefined || verdict.blocked !== undefined) {
75
81
  context.measured(
76
82
  `${context.engine}: a new frame's realm, in the task that added it, was ${verdict.blocked === undefined ? `reachable (RTCPeerConnection: ${JSON.stringify(verdict.reached)})` : `unreachable (${JSON.stringify(verdict.blocked)})`}`,
@@ -86,9 +92,14 @@ const childSetup = (stun: string) => `
86
92
  const child = ${js(childDocument(stun))};
87
93
  const makeFrame = () => { const f = document.createElement("iframe"); f.setAttribute("srcdoc", child); return f; };`;
88
94
 
89
- /** A navigated document's beacon to an allowed witness: heard only if that document ran. */
95
+ /**
96
+ * A navigated document's beacon to an allowed witness, heard only if that document ran: its first
97
+ * act, a real beacon, which the browser delivers even when the frame is removed a moment later (the
98
+ * display started again). A fetch at its end raced that restart: the embedder-csp control saw
99
+ * blob: and data: documents run only some of the time (P096).
100
+ */
90
101
  const witnessScript = (origin: string): string =>
91
- `<script>fetch(${js(`${origin}/ran`)}).catch(() => {});</script>`;
102
+ `<script>navigator.sendBeacon(${js(`${origin}/ran`)}) || fetch(${js(`${origin}/ran`)}, { keepalive: true }).catch(() => {});</script>`;
92
103
 
93
104
  /**
94
105
  * A document the frame navigates to must never run: it would be a fresh realm without the shell's
@@ -97,7 +108,7 @@ const witnessScript = (origin: string): string =>
97
108
  */
98
109
  function measureWitness(context: ProbeContext, witness: HttpOracle, scheme: string): void {
99
110
  const ran = witness.requests().some((request) => request.path === "/ran");
100
- expect(ran, `a ${scheme} document the frame navigated to ran`).toBe(false);
111
+ expect(ran, `probe: a ${scheme} document the frame navigated to ran`).toBe(false);
101
112
  }
102
113
 
103
114
  /** Every navigation attempt's verdict: nothing reached the oracle, and the content stayed or restarted. */
@@ -108,10 +119,10 @@ async function expectNoNavigation(
108
119
  udp?: UdpOracle,
109
120
  ): Promise<void> {
110
121
  await settle(1_500);
111
- expect(canary.requests(), "the navigation reached the canary").toEqual([]);
112
- expect(context.requestsTo(canary.origin), "the page requested the canary").toEqual([]);
122
+ expect(canary.requests(), "probe: the navigation reached the canary").toEqual([]);
123
+ expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
113
124
  if (udp !== undefined) {
114
- expect(udp.packets(), "a navigated document reached the STUN oracle").toBe(0);
125
+ expect(udp.packets(), "probe: a navigated document reached the STUN oracle").toBe(0);
115
126
  }
116
127
  const events = await display.events();
117
128
  const restarts = events.filter((event) => event.type === "navigated").length;
@@ -124,7 +135,7 @@ async function expectNoNavigation(
124
135
  const frame = await display.frame();
125
136
  await expect(
126
137
  frame.locator("#marker"),
127
- "the frame lost its content without being started again",
138
+ "probe: the frame lost its content without being started again",
128
139
  ).toHaveCount(1);
129
140
  context.measured(`${context.engine}: the frame kept its content`);
130
141
  }
@@ -195,9 +206,9 @@ const escape = (id: string, title: string, code: string | ((canary: string) => s
195
206
  });
196
207
  const before = context.page.url();
197
208
  await expectNoNavigation(context, display, canary);
198
- expect(popups, "a popup opened").toEqual([]);
199
- expect(downloads, "a download started").toEqual([]);
200
- expect(context.page.url(), "the top page navigated").toBe(before);
209
+ expect(popups, "probe: a popup opened").toEqual([]);
210
+ expect(downloads, "probe: a download started").toEqual([]);
211
+ expect(context.page.url(), "probe: the top page navigated").toBe(before);
201
212
  },
202
213
  });
203
214
 
@@ -262,8 +273,8 @@ const hint = (id: string, make: (canary: string) => Hint): Probe => ({
262
273
  });
263
274
  await context.result(display, 15_000);
264
275
  await settle(1_000);
265
- expect(canary.requests(), "a hint fetched from the canary").toEqual([]);
266
- expect(canary.connections(), "a hint opened a connection to the canary").toBe(0);
276
+ expect(canary.requests(), "probe: a hint fetched from the canary").toEqual([]);
277
+ expect(canary.connections(), "probe: a hint opened a connection to the canary").toBe(0);
267
278
  },
268
279
  });
269
280
 
@@ -327,9 +338,12 @@ const sdkProbe = (preset: "inline" | "artifact" | "mcp-app"): Probe => ({
327
338
  document: page,
328
339
  });
329
340
  const verdict = await context.result(display, 20_000);
330
- expect(verdict.error, "App.connect failed").toBeUndefined();
331
- expect(verdict).toMatchObject({ connected: true, theme: "light" });
332
- expect(verdict.styles).toBeGreaterThan(0);
341
+ expect(verdict.error, "probe: App.connect failed").toBeUndefined();
342
+ expect(verdict, "probe: the App SDK didn't connect with the host's theme").toMatchObject({
343
+ connected: true,
344
+ theme: "light",
345
+ });
346
+ expect(verdict.styles, "probe: the host context carried no theme variables").toBeGreaterThan(0);
333
347
  },
334
348
  });
335
349
 
@@ -354,7 +368,10 @@ export const PROBES: readonly Probe[] = [
354
368
  config: inline(),
355
369
  content: attack(`r.origin = window.origin;`),
356
370
  });
357
- expect((await context.result(display)).origin).toBe("null");
371
+ expect(
372
+ (await context.result(display)).origin,
373
+ "probe: the content's origin isn't opaque",
374
+ ).toBe("null");
358
375
  },
359
376
  },
360
377
  {
@@ -371,7 +388,10 @@ export const PROBES: readonly Probe[] = [
371
388
  try { window.sendPrompt = () => "replaced"; } catch (e) {}
372
389
  r.replaced = window.sendPrompt !== original;`),
373
390
  });
374
- expect(await context.result(display)).toMatchObject({
391
+ expect(
392
+ await context.result(display),
393
+ "probe: a global was defined without its capability, or replaced",
394
+ ).toMatchObject({
375
395
  sendPrompt: "function",
376
396
  openLink: "undefined",
377
397
  replaced: false,
@@ -393,7 +413,10 @@ export const PROBES: readonly Probe[] = [
393
413
  r.accent = style.getPropertyValue("--color-accent").trim();
394
414
  r.theme = document.documentElement.getAttribute("data-theme");`),
395
415
  });
396
- expect(await context.result(display)).toMatchObject({
416
+ expect(
417
+ await context.result(display),
418
+ "probe: the declared theme wasn't applied",
419
+ ).toMatchObject({
397
420
  accent: resolveTheme(config.theme, "dark")["--color-accent"],
398
421
  theme: "dark",
399
422
  });
@@ -413,9 +436,15 @@ export const PROBES: readonly Probe[] = [
413
436
  });
414
437
  await context.result(display);
415
438
  const frame = await display.frame();
416
- await expect(frame.locator("body")).toHaveAttribute("data-ran", "1");
439
+ await expect(
440
+ frame.locator("body"),
441
+ "probe: the content didn't run exactly once",
442
+ ).toHaveAttribute("data-ran", "1");
417
443
  await settle(300);
418
- await expect(frame.locator("body")).toHaveAttribute("data-ran", "1");
444
+ await expect(frame.locator("body"), "probe: the content ran again").toHaveAttribute(
445
+ "data-ran",
446
+ "1",
447
+ );
419
448
  },
420
449
  },
421
450
 
@@ -458,9 +487,9 @@ export const PROBES: readonly Probe[] = [
458
487
  }
459
488
  expect(verdict.allowed, "the allowed origin (the positive control)").toBe("oracle");
460
489
  expect(allowed.requests().map((request) => request.path)).toContain("/allowed");
461
- expect(canary.requests(), "requests reached the canary").toEqual([]);
462
- expect(context.requestsTo(canary.origin)).toEqual([]);
463
- expect(verdict).toMatchObject({
490
+ expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
491
+ expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
492
+ expect(verdict, "probe: a channel to the canary wasn't blocked").toMatchObject({
464
493
  fetch: "blocked",
465
494
  xhr: "blocked",
466
495
  websocket: "blocked",
@@ -512,9 +541,9 @@ export const PROBES: readonly Probe[] = [
512
541
  context.inapplicable(INHERITED("img-src", allowed.origin));
513
542
  }
514
543
  expect(verdict.allowed, "the allowed image (the positive control)").toBe("loaded");
515
- expect(canary.requests(), "resources loaded from the canary").toEqual([]);
516
- expect(context.requestsTo(canary.origin)).toEqual([]);
517
- expect(verdict.script).toBe("undefined");
544
+ expect(canary.requests(), "probe: resources loaded from the canary").toEqual([]);
545
+ expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
546
+ expect(verdict.script, "probe: a script from the canary ran").toBe("undefined");
518
547
  },
519
548
  },
520
549
 
@@ -545,14 +574,14 @@ export const PROBES: readonly Probe[] = [
545
574
  });
546
575
  const verdict = await context.result(display, 15_000);
547
576
  await settle();
548
- expect(verdict).toMatchObject({
577
+ expect(verdict, "probe: a WebRTC constructor was reachable or came back").toMatchObject({
549
578
  names: [],
550
579
  peer: "undefined",
551
580
  prefixed: "undefined",
552
581
  restored: "undefined",
553
582
  });
554
- expect(verdict.connected).toBeUndefined();
555
- expect(udp.packets(), "STUN reached the oracle").toBe(0);
583
+ expect(verdict.connected, "probe: the content reached a peer connection").toBeUndefined();
584
+ expect(udp.packets(), "probe: STUN reached the oracle").toBe(0);
556
585
  if (!sends) {
557
586
  context.measured(
558
587
  `${context.engine}: the STUN oracle has no positive control here; the constructors' absence is the evidence`,
@@ -781,7 +810,7 @@ export const PROBES: readonly Probe[] = [
781
810
  context
782
811
  .requestsTo(new URL(context.page.url()).origin)
783
812
  .filter((url) => url.includes("/__probe/")),
784
- "the frame navigated to the host's own origin",
813
+ "probe: the frame navigated to the host's own origin",
785
814
  ).toEqual([]);
786
815
  },
787
816
  },
@@ -793,7 +822,7 @@ export const PROBES: readonly Probe[] = [
793
822
  const canary = await context.http();
794
823
  const udp = await context.udp();
795
824
  const witness = await context.http();
796
- const page = `<p id="blob">blob</p>${childDocument(udp.stun)}${witnessScript(witness.origin)}`;
825
+ const page = `${witnessScript(witness.origin)}<p id="blob">blob</p>${childDocument(udp.stun)}`;
797
826
  const display = await context.launch({
798
827
  config: inline({ egress: { connect: [witness.origin] } }),
799
828
  content: attack(`
@@ -812,7 +841,7 @@ export const PROBES: readonly Probe[] = [
812
841
  const canary = await context.http();
813
842
  const udp = await context.udp();
814
843
  const witness = await context.http();
815
- const page = `<p id="data">data</p>${childDocument(udp.stun)}${witnessScript(witness.origin)}`;
844
+ const page = `${witnessScript(witness.origin)}<p id="data">data</p>${childDocument(udp.stun)}`;
816
845
  const display = await context.launch({
817
846
  config: inline({ egress: { connect: [witness.origin] } }),
818
847
  content: attack(`
@@ -900,9 +929,12 @@ export const PROBES: readonly Probe[] = [
900
929
  });
901
930
  const verdict = await context.result(display);
902
931
  await settle();
903
- expect(verdict).toMatchObject({ baseChanged: false, plugins: 0 });
904
- expect(canary.requests()).toEqual([]);
905
- expect(context.requestsTo(canary.origin)).toEqual([]);
932
+ expect(verdict, "probe: a <base> took effect or a plugin element stayed").toMatchObject({
933
+ baseChanged: false,
934
+ plugins: 0,
935
+ });
936
+ expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
937
+ expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
906
938
  },
907
939
  },
908
940
 
@@ -939,8 +971,11 @@ export const PROBES: readonly Probe[] = [
939
971
  });
940
972
  await context.result(display, 15_000);
941
973
  await settle(1_000);
942
- expect(canary.requests()).toEqual([]);
943
- expect(canary.connections()).toBe(0);
974
+ expect(canary.requests(), "probe: speculation rules fetched from the canary").toEqual([]);
975
+ expect(
976
+ canary.connections(),
977
+ "probe: speculation rules opened a connection to the canary",
978
+ ).toBe(0);
944
979
  },
945
980
  },
946
981
 
@@ -971,8 +1006,11 @@ export const PROBES: readonly Probe[] = [
971
1006
  localStorage.setItem("porthole-host-secret", "porthole-host-secret-value");
972
1007
  });
973
1008
  const verdict = await context.result(display);
974
- expect(verdict.origin).toBe("null");
975
- expect(verdict).toMatchObject({
1009
+ expect(verdict.origin, "probe: the content's origin isn't opaque").toBe("null");
1010
+ expect(
1011
+ verdict,
1012
+ "probe: the content reached the host's document, storage or opener",
1013
+ ).toMatchObject({
976
1014
  parentDocument: "blocked",
977
1015
  topDocument: "blocked",
978
1016
  parentLocation: "blocked",
@@ -981,8 +1019,10 @@ export const PROBES: readonly Probe[] = [
981
1019
  html: false,
982
1020
  opener: true,
983
1021
  });
984
- expect(["blocked", ""]).toContain(verdict.cookie);
985
- expect(canary.requests()).toEqual([]);
1022
+ expect(["blocked", ""], "probe: the content read the host's cookie").toContain(
1023
+ verdict.cookie,
1024
+ );
1025
+ expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
986
1026
  },
987
1027
  },
988
1028
  {
@@ -1011,10 +1051,15 @@ export const PROBES: readonly Probe[] = [
1011
1051
  const verdict = await context.result(display);
1012
1052
  await settle();
1013
1053
  expect(verdict.siblings, "the probe found its sibling").toBeGreaterThan(0);
1014
- expect(canary.requests()).toEqual([]);
1054
+ expect(canary.requests(), "probe: a sibling was navigated to the canary").toEqual([]);
1015
1055
  const frame = await victim.frame();
1016
- await expect(frame.locator("#victim")).toHaveText("victim");
1017
- await expect(frame.locator("#hijacked")).toHaveCount(0);
1056
+ await expect(
1057
+ frame.locator("#victim"),
1058
+ "probe: the other display lost its content",
1059
+ ).toHaveText("victim");
1060
+ await expect(frame.locator("#hijacked"), "probe: the other display was driven").toHaveCount(
1061
+ 0,
1062
+ );
1018
1063
  },
1019
1064
  },
1020
1065
 
@@ -1038,7 +1083,10 @@ export const PROBES: readonly Probe[] = [
1038
1083
  });
1039
1084
  await context.result(display, 15_000);
1040
1085
  await settle();
1041
- expect(context.requestsTo(host).filter((url) => url.includes("/portholeProbe/"))).toEqual([]);
1086
+ expect(
1087
+ context.requestsTo(host).filter((url) => url.includes("/portholeProbe/")),
1088
+ "probe: something loaded from the embedding page's own origin",
1089
+ ).toEqual([]);
1042
1090
  },
1043
1091
  },
1044
1092
  ...BEHAVIOR_PROBES,