@botiverse/porthole 0.12.0 → 0.14.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.
Files changed (94) hide show
  1. package/dist/annotate/types.d.ts +32 -3
  2. package/dist/annotate/types.js +4 -0
  3. package/dist/annotate/validate.js +19 -2
  4. package/dist/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.js +14 -10
  9. package/dist/check/lint.js +1 -1
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/scroll.d.ts +29 -13
  12. package/dist/check/scroll.js +74 -18
  13. package/dist/compile/policy.d.ts +7 -0
  14. package/dist/compile/policy.js +13 -1
  15. package/dist/config/capabilities.d.ts +16 -3
  16. package/dist/config/capabilities.js +1 -0
  17. package/dist/config/schema.d.ts +11 -0
  18. package/dist/config/validate.js +19 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/displays/displays.js +3 -1
  21. package/dist/guide/limits.js +1 -1
  22. package/dist/guide/runtime.js +1 -1
  23. package/dist/host/create-host.d.ts +2 -0
  24. package/dist/host/create-host.js +100 -3
  25. package/dist/host/pass-on.d.ts +15 -0
  26. package/dist/host/pass-on.js +65 -0
  27. package/dist/host/types.d.ts +37 -0
  28. package/dist/index.d.ts +5 -1
  29. package/dist/index.js +5 -1
  30. package/dist/isolation/types.d.ts +8 -0
  31. package/dist/isolation/types.js +8 -0
  32. package/dist/platform/focus-guard.d.ts +212 -0
  33. package/dist/platform/focus-guard.js +620 -0
  34. package/dist/platform/types.d.ts +25 -0
  35. package/dist/platform/web.js +80 -2
  36. package/dist/presets/presets.d.ts +2 -0
  37. package/dist/presets/presets.js +1 -0
  38. package/dist/react/frame.d.ts +8 -0
  39. package/dist/react/frame.js +4 -0
  40. package/dist/runtime/requests.js +34 -12
  41. package/dist/runtime/types.generated.js +1 -1
  42. package/dist/server/files.js +19 -3
  43. package/dist/server/index.d.ts +1 -0
  44. package/dist/server/index.js +4 -0
  45. package/dist/server/nested.d.ts +37 -0
  46. package/dist/server/nested.js +70 -0
  47. package/dist/server/server.js +57 -7
  48. package/dist/shell/annotate.d.ts +1 -1
  49. package/dist/shell/annotate.js +157 -7
  50. package/dist/shell/frame.d.ts +45 -0
  51. package/dist/shell/frame.js +250 -0
  52. package/dist/shell/plan.js +2 -1
  53. package/dist/shell/runtime.js +49 -14
  54. package/docs/ADOPTING.md +140 -7
  55. package/docs/ARCHITECTURE.md +23 -0
  56. package/docs/DECISIONS.md +564 -5
  57. package/docs/DESIGN.md +18 -2
  58. package/docs/THREAT_MODEL.md +192 -30
  59. package/package.json +1 -1
  60. package/src/annotate/types.ts +28 -3
  61. package/src/annotate/validate.ts +23 -2
  62. package/src/bridge/bridge.ts +17 -1
  63. package/src/bridge/unseen.ts +24 -0
  64. package/src/check/files.ts +14 -10
  65. package/src/check/lint.ts +1 -1
  66. package/src/check/scroll.ts +106 -38
  67. package/src/compile/policy.ts +14 -1
  68. package/src/config/capabilities.ts +16 -3
  69. package/src/config/schema.ts +11 -0
  70. package/src/config/validate.ts +23 -0
  71. package/src/displays/displays.ts +3 -1
  72. package/src/guide/limits.ts +1 -1
  73. package/src/guide/runtime.ts +1 -1
  74. package/src/host/create-host.ts +105 -4
  75. package/src/host/pass-on.ts +73 -0
  76. package/src/host/types.ts +33 -0
  77. package/src/index.ts +5 -1
  78. package/src/isolation/types.ts +12 -0
  79. package/src/platform/focus-guard.ts +815 -0
  80. package/src/platform/types.ts +24 -0
  81. package/src/platform/web.ts +96 -2
  82. package/src/presets/presets.ts +3 -0
  83. package/src/react/frame.tsx +10 -0
  84. package/src/runtime/requests.ts +36 -14
  85. package/src/runtime/types.generated.ts +1 -1
  86. package/src/server/files.ts +19 -3
  87. package/src/server/index.ts +10 -0
  88. package/src/server/nested.ts +86 -0
  89. package/src/server/server.ts +65 -6
  90. package/src/shell/annotate.ts +157 -7
  91. package/src/shell/frame.ts +268 -0
  92. package/src/shell/plan.ts +2 -1
  93. package/src/shell/runtime.ts +49 -14
  94. package/types/runtime/v1/comments.d.ts +8 -4
@@ -12,7 +12,9 @@ import { attributesOf } from "./markup.ts";
12
12
  * - body with overflow-y hidden or clip, where html's overflow is visible (body's then becomes the
13
13
  * viewport's) or body is one screen tall;
14
14
  * - the root with overflow-y hidden or clip and one screen tall;
15
- * - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing);
15
+ * - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing), and
16
+ * body fixed whatever its height, unless it scrolls itself (where html's overflow is visible,
17
+ * body's is the viewport's and body itself doesn't: P110);
16
18
  * and nothing in the page's markup below body that scrolls itself: no element there with style=""
17
19
  * or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
18
20
  * that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
@@ -28,7 +30,8 @@ import { attributesOf } from "./markup.ts";
28
30
  * and bottom set (`inset: 0`).
29
31
  *
30
32
  * What it reads: the page's `<style>` elements, the stylesheets it links that the caller finds
31
- * (a version's own files) and what they `@import`, in document order; style="" on the three; the
33
+ * (a version's own files) and what they `@import`, in document order; style="" on body and the
34
+ * root (not html's: the shell drops it, P110); the
32
35
  * class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
33
36
  * Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
34
37
  * order, !important and cascade layers decide between rules, so a later override is seen.
@@ -43,7 +46,8 @@ import { attributesOf } from "./markup.ts";
43
46
  *
44
47
  * Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
45
48
  * rule it is in, a rule's selectors one at a time), at most `SHEETS` of them and `READ` bytes in
46
- * all, its own `<style>` included; past that, the rest isn't read. At most `MOST_LAYERS` layers a
49
+ * all, its own `<style>` included; past that, the rest isn't read, nor asked for, and a sheet is
50
+ * decoded only once its size is taken (P110). At most `MOST_LAYERS` layers a
47
51
  * page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
48
52
  * element keeps, per property, only each layer's winner so far, and a compound is matched against
49
53
  * an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
@@ -57,19 +61,25 @@ import { attributesOf } from "./markup.ts";
57
61
  * selector).
58
62
  */
59
63
 
60
- /** A stylesheet the page links, as the caller finds it from `from` (a path), or null. */
64
+ /**
65
+ * A stylesheet the page links, as the caller finds it from `from` (a path), or null: its path, the
66
+ * fewest characters it may hold (`least`: a string's length; as bytes, a third of them, less a
67
+ * BOM's), and its text (at least its first `SCANNED` characters), decoded only where the rule may
68
+ * read it (P110: one page linking 400 sheets decoded and kept all of them, though the rule reads at
69
+ * most `SHEETS`, `READ` characters in all).
70
+ */
61
71
  export type LinkedSheet = (
62
72
  href: string,
63
73
  from: string,
64
- ) => { readonly path: string; readonly text: string } | null;
74
+ ) => { readonly path: string; readonly least: number; readonly text: () => string } | null;
65
75
 
66
76
  export interface ScrollLock {
67
77
  /** What to change, for the agent. */
68
78
  readonly message: string;
69
79
  /** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
70
80
  readonly path?: string;
71
- /** Its line (1-based). */
72
- readonly line: number;
81
+ /** Its line (1-based); none where the page couldn't be checked (P110). */
82
+ readonly line?: number;
73
83
  }
74
84
 
75
85
  /** How much of one stylesheet is read: its first 2 MiB. */
@@ -575,7 +585,11 @@ function identAt(text: string, at: number): { value: string; end: number } | nul
575
585
  if (code === "\\") {
576
586
  const hex = /^[0-9a-f]{1,6}\s?/iu.exec(text.slice(index + 1, index + 8));
577
587
  if (hex !== null) {
578
- value += String.fromCodePoint(Number.parseInt(hex[0].trim(), 16) || 0xfffd);
588
+ // CSS Syntax's "consume an escaped code point": 0, a surrogate or past U+10FFFF is U+FFFD
589
+ // (six hex digits reach 0xFFFFFF, which String.fromCodePoint throws on: P110).
590
+ const point = Number.parseInt(hex[0].trim(), 16);
591
+ const valid = point !== 0 && point <= 0x10ffff && (point < 0xd800 || point > 0xdfff);
592
+ value += String.fromCodePoint(valid ? point : 0xfffd);
579
593
  index += 1 + hex[0].length;
580
594
  } else if (index + 1 < text.length) {
581
595
  value += text[index + 1];
@@ -875,8 +889,8 @@ const tooDeep = (name: string): string | null => {
875
889
  return null;
876
890
  };
877
891
 
878
- /** A stylesheet found for the page, once: its path and text. */
879
- type Found = { readonly path: string; readonly text: string } | null;
892
+ /** A stylesheet found for the page, once: its path, its fewest characters, its text when read. */
893
+ type Found = ReturnType<LinkedSheet>;
880
894
 
881
895
  /** The cascade over the chain: each declaration that matches, then the one that wins. */
882
896
  class Cascade {
@@ -979,18 +993,39 @@ class Cascade {
979
993
  return true;
980
994
  }
981
995
 
982
- /** Whether a stylesheet may still be read for this page (once, within the budget). */
983
- take(found: Found): found is { path: string; text: string } {
996
+ /**
997
+ * Whether nothing more may be read for this page: `SHEETS` read, `READ` spent, or the version's
998
+ * budget. Then no sheet is asked for (P110).
999
+ */
1000
+ full(): boolean {
1001
+ return this.read.size >= SHEETS || this.bytes >= READ || this.budget.spent;
1002
+ }
1003
+
1004
+ /**
1005
+ * A stylesheet's first `SCANNED` characters, if it may still be read for this page (once, within
1006
+ * the budget), else null. The caps count characters, whatever the caller gives: where even its
1007
+ * fewest are past what's left, it is refused before it is decoded (past the version's budget,
1008
+ * spent); else it is decoded, cut, and charged what it holds, or dropped if that doesn't fit.
1009
+ */
1010
+ take(found: Found): string | null {
984
1011
  if (found === null || this.read.has(found.path) || this.read.size >= SHEETS) {
985
- return false;
1012
+ return null;
986
1013
  }
987
- const size = Math.min(found.text.length, SCANNED);
988
- if (this.bytes + size > READ || !this.spend(size)) {
989
- return false;
1014
+ const least = Math.min(found.least, SCANNED);
1015
+ if (this.bytes + least > READ) {
1016
+ return null;
1017
+ }
1018
+ if (this.budget.spent || least > this.budget.bytes) {
1019
+ this.budget.spent = true;
1020
+ return null;
1021
+ }
1022
+ const text = found.text().slice(0, SCANNED);
1023
+ if (this.bytes + text.length > READ || !this.spend(text.length)) {
1024
+ return null;
990
1025
  }
991
1026
  this.read.add(found.path);
992
- this.bytes += size;
993
- return true;
1027
+ this.bytes += text.length;
1028
+ return text;
994
1029
  }
995
1030
 
996
1031
  /**
@@ -1146,12 +1181,19 @@ class Cascade {
1146
1181
  take(to);
1147
1182
  }
1148
1183
 
1149
- /** A stylesheet the page links or a sheet imports, if it may still be read. */
1150
- file(found: Found, layer: string | null) {
1151
- if (!this.take(found)) {
1184
+ /**
1185
+ * A stylesheet the page links or a sheet imports (`href`, from `from`), if it may still be read:
1186
+ * asked for only while the page may read more, decoded only once taken.
1187
+ */
1188
+ file(href: string, from: string, layer: string | null) {
1189
+ if (this.full()) {
1190
+ return;
1191
+ }
1192
+ const found = this.find(href, from);
1193
+ const text = this.take(found);
1194
+ if (found === null || text === null) {
1152
1195
  return;
1153
1196
  }
1154
- const text = found.text.slice(0, SCANNED);
1155
1197
  this.sheet(withoutComments(text), 0, text.length, {
1156
1198
  source: { path: found.path, text },
1157
1199
  base: 0,
@@ -1311,7 +1353,7 @@ class Cascade {
1311
1353
  return;
1312
1354
  }
1313
1355
  }
1314
- this.file(this.find(href, context.from), layer);
1356
+ this.file(href, context.from, layer);
1315
1357
  }
1316
1358
  }
1317
1359
 
@@ -1362,20 +1404,33 @@ interface Hold {
1362
1404
  readonly at: Value;
1363
1405
  }
1364
1406
 
1407
+ interface ScrollOptions {
1408
+ readonly noun: string;
1409
+ readonly path?: string;
1410
+ readonly sheet?: LinkedSheet;
1411
+ /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
1412
+ readonly budget?: ScrollBudget;
1413
+ }
1414
+
1365
1415
  /**
1366
1416
  * Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
1367
1417
  * don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
1418
+ * Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
1419
+ * line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
1420
+ * `admitFiles` in 0.11).
1368
1421
  */
1369
- export function scrollLock(
1370
- page: string,
1371
- options: {
1372
- readonly noun: string;
1373
- readonly path?: string;
1374
- readonly sheet?: LinkedSheet;
1375
- /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
1376
- readonly budget?: ScrollBudget;
1377
- },
1378
- ): ScrollLock | null {
1422
+ export function scrollLock(page: string, options: ScrollOptions): ScrollLock | null {
1423
+ try {
1424
+ return readScrollLock(page, options);
1425
+ } catch {
1426
+ return {
1427
+ message: `The ${options.noun} wasn't checked for scroll lock: its styles couldn't be read. If it holds html, body or its root to one screen (overflow: hidden with height: 100% or 100vh, or position: fixed), let it scroll as a document.`,
1428
+ ...(options.path === undefined ? {} : { path: options.path }),
1429
+ };
1430
+ }
1431
+ }
1432
+
1433
+ function readScrollLock(page: string, options: ScrollOptions): ScrollLock | null {
1379
1434
  const shared = options.budget ?? { bytes: Infinity, steps: Infinity, spent: false };
1380
1435
  if (shared.spent) {
1381
1436
  return null;
@@ -1400,7 +1455,9 @@ export function scrollLock(
1400
1455
  };
1401
1456
  };
1402
1457
  const chain: Node[] = [
1403
- nodeOf(scanned.html, "html", "html", false),
1458
+ // Not html's style="": the shell imports a page's html attributes but that one
1459
+ // (`renderDocument`), so it never applies in Porthole's frame (P110).
1460
+ { ...nodeOf(scanned.html, "html", "html", false), style: null },
1404
1461
  nodeOf(scanned.body, "body", "body", false),
1405
1462
  ];
1406
1463
  const rootTag =
@@ -1461,7 +1518,7 @@ export function scrollLock(
1461
1518
  ) {
1462
1519
  continue;
1463
1520
  }
1464
- cascade.file(find(href, from), null);
1521
+ cascade.file(href, from, null);
1465
1522
  }
1466
1523
  for (const node of chain) {
1467
1524
  if (node.style !== null) {
@@ -1604,7 +1661,10 @@ export function scrollLock(
1604
1661
  }
1605
1662
  const height = tall("height");
1606
1663
  const maxHeight = tall("max-height");
1607
- if (positioned && position !== undefined && (spanned || height || maxHeight)) {
1664
+ // A fixed body holds the page whatever its height (P110): a fixed box adds nothing to what the
1665
+ // frame scrolls, so `body { position: fixed; top: 0 }`, the scroll-lock libraries' way, does.
1666
+ const fixedBody = index === 1 && position?.value === "fixed";
1667
+ if (positioned && position !== undefined && (spanned || height || maxHeight || fixedBody)) {
1608
1668
  shown.unshift(position);
1609
1669
  }
1610
1670
  states.push({ screen: height || maxHeight || spanned, shown, position: position?.value ?? "" });
@@ -1628,11 +1688,16 @@ export function scrollLock(
1628
1688
  return found !== undefined && !CONTENT_HEIGHT.test(found) && !PARENT.test(found);
1629
1689
  });
1630
1690
  };
1691
+ // An element's own overflow-y: body's is the viewport's where html's overflow is visible, and
1692
+ // body's own is then visible (P110: `body { position: fixed; inset: 0; overflow: auto }` doesn't
1693
+ // scroll itself, the viewport takes its auto).
1694
+ const ownOverflowY = (index: number, node: Node): string =>
1695
+ index === 1 && htmlVisible ? "visible" : overflowY(node);
1631
1696
  const scrollBox = (index: number): boolean => {
1632
1697
  const node = chain[index];
1633
1698
  return (
1634
1699
  node !== undefined &&
1635
- SCROLLS.has(overflowY(node)) &&
1700
+ SCROLLS.has(ownOverflowY(index, node)) &&
1636
1701
  ((states[index]?.screen ?? false) || unread(index))
1637
1702
  );
1638
1703
  };
@@ -1649,7 +1714,10 @@ export function scrollLock(
1649
1714
  const overflow = value(node, "overflow-y");
1650
1715
  const clipped =
1651
1716
  clips && (index === 0 ? true : index === 1 ? state.screen || htmlVisible : state.screen);
1652
- const fixed = state.position === "fixed" && state.screen && !SCROLLS.has(overflowY(node));
1717
+ const fixed =
1718
+ state.position === "fixed" &&
1719
+ (state.screen || index === 1) &&
1720
+ !SCROLLS.has(ownOverflowY(index, node));
1653
1721
  if (!clipped && !fixed) {
1654
1722
  continue;
1655
1723
  }
@@ -217,6 +217,8 @@ export function sandboxTokens(config: PortholeConfig): string[] {
217
217
  case "opaque":
218
218
  return ["allow-scripts"];
219
219
  case "domain":
220
+ // Nested (P111), this frame holds Porthole's shell, on the content origin, and the page is
221
+ // the shell's child (`PAGE_SANDBOX_TOKENS`).
220
222
  return ["allow-scripts", "allow-same-origin"];
221
223
  case "external":
222
224
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -235,9 +237,20 @@ export function sandboxTokens(config: PortholeConfig): string[] {
235
237
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
236
238
  */
237
239
  export function servedSandboxDirective(config: PortholeConfig): CspDirective | null {
238
- return config.isolation === "domain" ? ["sandbox", ...sandboxTokens(config)] : null;
240
+ if (config.isolation !== "domain") {
241
+ return null;
242
+ }
243
+ return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
239
244
  }
240
245
 
246
+ /**
247
+ * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
248
+ * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
249
+ * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
250
+ * so the shell's realm (a test holds every sandbox Porthole writes to this).
251
+ */
252
+ export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
253
+
241
254
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
242
255
  export function servedDocumentCsp(
243
256
  config: PortholeConfig,
@@ -45,9 +45,14 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
45
45
  /**
46
46
  * What must hold before a call reaches the host's handler. A capability's gates all apply.
47
47
  *
48
- * - `user-activation`: the call follows a real user gesture in the frame. The shell refuses a call
49
- * without one, and the host checks its own page's activation (which a gesture in a child frame
50
- * propagates to). It stops calls made on load or on a timer; it is not proof of intent.
48
+ * - `user-activation`: the call follows a real user gesture. The shell refuses a call without one
49
+ * in its frame, but that check is the page's own (a page posts the call itself and skips it).
50
+ * The host checks its own page's transient activation, which a gesture in a child frame
51
+ * propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
52
+ * the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
53
+ * load, or on a timer while nobody does anything; it is not proof that the gesture was in this
54
+ * frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
55
+ * the person's composer), the host also asks that its page's focus be in the calling frame.
51
56
  * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
52
57
  * goes only if they accept. No `confirm` function means the call is refused (fail closed).
53
58
  * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
@@ -82,6 +87,13 @@ export interface CapabilitySpec {
82
87
  * Absent for what the shell does by itself (sizes, errors, annotations).
83
88
  */
84
89
  readonly request?: { readonly method: string; readonly sdk?: string };
90
+ /**
91
+ * Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
92
+ * focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
93
+ * a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
94
+ * typing in its own composer included.
95
+ */
96
+ readonly inFrame?: true;
85
97
  }
86
98
 
87
99
  const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
@@ -170,6 +182,7 @@ export const CAPABILITIES = {
170
182
  defaultGates: ["user-activation", rate(30)],
171
183
  served: "handler",
172
184
  request: { method: "porthole/call" },
185
+ inFrame: true,
173
186
  },
174
187
  /** This artifact's current version, and a new version of it, base-checked (P088). */
175
188
  artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
@@ -258,6 +258,17 @@ export interface PortholeConfig {
258
258
  * `db`). Absent: 0.6's frames, globals and manual, exactly.
259
259
  */
260
260
  readonly runtime?: RuntimeVersion;
261
+ /**
262
+ * Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
263
+ * alone, a document of Porthole's own with no content in it, and the page runs in a child frame
264
+ * of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
265
+ * origin at its files' sealed address. The shell is then a realm the page can't reach, above the
266
+ * page's frame: it relays the page's messages, and tells the host when its own transient
267
+ * activation turns on (a press in the page activates its ancestors only), which is how the host
268
+ * knows the person, not the page, moved the keyboard into the frame or opened a comment. The
269
+ * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
270
+ */
271
+ readonly nested?: true;
261
272
  }
262
273
 
263
274
  export interface StorageConfig {
@@ -324,6 +324,7 @@ export function validateConfig(
324
324
  "storage",
325
325
  "errors",
326
326
  "runtime",
327
+ "nested",
327
328
  ],
328
329
  "config",
329
330
  );
@@ -687,6 +688,28 @@ export function validateConfig(
687
688
  }
688
689
  }
689
690
 
691
+ if (config.nested !== undefined) {
692
+ if (config.nested !== true) {
693
+ fail("config.nested", "must be true, or left out");
694
+ }
695
+ if (config.isolation !== "domain" || config.mode !== "artifact") {
696
+ fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
697
+ }
698
+ // The page's origin is opaque (P111): nothing of the content origin's own is its.
699
+ if (config.storage !== undefined) {
700
+ fail("config.nested", "a nested page keeps no storage: drop config.storage");
701
+ }
702
+ if (capabilities.assets !== undefined) {
703
+ fail(
704
+ "config.nested",
705
+ "a nested page can't load its asset library (/_blob/) yet: drop assets",
706
+ );
707
+ }
708
+ if (isObject(config.egress) && config.egress.libraries === true) {
709
+ fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
710
+ }
711
+ }
712
+
690
713
  if (config.errors !== undefined) {
691
714
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
692
715
  fail("config.errors", 'must be "agent", "host" or "none"');
@@ -93,9 +93,11 @@ export function defineDisplays<N extends string>(
93
93
  return presets.url({ ...kind.options, contentOrigins: [source] });
94
94
  }
95
95
  const options = kind.options ?? {};
96
+ // Nesting (P111) is a served page's: an opaque frame has nothing to nest.
97
+ const { nested: _nested, ...opaque } = options;
96
98
  return presets[kind.preset](
97
99
  source === null
98
- ? options
100
+ ? opaque
99
101
  : { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] },
100
102
  );
101
103
  };
@@ -196,7 +196,7 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
196
196
  );
197
197
  add(
198
198
  "storage",
199
- config.isolation === "opaque"
199
+ config.isolation === "opaque" || config.nested === true
200
200
  ? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
201
201
  : config.storage?.scope !== undefined
202
202
  ? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
61
61
  const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
62
62
  user: () => "who is viewing: { id, name, level }, as the app says",
63
63
  comments: () =>
64
- "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width, bidi or tag characters; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
64
+ "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
65
65
  copyText: () =>
66
66
  `copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
67
67
  openLink: () =>