@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
@@ -10,7 +10,9 @@
10
10
  * - body with overflow-y hidden or clip, where html's overflow is visible (body's then becomes the
11
11
  * viewport's) or body is one screen tall;
12
12
  * - the root with overflow-y hidden or clip and one screen tall;
13
- * - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing);
13
+ * - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing), and
14
+ * body fixed whatever its height, unless it scrolls itself (where html's overflow is visible,
15
+ * body's is the viewport's and body itself doesn't: P110);
14
16
  * and nothing in the page's markup below body that scrolls itself: no element there with style=""
15
17
  * or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
16
18
  * that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
@@ -26,7 +28,8 @@
26
28
  * and bottom set (`inset: 0`).
27
29
  *
28
30
  * What it reads: the page's `<style>` elements, the stylesheets it links that the caller finds
29
- * (a version's own files) and what they `@import`, in document order; style="" on the three; the
31
+ * (a version's own files) and what they `@import`, in document order; style="" on body and the
32
+ * root (not html's: the shell drops it, P110); the
30
33
  * class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
31
34
  * Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
32
35
  * order, !important and cascade layers decide between rules, so a later override is seen.
@@ -41,7 +44,8 @@
41
44
  *
42
45
  * Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
43
46
  * rule it is in, a rule's selectors one at a time), at most `SHEETS` of them and `READ` bytes in
44
- * all, its own `<style>` included; past that, the rest isn't read. At most `MOST_LAYERS` layers a
47
+ * all, its own `<style>` included; past that, the rest isn't read, nor asked for, and a sheet is
48
+ * decoded only once its size is taken (P110). At most `MOST_LAYERS` layers a
45
49
  * page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
46
50
  * element keeps, per property, only each layer's winner so far, and a compound is matched against
47
51
  * an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
@@ -54,18 +58,25 @@
54
58
  * HTML doesn't have; the fix is then !important where the name has less specificity than the
55
59
  * selector).
56
60
  */
57
- /** A stylesheet the page links, as the caller finds it from `from` (a path), or null. */
61
+ /**
62
+ * A stylesheet the page links, as the caller finds it from `from` (a path), or null: its path, the
63
+ * fewest characters it may hold (`least`: a string's length; as bytes, a third of them, less a
64
+ * BOM's), and its text (at least its first `SCANNED` characters), decoded only where the rule may
65
+ * read it (P110: one page linking 400 sheets decoded and kept all of them, though the rule reads at
66
+ * most `SHEETS`, `READ` characters in all).
67
+ */
58
68
  export type LinkedSheet = (href: string, from: string) => {
59
69
  readonly path: string;
60
- readonly text: string;
70
+ readonly least: number;
71
+ readonly text: () => string;
61
72
  } | null;
62
73
  export interface ScrollLock {
63
74
  /** What to change, for the agent. */
64
75
  readonly message: string;
65
76
  /** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
66
77
  readonly path?: string;
67
- /** Its line (1-based). */
68
- readonly line: number;
78
+ /** Its line (1-based); none where the page couldn't be checked (P110). */
79
+ readonly line?: number;
69
80
  }
70
81
  /** The most stylesheets read for one page, each once. */
71
82
  export declare const SHEETS = 32;
@@ -87,14 +98,19 @@ export interface ScrollBudget {
87
98
  }
88
99
  /** A version's budget, for one `lintFiles`. */
89
100
  export declare const scrollBudget: () => ScrollBudget;
90
- /**
91
- * Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
92
- * don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
93
- */
94
- export declare function scrollLock(page: string, options: {
101
+ interface ScrollOptions {
95
102
  readonly noun: string;
96
103
  readonly path?: string;
97
104
  readonly sheet?: LinkedSheet;
98
105
  /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
99
106
  readonly budget?: ScrollBudget;
100
- }): ScrollLock | null;
107
+ }
108
+ /**
109
+ * Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
110
+ * don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
111
+ * Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
112
+ * line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
113
+ * `admitFiles` in 0.11).
114
+ */
115
+ export declare function scrollLock(page: string, options: ScrollOptions): ScrollLock | null;
116
+ export {};
@@ -394,7 +394,11 @@ function identAt(text, at) {
394
394
  if (code === "\\") {
395
395
  const hex = /^[0-9a-f]{1,6}\s?/iu.exec(text.slice(index + 1, index + 8));
396
396
  if (hex !== null) {
397
- value += String.fromCodePoint(Number.parseInt(hex[0].trim(), 16) || 0xfffd);
397
+ // CSS Syntax's "consume an escaped code point": 0, a surrogate or past U+10FFFF is U+FFFD
398
+ // (six hex digits reach 0xFFFFFF, which String.fromCodePoint throws on: P110).
399
+ const point = Number.parseInt(hex[0].trim(), 16);
400
+ const valid = point !== 0 && point <= 0x10ffff && (point < 0xd800 || point > 0xdfff);
401
+ value += String.fromCodePoint(valid ? point : 0xfffd);
398
402
  index += 1 + hex[0].length;
399
403
  }
400
404
  else if (index + 1 < text.length) {
@@ -775,18 +779,38 @@ class Cascade {
775
779
  this.bytes += size;
776
780
  return true;
777
781
  }
778
- /** Whether a stylesheet may still be read for this page (once, within the budget). */
782
+ /**
783
+ * Whether nothing more may be read for this page: `SHEETS` read, `READ` spent, or the version's
784
+ * budget. Then no sheet is asked for (P110).
785
+ */
786
+ full() {
787
+ return this.read.size >= SHEETS || this.bytes >= READ || this.budget.spent;
788
+ }
789
+ /**
790
+ * A stylesheet's first `SCANNED` characters, if it may still be read for this page (once, within
791
+ * the budget), else null. The caps count characters, whatever the caller gives: where even its
792
+ * fewest are past what's left, it is refused before it is decoded (past the version's budget,
793
+ * spent); else it is decoded, cut, and charged what it holds, or dropped if that doesn't fit.
794
+ */
779
795
  take(found) {
780
796
  if (found === null || this.read.has(found.path) || this.read.size >= SHEETS) {
781
- return false;
797
+ return null;
782
798
  }
783
- const size = Math.min(found.text.length, SCANNED);
784
- if (this.bytes + size > READ || !this.spend(size)) {
785
- return false;
799
+ const least = Math.min(found.least, SCANNED);
800
+ if (this.bytes + least > READ) {
801
+ return null;
802
+ }
803
+ if (this.budget.spent || least > this.budget.bytes) {
804
+ this.budget.spent = true;
805
+ return null;
806
+ }
807
+ const text = found.text().slice(0, SCANNED);
808
+ if (this.bytes + text.length > READ || !this.spend(text.length)) {
809
+ return null;
786
810
  }
787
811
  this.read.add(found.path);
788
- this.bytes += size;
789
- return true;
812
+ this.bytes += text.length;
813
+ return text;
790
814
  }
791
815
  /**
792
816
  * A declaration for `node`, kept where it wins so far within its layer (and !important,
@@ -910,12 +934,19 @@ class Cascade {
910
934
  }
911
935
  take(to);
912
936
  }
913
- /** A stylesheet the page links or a sheet imports, if it may still be read. */
914
- file(found, layer) {
915
- if (!this.take(found)) {
937
+ /**
938
+ * A stylesheet the page links or a sheet imports (`href`, from `from`), if it may still be read:
939
+ * asked for only while the page may read more, decoded only once taken.
940
+ */
941
+ file(href, from, layer) {
942
+ if (this.full()) {
943
+ return;
944
+ }
945
+ const found = this.find(href, from);
946
+ const text = this.take(found);
947
+ if (found === null || text === null) {
916
948
  return;
917
949
  }
918
- const text = found.text.slice(0, SCANNED);
919
950
  this.sheet(withoutComments(text), 0, text.length, {
920
951
  source: { path: found.path, text },
921
952
  base: 0,
@@ -1051,7 +1082,7 @@ class Cascade {
1051
1082
  return;
1052
1083
  }
1053
1084
  }
1054
- this.file(this.find(href, context.from), layer);
1085
+ this.file(href, context.from, layer);
1055
1086
  }
1056
1087
  }
1057
1088
  /** A value of a shape the check knows, as the agent may be told it; else its property alone. */
@@ -1092,8 +1123,22 @@ const lineOf = (text, index) => {
1092
1123
  /**
1093
1124
  * Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
1094
1125
  * don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
1126
+ * Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
1127
+ * line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
1128
+ * `admitFiles` in 0.11).
1095
1129
  */
1096
1130
  export function scrollLock(page, options) {
1131
+ try {
1132
+ return readScrollLock(page, options);
1133
+ }
1134
+ catch {
1135
+ return {
1136
+ 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.`,
1137
+ ...(options.path === undefined ? {} : { path: options.path }),
1138
+ };
1139
+ }
1140
+ }
1141
+ function readScrollLock(page, options) {
1097
1142
  const shared = options.budget ?? { bytes: Infinity, steps: Infinity, spent: false };
1098
1143
  if (shared.spent) {
1099
1144
  return null;
@@ -1117,7 +1162,9 @@ export function scrollLock(page, options) {
1117
1162
  };
1118
1163
  };
1119
1164
  const chain = [
1120
- nodeOf(scanned.html, "html", "html", false),
1165
+ // Not html's style="": the shell imports a page's html attributes but that one
1166
+ // (`renderDocument`), so it never applies in Porthole's frame (P110).
1167
+ { ...nodeOf(scanned.html, "html", "html", false), style: null },
1121
1168
  nodeOf(scanned.body, "body", "body", false),
1122
1169
  ];
1123
1170
  const rootTag = scanned.body !== null && scanned.contentCount === 1 ? scanned.content[0] : undefined;
@@ -1174,7 +1221,7 @@ export function scrollLock(page, options) {
1174
1221
  href === "") {
1175
1222
  continue;
1176
1223
  }
1177
- cascade.file(find(href, from), null);
1224
+ cascade.file(href, from, null);
1178
1225
  }
1179
1226
  for (const node of chain) {
1180
1227
  if (node.style !== null) {
@@ -1288,7 +1335,10 @@ export function scrollLock(page, options) {
1288
1335
  }
1289
1336
  const height = tall("height");
1290
1337
  const maxHeight = tall("max-height");
1291
- if (positioned && position !== undefined && (spanned || height || maxHeight)) {
1338
+ // A fixed body holds the page whatever its height (P110): a fixed box adds nothing to what the
1339
+ // frame scrolls, so `body { position: fixed; top: 0 }`, the scroll-lock libraries' way, does.
1340
+ const fixedBody = index === 1 && position?.value === "fixed";
1341
+ if (positioned && position !== undefined && (spanned || height || maxHeight || fixedBody)) {
1292
1342
  shown.unshift(position);
1293
1343
  }
1294
1344
  states.push({ screen: height || maxHeight || spanned, shown, position: position?.value ?? "" });
@@ -1312,10 +1362,14 @@ export function scrollLock(page, options) {
1312
1362
  return found !== undefined && !CONTENT_HEIGHT.test(found) && !PARENT.test(found);
1313
1363
  });
1314
1364
  };
1365
+ // An element's own overflow-y: body's is the viewport's where html's overflow is visible, and
1366
+ // body's own is then visible (P110: `body { position: fixed; inset: 0; overflow: auto }` doesn't
1367
+ // scroll itself, the viewport takes its auto).
1368
+ const ownOverflowY = (index, node) => index === 1 && htmlVisible ? "visible" : overflowY(node);
1315
1369
  const scrollBox = (index) => {
1316
1370
  const node = chain[index];
1317
1371
  return (node !== undefined &&
1318
- SCROLLS.has(overflowY(node)) &&
1372
+ SCROLLS.has(ownOverflowY(index, node)) &&
1319
1373
  ((states[index]?.screen ?? false) || unread(index)));
1320
1374
  };
1321
1375
  const holds = [];
@@ -1330,7 +1384,9 @@ export function scrollLock(page, options) {
1330
1384
  const clips = CLIPS.has(overflowY(node));
1331
1385
  const overflow = value(node, "overflow-y");
1332
1386
  const clipped = clips && (index === 0 ? true : index === 1 ? state.screen || htmlVisible : state.screen);
1333
- const fixed = state.position === "fixed" && state.screen && !SCROLLS.has(overflowY(node));
1387
+ const fixed = state.position === "fixed" &&
1388
+ (state.screen || index === 1) &&
1389
+ !SCROLLS.has(ownOverflowY(index, node));
1334
1390
  if (!clipped && !fixed) {
1335
1391
  continue;
1336
1392
  }
@@ -85,6 +85,13 @@ export declare function sandboxTokens(config: PortholeConfig): string[];
85
85
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
86
86
  */
87
87
  export declare function servedSandboxDirective(config: PortholeConfig): CspDirective | null;
88
+ /**
89
+ * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
90
+ * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
91
+ * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
92
+ * so the shell's realm (a test holds every sandbox Porthole writes to this).
93
+ */
94
+ export declare const PAGE_SANDBOX_TOKENS: readonly string[];
88
95
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
89
96
  export declare function servedDocumentCsp(config: PortholeConfig, directives: readonly CspDirective[]): string;
90
97
  /**
@@ -173,6 +173,8 @@ export function sandboxTokens(config) {
173
173
  case "opaque":
174
174
  return ["allow-scripts"];
175
175
  case "domain":
176
+ // Nested (P111), this frame holds Porthole's shell, on the content origin, and the page is
177
+ // the shell's child (`PAGE_SANDBOX_TOKENS`).
176
178
  return ["allow-scripts", "allow-same-origin"];
177
179
  case "external":
178
180
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -190,8 +192,18 @@ export function sandboxTokens(config) {
190
192
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
191
193
  */
192
194
  export function servedSandboxDirective(config) {
193
- return config.isolation === "domain" ? ["sandbox", ...sandboxTokens(config)] : null;
195
+ if (config.isolation !== "domain") {
196
+ return null;
197
+ }
198
+ return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
194
199
  }
200
+ /**
201
+ * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
202
+ * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
203
+ * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
204
+ * so the shell's realm (a test holds every sandbox Porthole writes to this).
205
+ */
206
+ export const PAGE_SANDBOX_TOKENS = ["allow-scripts"];
195
207
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
196
208
  export function servedDocumentCsp(config, directives) {
197
209
  const sandbox = servedSandboxDirective(config);
@@ -15,9 +15,14 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
15
15
  /**
16
16
  * What must hold before a call reaches the host's handler. A capability's gates all apply.
17
17
  *
18
- * - `user-activation`: the call follows a real user gesture in the frame. The shell refuses a call
19
- * without one, and the host checks its own page's activation (which a gesture in a child frame
20
- * propagates to). It stops calls made on load or on a timer; it is not proof of intent.
18
+ * - `user-activation`: the call follows a real user gesture. The shell refuses a call without one
19
+ * in its frame, but that check is the page's own (a page posts the call itself and skips it).
20
+ * The host checks its own page's transient activation, which a gesture in a child frame
21
+ * propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
22
+ * the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
23
+ * load, or on a timer while nobody does anything; it is not proof that the gesture was in this
24
+ * frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
25
+ * the person's composer), the host also asks that its page's focus be in the calling frame.
21
26
  * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
22
27
  * goes only if they accept. No `confirm` function means the call is refused (fail closed).
23
28
  * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
@@ -53,6 +58,13 @@ export interface CapabilitySpec {
53
58
  readonly method: string;
54
59
  readonly sdk?: string;
55
60
  };
61
+ /**
62
+ * Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
63
+ * focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
64
+ * a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
65
+ * typing in its own composer included.
66
+ */
67
+ readonly inFrame?: true;
56
68
  }
57
69
  /** The most text one `copyText` call carries. */
58
70
  export declare const MAX_COPY_CHARS = 20000;
@@ -174,6 +186,7 @@ export declare const CAPABILITIES: {
174
186
  readonly request: {
175
187
  readonly method: "porthole/call";
176
188
  };
189
+ readonly inFrame: true;
177
190
  };
178
191
  /** This artifact's current version, and a new version of it, base-checked (P088). */
179
192
  readonly artifact: {
@@ -109,6 +109,7 @@ export const CAPABILITIES = {
109
109
  defaultGates: ["user-activation", rate(30)],
110
110
  served: "handler",
111
111
  request: { method: "porthole/call" },
112
+ inFrame: true,
112
113
  },
113
114
  /** This artifact's current version, and a new version of it, base-checked (P088). */
114
115
  artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
@@ -238,6 +238,17 @@ export interface PortholeConfig {
238
238
  * `db`). Absent: 0.6's frames, globals and manual, exactly.
239
239
  */
240
240
  readonly runtime?: RuntimeVersion;
241
+ /**
242
+ * Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
243
+ * alone, a document of Porthole's own with no content in it, and the page runs in a child frame
244
+ * of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
245
+ * origin at its files' sealed address. The shell is then a realm the page can't reach, above the
246
+ * page's frame: it relays the page's messages, and tells the host when its own transient
247
+ * activation turns on (a press in the page activates its ancestors only), which is how the host
248
+ * knows the person, not the page, moved the keyboard into the frame or opened a comment. The
249
+ * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
250
+ */
251
+ readonly nested?: true;
241
252
  }
242
253
  export interface StorageConfig {
243
254
  /**
@@ -270,6 +270,7 @@ export function validateConfig(input, options = {}) {
270
270
  "storage",
271
271
  "errors",
272
272
  "runtime",
273
+ "nested",
273
274
  ], "config");
274
275
  if (!MODES.includes(config.mode)) {
275
276
  fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -544,6 +545,24 @@ export function validateConfig(input, options = {}) {
544
545
  fail("config.storage.shared", 'must be a short lowercase noun ("conversation")');
545
546
  }
546
547
  }
548
+ if (config.nested !== undefined) {
549
+ if (config.nested !== true) {
550
+ fail("config.nested", "must be true, or left out");
551
+ }
552
+ if (config.isolation !== "domain" || config.mode !== "artifact") {
553
+ fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
554
+ }
555
+ // The page's origin is opaque (P111): nothing of the content origin's own is its.
556
+ if (config.storage !== undefined) {
557
+ fail("config.nested", "a nested page keeps no storage: drop config.storage");
558
+ }
559
+ if (capabilities.assets !== undefined) {
560
+ fail("config.nested", "a nested page can't load its asset library (/_blob/) yet: drop assets");
561
+ }
562
+ if (isObject(config.egress) && config.egress.libraries === true) {
563
+ fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
564
+ }
565
+ }
547
566
  if (config.errors !== undefined) {
548
567
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
549
568
  fail("config.errors", 'must be "agent", "host" or "none"');