@botiverse/porthole 0.14.6 → 0.14.8

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 (53) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/dist/check/files.js +2 -0
  3. package/dist/check/lint.js +82 -3
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +17 -6
  6. package/dist/compile/policy.js +22 -7
  7. package/dist/config/schema.d.ts +13 -0
  8. package/dist/config/validate.js +15 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/conformance/kit.d.ts +5 -0
  11. package/dist/conformance/kit.js +21 -0
  12. package/dist/conformance/limits.js +10 -5
  13. package/dist/conformance/probes.js +139 -28
  14. package/dist/conformance/served.js +43 -14
  15. package/dist/guide/limits.js +8 -1
  16. package/dist/host/create-host.js +35 -4
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.js +1 -1
  19. package/dist/presets/presets.d.ts +6 -0
  20. package/dist/presets/presets.js +6 -0
  21. package/dist/server/files.js +4 -3
  22. package/dist/server/index.js +2 -1
  23. package/dist/server/server.js +89 -37
  24. package/dist/server/types.d.ts +23 -0
  25. package/dist/shell/plan.d.ts +5 -0
  26. package/dist/shell/plan.js +2 -0
  27. package/dist/shell/runtime.d.ts +30 -1
  28. package/dist/shell/runtime.js +785 -104
  29. package/docs/ADOPTING.md +36 -0
  30. package/docs/DECISIONS.md +341 -0
  31. package/docs/DESIGN.md +7 -4
  32. package/docs/THREAT_MODEL.md +30 -5
  33. package/docs/insertion-entry-points.md +95 -0
  34. package/package.json +1 -1
  35. package/src/check/files.ts +2 -0
  36. package/src/check/lint.ts +97 -8
  37. package/src/compile/policy.ts +23 -6
  38. package/src/config/schema.ts +13 -0
  39. package/src/config/validate.ts +16 -0
  40. package/src/conformance/kit.ts +22 -0
  41. package/src/conformance/limits.ts +10 -5
  42. package/src/conformance/probes.ts +149 -28
  43. package/src/conformance/served.ts +43 -14
  44. package/src/guide/limits.ts +9 -1
  45. package/src/host/create-host.ts +37 -4
  46. package/src/index.ts +1 -0
  47. package/src/presets/presets.ts +15 -0
  48. package/src/server/files.ts +8 -2
  49. package/src/server/index.ts +2 -1
  50. package/src/server/server.ts +116 -46
  51. package/src/server/types.ts +25 -0
  52. package/src/shell/plan.ts +7 -0
  53. package/src/shell/runtime.ts +788 -104
@@ -11,7 +11,7 @@ import {
11
11
  import { presets } from "../presets/presets.ts";
12
12
  import { resolveTheme } from "../theme/variables.ts";
13
13
  import type { ConformanceHost, LaunchedDisplay, LeakSuiteOptions } from "./index.ts";
14
- import { attack, inline, js, type Probe, type ProbeContext } from "./kit.ts";
14
+ import { attack, inline, js, noteRefused, type Probe, type ProbeContext } from "./kit.ts";
15
15
  import { BEHAVIOR_PROBES } from "./behavior.ts";
16
16
  import { CLIPBOARD_PROBES } from "./clipboard.ts";
17
17
  import { LIMIT_PROBES } from "./limits.ts";
@@ -77,6 +77,7 @@ async function expectNoChild(
77
77
  expect(verdict.childRan ?? false, "probe: a nested frame's script ran").toBe(false);
78
78
  expect(verdict.frames ?? 0, "probe: a nested frame is still in the tree").toBe(0);
79
79
  expect(udp.packets(), "probe: STUN packets reached the oracle").toBe(0);
80
+ noteRefused(context, verdict);
80
81
  if (verdict.reached !== undefined || verdict.blocked !== undefined) {
81
82
  context.measured(
82
83
  `${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)})`}`,
@@ -90,7 +91,7 @@ const childSetup = (stun: string) => `
90
91
  r.childRan = false;
91
92
  window.addEventListener("message", (event) => { if (event.data && event.data.tag === "child-ran") r.childRan = true; });
92
93
  const child = ${js(childDocument(stun))};
93
- const makeFrame = () => { const f = document.createElement("iframe"); f.setAttribute("srcdoc", child); return f; };`;
94
+ const makeFrame = () => { const f = created("iframe"); if (f) f.setAttribute("srcdoc", child); return f; };`;
94
95
 
95
96
  /**
96
97
  * A navigated document's beacon to an allowed witness, heard only if that document ran: its first
@@ -595,7 +596,8 @@ export const PROBES: readonly Probe[] = [
595
596
  "light-dom",
596
597
  "a srcdoc frame appended to the document",
597
598
  () => `
598
- document.body.append(makeFrame());
599
+ const f = makeFrame();
600
+ if (f) document.body.append(f);
599
601
  await wait(50);
600
602
  r.frames = document.querySelectorAll("iframe").length;`,
601
603
  ),
@@ -603,16 +605,18 @@ export const PROBES: readonly Probe[] = [
603
605
  "sync-realm",
604
606
  "reaching a new frame's realm in the same task it was added",
605
607
  (stun) => `
606
- const f = document.createElement("iframe");
607
- document.body.append(f);
608
- try {
609
- const w = window[window.length - 1] || f.contentWindow;
610
- r.reached = typeof (w && w.RTCPeerConnection);
611
- const p = new w.RTCPeerConnection({ iceServers: [{ urls: ${js(stun)} }], iceCandidatePoolSize: 4 });
612
- p.createDataChannel("x");
613
- p.createOffer().then((o) => p.setLocalDescription(o));
614
- r.childRan = true;
615
- } catch (e) { r.blocked = String(e && e.name); }
608
+ const f = created("iframe");
609
+ if (f) {
610
+ document.body.append(f);
611
+ try {
612
+ const w = window[window.length - 1] || f.contentWindow;
613
+ r.reached = typeof (w && w.RTCPeerConnection);
614
+ const p = new w.RTCPeerConnection({ iceServers: [{ urls: ${js(stun)} }], iceCandidatePoolSize: 4 });
615
+ p.createDataChannel("x");
616
+ p.createOffer().then((o) => p.setLocalDescription(o));
617
+ r.childRan = true;
618
+ } catch (e) { r.blocked = String(e && e.name); }
619
+ }
616
620
  await wait(50);
617
621
  r.frames = document.querySelectorAll("iframe").length;`,
618
622
  ),
@@ -623,7 +627,8 @@ export const PROBES: readonly Probe[] = [
623
627
  const host = document.createElement("div");
624
628
  document.body.append(host);
625
629
  const root = host.attachShadow({ mode: "open" });
626
- root.append(makeFrame());
630
+ const f = makeFrame();
631
+ if (f) root.append(f);
627
632
  await wait(50);
628
633
  r.frames = root.querySelectorAll("iframe").length;`,
629
634
  ),
@@ -635,7 +640,8 @@ export const PROBES: readonly Probe[] = [
635
640
  document.body.append(host);
636
641
  const root = host.attachShadow({ mode: "closed" });
637
642
  root.innerHTML = '<p>shadow</p>';
638
- root.append(makeFrame());
643
+ const f = makeFrame();
644
+ if (f) root.append(f);
639
645
  await wait(50);
640
646
  r.frames = root.querySelectorAll("iframe").length;`,
641
647
  ),
@@ -649,7 +655,8 @@ export const PROBES: readonly Probe[] = [
649
655
  const inner = document.createElement("div");
650
656
  first.append(inner);
651
657
  const second = inner.attachShadow({ mode: "open" });
652
- second.append(makeFrame());
658
+ const f = makeFrame();
659
+ if (f) second.append(f);
653
660
  await wait(50);
654
661
  r.frames = second.querySelectorAll("iframe").length;`,
655
662
  ),
@@ -703,13 +710,17 @@ export const PROBES: readonly Probe[] = [
703
710
  "plugins",
704
711
  "object and embed elements holding a document",
705
712
  () => `
706
- const object = document.createElement("object");
707
- object.type = "text/html";
708
- object.data = "data:text/html," + encodeURIComponent(child);
709
- const embed = document.createElement("embed");
710
- embed.type = "text/html";
711
- embed.src = "data:text/html," + encodeURIComponent(child);
712
- document.body.append(object, embed);
713
+ const object = created("object");
714
+ if (object) {
715
+ object.type = "text/html";
716
+ object.data = "data:text/html," + encodeURIComponent(child);
717
+ }
718
+ const embed = created("embed");
719
+ if (embed) {
720
+ embed.type = "text/html";
721
+ embed.src = "data:text/html," + encodeURIComponent(child);
722
+ }
723
+ document.body.append(...[object, embed].filter((each) => each !== null));
713
724
  await wait(50);
714
725
  r.frames = document.querySelectorAll("object, embed").length;`,
715
726
  ),
@@ -751,6 +762,115 @@ export const PROBES: readonly Probe[] = [
751
762
  },
752
763
  },
753
764
 
765
+ // ── 4, opted in: a page's own frames (P128) ────────────────────────────────────────────────
766
+ // A host that sets `nestedFrames: "own"` lets srcdoc frames (and, served, frames of the page's
767
+ // own files: leak/served/files.spec.ts) load and run; every other frame stays out. These run
768
+ // under an opaque inline widget, where they check what stays out. A srcdoc frame's scripts don't
769
+ // run there (measured, all three engines: the child inherits the frame's nonce policy), so that
770
+ // a kept frame runs is the served case's to show.
771
+ {
772
+ id: "4.own-external",
773
+ item: 4,
774
+ title:
775
+ "a page's own frames, opted in (P128): a frame of another site, a plugin, a frame with no document of its own: none stays or loads",
776
+ async run(context) {
777
+ const canary = await context.http();
778
+ const c = canary.origin;
779
+ const display = await context.launch({
780
+ config: inline({ nestedFrames: "own" }),
781
+ content: attack(
782
+ `
783
+ const away = document.createElement("iframe");
784
+ away.src = ${js(`${c}/made.html?d=secret`)};
785
+ document.body.append(away);
786
+ const blank = document.createElement("iframe");
787
+ document.body.append(blank);
788
+ const holder = document.createElement("div");
789
+ holder.innerHTML = ${js(`<iframe src="${c}/parsed.html?d=secret"></iframe><iframe src="parsed-relative.html"></iframe><object data="${c}/object.html" type="text/html"></object><embed src="${c}/embed.html" type="text/html"><iframe src="data:text/html,<p>x</p>"></iframe>`)};
790
+ document.body.append(holder);
791
+ await wait(1200);
792
+ r.blankKept = blank.isConnected;
793
+ r.frames = document.querySelectorAll("iframe, object, embed").length;`,
794
+ `<iframe src="${c}/markup.html?d=secret"></iframe>`,
795
+ ),
796
+ });
797
+ const verdict = await context.result(display, 15_000);
798
+ await settle(1_000);
799
+ expect(verdict.error, "the content's own code failed").toBeUndefined();
800
+ expect(verdict.frames, "probe: a frame that isn't the content's own is in the tree").toBe(0);
801
+ expect(verdict.blankKept, "probe: a frame with no document of its own was kept").toBe(false);
802
+ expect(canary.requests(), "probe: a frame reached the canary").toEqual([]);
803
+ expect(context.requestsTo(c), "probe: the page requested the canary").toEqual([]);
804
+ },
805
+ },
806
+ {
807
+ id: "4.own-turned",
808
+ item: 4,
809
+ title:
810
+ "a page's own frames, opted in (P128): a kept frame turned to another site leaves before it goes",
811
+ async run(context) {
812
+ const canary = await context.http();
813
+ const c = canary.origin;
814
+ const display = await context.launch({
815
+ config: inline({ nestedFrames: "own" }),
816
+ content: attack(`
817
+ const make = () => { const f = document.createElement("iframe"); f.srcdoc = "<p>kept</p>"; document.body.append(f); return f; };
818
+ const dropped = make();
819
+ const attribute = make();
820
+ const named = make();
821
+ r.kept = document.querySelectorAll("iframe").length;
822
+ // Its srcdoc wins while it has one: a src alone changes nothing.
823
+ dropped.src = ${js(`${c}/dropped.html?d=secret`)};
824
+ r.keptWithSrc = dropped.isConnected;
825
+ dropped.removeAttribute("srcdoc");
826
+ attribute.setAttribute("src", ${js(`${c}/attribute.html?d=secret`)});
827
+ attribute.attributes.removeNamedItem("srcdoc");
828
+ named.toggleAttribute("srcdoc");
829
+ named.setAttribute("src", ${js(`${c}/named.html?d=secret`)});
830
+ await wait(1200);
831
+ r.frames = document.querySelectorAll("iframe").length;`),
832
+ });
833
+ const verdict = await context.result(display, 15_000);
834
+ await settle(1_000);
835
+ expect(verdict.error, "the content's own code failed").toBeUndefined();
836
+ expect(verdict.kept, "the content's own srcdoc frames were kept").toBe(3);
837
+ expect(verdict.keptWithSrc, "a srcdoc frame given a src was kept").toBe(true);
838
+ expect(verdict.frames, "probe: a frame turned to another site is in the tree").toBe(0);
839
+ expect(canary.requests(), "probe: a turned frame reached the canary").toEqual([]);
840
+ expect(context.requestsTo(c), "probe: the page requested the canary").toEqual([]);
841
+ },
842
+ },
843
+ {
844
+ id: "4.own-default",
845
+ item: 4,
846
+ title:
847
+ 'no nested frame runs by default (P128): what nestedFrames "own" would keep is removed without it',
848
+ async run(context) {
849
+ const udp = await context.udp();
850
+ const child = childDocument(udp.stun).replace(/"/gu, "&quot;");
851
+ const display = await context.launch({
852
+ config: inline(),
853
+ content: attack(
854
+ `${childSetup(udp.stun)}
855
+ const made = created("iframe");
856
+ if (made) {
857
+ made.srcdoc = child;
858
+ document.body.append(made);
859
+ }
860
+ const relative = created("iframe");
861
+ if (relative) {
862
+ relative.src = "page.html";
863
+ document.body.append(relative);
864
+ }
865
+ await wait(1200);
866
+ r.frames = document.querySelectorAll("iframe").length;`,
867
+ `<iframe srcdoc="${child}"></iframe><iframe src="page.html"></iframe>`,
868
+ ),
869
+ });
870
+ await expectNoChild(context, display, udp);
871
+ },
872
+ },
873
+
754
874
  // ── 5: self-navigation ─────────────────────────────────────────────────────────────────────
755
875
  navigation("location", "location.href", (target) => `location.href = ${js(target)};`),
756
876
  navigation("replace", "location.replace", (target) => `location.replace(${js(target)});`),
@@ -917,11 +1037,11 @@ export const PROBES: readonly Probe[] = [
917
1037
  const img = document.createElement("img");
918
1038
  img.src = "relative.png?d=secret";
919
1039
  document.body.append(img);
920
- const object = document.createElement("object");
921
- object.data = ${js(`${c}/object.html`)};
922
- const embed = document.createElement("embed");
923
- embed.src = ${js(`${c}/embed.html`)};
924
- document.body.append(object, embed);
1040
+ const object = created("object");
1041
+ if (object) object.data = ${js(`${c}/object.html`)};
1042
+ const embed = created("embed");
1043
+ if (embed) embed.src = ${js(`${c}/embed.html`)};
1044
+ document.body.append(...[object, embed].filter((each) => each !== null));
925
1045
  await wait(500);
926
1046
  r.plugins = document.querySelectorAll("object, embed").length;`,
927
1047
  `<object data="${c}/static-object.html"></object><embed src="${c}/static-embed.swf">`,
@@ -935,6 +1055,7 @@ export const PROBES: readonly Probe[] = [
935
1055
  });
936
1056
  expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
937
1057
  expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
1058
+ noteRefused(context, verdict);
938
1059
  },
939
1060
  },
940
1061
 
@@ -1337,18 +1337,27 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1337
1337
  expect(again.status(), "probe: a used door ticket is 401 session").toBe(401);
1338
1338
 
1339
1339
  // (4) The door ticket at the content route, and the content ticket at the door, open
1340
- // nothing; (6) a fresh door framed from a foreign origin hears nothing (frame-ancestors).
1340
+ // nothing: the two tickets of one issue are not interchangeable. Each is swapped into the
1341
+ // other's own URL, each path kept as the host gave it (a host's door path need not end in
1342
+ // its content's key, P126); (6) a fresh door framed from a foreign origin hears nothing
1343
+ // (frame-ancestors).
1341
1344
  const fresh = await host.locate(await host.shell("door-cross"));
1342
- const freshDoor = new URL(doorOf(fresh));
1343
- const freshContent = new URL(fresh.url);
1344
- const key = freshDoor.pathname.split("/").at(-1) ?? "";
1345
- const doorTicket = freshDoor.searchParams.get("ticket") ?? "";
1346
- const contentTicket = freshContent.searchParams.get("ticket") ?? "";
1347
- const doorTicketAtContent = `${fresh.origin}/__porthole/d/${key}?ticket=${doorTicket}`;
1348
- const contentTicketAtDoor = `${fresh.origin}/__porthole/door/${key}?ticket=${contentTicket}`;
1345
+ const doorTicketAtContent = new URL(fresh.url);
1346
+ const contentTicketAtDoor = new URL(doorOf(fresh));
1347
+ const doorTicket = contentTicketAtDoor.searchParams.get("ticket");
1348
+ const contentTicket = doorTicketAtContent.searchParams.get("ticket");
1349
+ if (doorTicket === null || contentTicket === null) {
1350
+ info?.annotations.push({
1351
+ type: "measured",
1352
+ description:
1353
+ "the location's content or door URL carries no ticket query parameter: the swap presents none",
1354
+ });
1355
+ }
1356
+ doorTicketAtContent.searchParams.set("ticket", doorTicket ?? "");
1357
+ contentTicketAtDoor.searchParams.set("ticket", contentTicket ?? "");
1349
1358
  for (const [what, url] of [
1350
- ["the door ticket at the content route", doorTicketAtContent],
1351
- ["the content ticket at the door", contentTicketAtDoor],
1359
+ ["the door ticket at the content route", doorTicketAtContent.href],
1360
+ ["the content ticket at the door", contentTicketAtDoor.href],
1352
1361
  ] as const) {
1353
1362
  const response = await page.request.get(url, { failOnStatusCode: false });
1354
1363
  expect(response.status(), `probe: ${what} opens nothing`).toBe(401);
@@ -1470,12 +1479,32 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1470
1479
  link.rel = "stylesheet";
1471
1480
  link.href = each.style;
1472
1481
  document.head.append(link);
1473
- const nested = document.createElement("iframe");
1474
- nested.src = each.frame;
1475
- document.body.append(nested);
1482
+ // Refused at creation under the default config (P130): the frame can't exist.
1483
+ let nested: HTMLIFrameElement | null = null;
1484
+ try {
1485
+ nested = document.createElement("iframe");
1486
+ } catch (error) {
1487
+ if ((error as { name?: unknown } | null)?.name !== "NotSupportedError") {
1488
+ throw error;
1489
+ }
1490
+ }
1491
+ if (nested !== null) {
1492
+ nested.src = each.frame;
1493
+ document.body.append(nested);
1494
+ }
1476
1495
  await new Promise((resolve) => setTimeout(resolve, 800));
1477
- return { fetched, policy: policies.find((policy) => /connect-src/u.test(policy)) ?? "" };
1496
+ return {
1497
+ fetched,
1498
+ policy: policies.find((policy) => /connect-src/u.test(policy)) ?? "",
1499
+ frameRefused: nested === null,
1500
+ };
1478
1501
  }, urls);
1502
+ if (seen.frameRefused) {
1503
+ info?.annotations.push({
1504
+ type: "measured",
1505
+ description: "the nested frame was refused at creation",
1506
+ });
1507
+ }
1479
1508
  await page.waitForTimeout(SETTLE_MS);
1480
1509
  expect(seen.fetched, "probe: the fetch got out").toBe("blocked");
1481
1510
  expect(seen.policy, "probe: a CSP applied to the document").not.toBe("");
@@ -190,9 +190,17 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
190
190
  ? `The ${it}'s address is about:srcdoc: it has no query string or hash to read.`
191
191
  : `The ${it}'s address is its own (with Porthole's one-time ticket), never the app's: read no parameters from it.`,
192
192
  );
193
+ // A page's own frames (P128): what loads, as the shell keeps it; the rest is removed. By default
194
+ // the shell also refuses to make one (P130).
195
+ const frames =
196
+ config.nestedFrames !== "own"
197
+ ? "nested frames (iframe, object, embed) are removed, and making one in script throws"
198
+ : config.mode === "artifact" && config.isolation === "domain"
199
+ ? `an <iframe> of one of the ${it}'s own files (a relative src) or with srcdoc loads, set before it is added; other iframes, object, embed and frame are removed`
200
+ : "an <iframe> with srcdoc loads, set before it is added; other iframes, object, embed and frame are removed";
193
201
  add(
194
202
  "shell",
195
- `document.write and document.open throw; nested frames (iframe, object, embed) are removed; full screen and the clipboard are closed${globals.has("copyText") ? " (copy buttons call copyText)" : config.runtime !== undefined && declared.has("copyText") ? " (copy buttons call clipboard.copy)" : ""}.`,
203
+ `document.write and document.open throw; ${frames}; full screen and the clipboard are closed${globals.has("copyText") ? " (copy buttons call copyText)" : config.runtime !== undefined && declared.has("copyText") ? " (copy buttons call clipboard.copy)" : ""}.`,
196
204
  );
197
205
  add(
198
206
  "storage",
@@ -494,6 +494,28 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
494
494
  };
495
495
  };
496
496
 
497
+ // A frame's size is taken at most once an animation frame after its run's first, and only
498
+ // when it changed (P127): `resize` has no gate, and each one would reflow the host's page and
499
+ // tell its listeners.
500
+ let sizeFrame: number | null = null;
501
+ let pendingSize: DisplayEvents["resize"] | null = null;
502
+ let shownSize: DisplayEvents["resize"] | null = null;
503
+ const applySize = () => {
504
+ sizeFrame = null;
505
+ const size = pendingSize;
506
+ pendingSize = null;
507
+ if (
508
+ size === null ||
509
+ (shownSize !== null && size.height === shownSize.height && size.width === shownSize.width)
510
+ ) {
511
+ return;
512
+ }
513
+ shownSize = size;
514
+ height = size.height;
515
+ surface?.setHeight(size.height);
516
+ emit("resize", size);
517
+ };
518
+
497
519
  const onBridge = (event: BridgeEvent) => {
498
520
  switch (event.type) {
499
521
  case "resize": {
@@ -501,12 +523,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
501
523
  config.limits.maxHeightPx,
502
524
  Math.max(config.limits.minHeightPx, Math.ceil(event.height)),
503
525
  );
504
- height = next;
505
- surface?.setHeight(next);
506
- emit("resize", {
526
+ pendingSize = {
507
527
  height: next,
508
528
  ...(event.width === undefined ? {} : { width: event.width }),
509
- });
529
+ };
530
+ // A run's first size at once: until then its frame has no height of its own.
531
+ if (view === null || shownSize === null) {
532
+ applySize();
533
+ } else if (sizeFrame === null) {
534
+ sizeFrame = view.requestAnimationFrame(applySize);
535
+ }
510
536
  return;
511
537
  }
512
538
  case "navigationBlocked":
@@ -544,6 +570,13 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
544
570
  bridge?.close();
545
571
  bridge = null;
546
572
  handshaken = false;
573
+ // The next run's frame tells its own size, the same as this one's or not.
574
+ if (sizeFrame !== null) {
575
+ view?.cancelAnimationFrame(sizeFrame);
576
+ sizeFrame = null;
577
+ }
578
+ pendingSize = null;
579
+ shownSize = null;
547
580
  abort?.abort();
548
581
  abort = null;
549
582
  outcomeWatch?.stop();
package/src/index.ts CHANGED
@@ -197,6 +197,7 @@ export {
197
197
  assetCspDirectives,
198
198
  FILE_SET_DIRECTIVES,
199
199
  fileSetCspDirectives,
200
+ fileSetDirectives,
200
201
  INERT_FILE_CSP,
201
202
  type CspDirective,
202
203
  type EgressKind,
@@ -58,6 +58,12 @@ export interface PresetOptions {
58
58
  readonly runtime?: RuntimeVersion;
59
59
  /** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
60
60
  readonly nested?: true;
61
+ /**
62
+ * `own` (P128): an `<iframe>` of one of the page's own files (a relative `src`) or a `srcdoc`
63
+ * one loads and runs, in a realm of its own that the shell's hardening doesn't reach
64
+ * (`PortholeConfig.nestedFrames`). `none` (default): every nested frame is removed.
65
+ */
66
+ readonly nestedFrames?: "none" | "own";
61
67
  }
62
68
 
63
69
  /** What a live widget may say about a capability (P103): anything but origins of its own. */
@@ -244,6 +250,7 @@ function build(
244
250
  ...(options.errors === undefined ? {} : { errors: options.errors }),
245
251
  ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
246
252
  ...(options.nested === undefined ? {} : { nested: options.nested }),
253
+ ...(options.nestedFrames === undefined ? {} : { nestedFrames: options.nestedFrames }),
247
254
  });
248
255
  }
249
256
 
@@ -271,6 +278,14 @@ export const presets = {
271
278
  "a live widget has no network of its own: its egress stays closed (P079)",
272
279
  );
273
280
  }
281
+ // A child frame is a realm the shell's WebRTC removal never reached (P128): a network of its
282
+ // own, which a live widget never has.
283
+ if (options.nestedFrames === "own") {
284
+ throw new ConfigError(
285
+ "options.nestedFrames",
286
+ "a live widget has no network of its own: its frames stay removed (P079, P128)",
287
+ );
288
+ }
274
289
  // A capability's own origins join the CSP as egress does (P103): none for a live widget.
275
290
  for (const [name, value] of Object.entries((options as PresetOptions).capabilities ?? {})) {
276
291
  for (const field of ["connect", "resource"] as const) {
@@ -2,6 +2,7 @@ import type { CompiledConfig } from "../compile/compile.ts";
2
2
  import {
3
3
  assetCspDirectives,
4
4
  fileSetCspDirectives,
5
+ fileSetDirectives,
5
6
  INERT_FILE_CSP,
6
7
  servedDocumentCsp,
7
8
  servedPermissionsPolicy,
@@ -268,10 +269,15 @@ export async function serveFile(serving: FileServing): Promise<Response> {
268
269
  serving.compiled.config.capabilities.assets !== undefined
269
270
  ? "same-origin"
270
271
  : "no-referrer";
271
- // Its version's files (P082), and its artifact's assets where the config serves them (P089).
272
+ // Its version's files (P082), frames of them where the config opts in (P128), and its
273
+ // artifact's assets where the config serves them (P089).
272
274
  const directives = assetCspDirectives(
273
275
  serving.compiled.config,
274
- fileSetCspDirectives(serving.compiled.cspDirectives, serving.source),
276
+ fileSetCspDirectives(
277
+ serving.compiled.cspDirectives,
278
+ serving.source,
279
+ fileSetDirectives(serving.compiled.config),
280
+ ),
275
281
  serving.origin,
276
282
  );
277
283
  // A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
@@ -73,7 +73,8 @@ export { DOOR_PATH, FRAME_STATUS_METHOD } from "../isolation/types.ts";
73
73
  // A served display's door (P125): `/server` serves it for a shell, a page that isn't nested and the
74
74
  // sandbox proxy; a content Worker of a host's own answers the same at `DOOR_PATH<key>`, after
75
75
  // taking the door's own ticket (`TicketRecord.door`) and running the checks its content's address
76
- // runs (docs/ADOPTING.md, "The door").
76
+ // runs (docs/ADOPTING.md, "The door"). A host that signs its own tickets answers it with
77
+ // `PortholeServer.doorAnswer` once it has admitted the request itself (P126).
77
78
  export { doorResponse, doorStatusResponse, type DoorOptions } from "./pages.ts";
78
79
  // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
79
80
  // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a