@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
@@ -0,0 +1,95 @@
1
+ # Insertion entry points the frame guard covers
2
+
3
+ The shell's frame guard (step 3 of the runtime, `src/shell/runtime.ts`; P030, P128, P129, P130)
4
+ keeps frame-like elements (`FRAMES`: `iframe`, `frame`, `frameset`, `object`, `embed`, `portal`,
5
+ `fencedframe`) and the resource hints a CSP doesn't govern (`HINTS`) out of every tree content can
6
+ reach. This page lists every way content can put a node into a document, or get a subtree it can
7
+ put in later, and how each is guarded. `test/shell.test.ts` checks each row against the runtime.
8
+
9
+ The invariant (P130): **every insertion entry point is guarded, every subtree producer strips
10
+ before it returns, and under the default configuration no frame-capable element can exist in a
11
+ content-reachable tree.** The mutation observer stays behind all of it as the backstop.
12
+
13
+ Statuses:
14
+
15
+ - **wrapped**: the method or setter runs every node argument through `admit`/`strip` (built-ins
16
+ captured before content runs, called through `callOf`) before the platform connects anything.
17
+ This holds whatever the parent is, connected or detached.
18
+ - **parsed and stripped**: the markup is parsed in a detached element of the same kind (`parseIn`)
19
+ or by the platform's own parser, stripped, then moved in through a wrapped method or returned.
20
+ - **producer stripped**: an API that hands content a subtree strips that subtree synchronously
21
+ before content gets it.
22
+ - **refused**: the call throws a neutral error, as `document.write` does, and nothing is made.
23
+ - **text only**: the entry point inserts text, never elements.
24
+ - **nothing to guard**: the entry point makes only empty elements of fixed kinds, or copies or
25
+ moves nodes that already went through the guard (and, under the default configuration, can't
26
+ hold a frame-like element).
27
+
28
+ `strip` walks a node's own tree (what `querySelectorAll` reaches) and also what that never enters:
29
+ each template's content and each open shadow root's tree, however deeply they nest (a work list,
30
+ not recursion). A shadow root it finds is also watched by the observer.
31
+
32
+ ## Putting nodes into a document
33
+
34
+ | # | Entry point | Status | How |
35
+ | --- | --- | --- | --- |
36
+ | A1 | `Node.appendChild` / `insertBefore` / `replaceChild` | wrapped | the node argument is admitted; a refused one goes in as an empty text node |
37
+ | A2 | `append` / `prepend` / `replaceChildren` on Element, Document, DocumentFragment (ShadowRoot inherits them) | wrapped | every argument is admitted |
38
+ | A3 | `before` / `after` / `replaceWith` on Element, CharacterData, DocumentType | wrapped | every argument is admitted |
39
+ | A4 | `Element.insertAdjacentElement` | wrapped | the element argument is admitted |
40
+ | A5 | `insertAdjacentText`, `innerText`, `outerText`, `textContent`, `nodeValue` | text only | `textContent` and `nodeValue` also go through the attribute-turn guard |
41
+ | A6 | `Range.insertNode` / `surroundContents` | wrapped | the node argument is admitted |
42
+ | A7 | `innerHTML` setter (Element, ShadowRoot) | parsed and stripped | parsed in a detached element of the same kind; on an HTML `<template>` the markup goes into its content, which is stripped before the setter returns |
43
+ | A8 | `outerHTML` setter | parsed and stripped | parsed in the parent's kind; where the parent is a document the platform's setter refuses |
44
+ | A9 | `insertAdjacentHTML` | parsed and stripped | the position is read once; the nodes go in through the wrapped methods |
45
+ | A10 | `setHTML` (Sanitizer API; Element, ShadowRoot) | parsed and stripped | sent to the `innerHTML` path |
46
+ | A11 | `setHTMLUnsafe` (Element, ShadowRoot) | parsed and stripped | sent to the `innerHTML` path (no declarative shadow DOM) |
47
+ | A12 | `document.open` / `write` / `writeln` | refused | throw |
48
+ | A13 | `execCommand("insertHTML")` (and `copy`, `cut`, `paste`) | refused | the command name is read once |
49
+ | A14 | `document.body` setter | wrapped | the value is admitted; a refused one refuses the set (`HierarchyRequestError`) |
50
+ | A15 | `HTMLTableElement` `tHead` / `tFoot` / `caption` setters | wrapped | as A14 |
51
+ | A16 | `createTHead` / `createTFoot` / `createCaption` / `createTBody` / `insertRow` / `insertCell` | nothing to guard | they make empty elements of fixed kinds; anything put into them goes through A1–A3 |
52
+ | A17 | `HTMLSelectElement.add`, `HTMLOptionsCollection.add` | wrapped | the element argument is admitted |
53
+ | A18 | `select[i] = option`, `options[i] = option`, the `length` setters (indexed setters can't be wrapped) | nothing to guard | under the default configuration no frame-like element can be made (A21, A25) or parsed into a subtree content gets (section B), so a detached option can't hold one |
54
+ | A19 | `Element.attachShadow` | wrapped | `init` is read once, field by field, into a fresh object with no prototype, which is all the platform is given; the new root is guarded |
55
+ | A20 | Declarative shadow DOM | parsed and stripped | the parser entry points that would build it are closed (A11, A12) or sent to `DOMParser`'s parse (`Document.parseHTMLUnsafe`, `Document.parseHTML`), which builds none |
56
+ | A21 | `createElement` / `createElementNS` (Document; ShadowRoot where an engine has them), and what copies nodes: `cloneNode`, `importNode`, `Range.cloneContents` | nothing to guard | under the default configuration a `FRAMES` name is refused at creation, in any case and any namespace (the local name after a prefix included); the name is read once and that reading is what the platform gets. Nothing else makes a frame-like element: `new Option(…)`, `new Image()` and `new Audio()` make their own kinds, and a copy is of a tree that already holds none |
57
+ | A22 | `src` / `srcdoc` and other attribute setters on an iframe | wrapped | under the default configuration no iframe exists to set; under `nestedFrames: "own"` a kept iframe leaves the document before a change would make it any other (P128) |
58
+ | A23 | `<object>` / `<embed>` and the other `FRAMES` elements | refused | refused at creation under the default configuration; removed on every guarded insertion and by the observer under any configuration; never kept, not even under `"own"` |
59
+ | A24 | `moveBefore` (where an engine has it) | wrapped | the node argument is admitted |
60
+ | A25 | `CustomElementRegistry.define` with `extends` naming a `FRAMES` element | refused | under the default configuration; the options are read once into a fresh object |
61
+ | A26 | A markup method on Element, ShadowRoot, Document, DocumentFragment or Range not named above (one a later engine adds) | refused | any own method whose name contains `HTML`, other than those above, throws |
62
+
63
+ ## Producers: APIs that hand content a subtree it can insert later
64
+
65
+ | # | Producer | Status | How |
66
+ | --- | --- | --- | --- |
67
+ | B1 | `DOMParser.parseFromString`, every MIME type | producer stripped | the platform's parse, then `strip` of the document |
68
+ | B2 | `HTMLTemplateElement.content` | producer stripped | the getter strips the content before it returns it (and A7 strips what the template's `innerHTML` fills) |
69
+ | B3 | `Document.parseHTMLUnsafe`, `Document.parseHTML` | producer stripped | the platform's `DOMParser` parse, stripped |
70
+ | B4 | `document.implementation.createHTMLDocument` | producer stripped | the new document is stripped |
71
+ | B5 | `document.implementation.createDocument` | producer stripped | the new document is stripped (its document element included) |
72
+ | B6 | `Range.createContextualFragment` | producer stripped | the fragment is stripped |
73
+ | B7 | `XSLTProcessor.transformToFragment` / `transformToDocument` (where an engine has them) | producer stripped | the result is stripped |
74
+ | B8 | `XMLHttpRequest` `responseXML`, and `response` when it is a document | producer stripped | each getter strips the document before it returns it |
75
+ | B9 | `Document.importNode` / `adoptNode` | producer stripped | the clone (importNode) or the node (adoptNode) is stripped; one that is itself a frame-like element is refused |
76
+ | B10 | HTML inside SVG `<foreignObject>` and MathML `<annotation-xml>`, and markup that crosses namespaces while parsing | parsed and stripped | the walk matches HTML-namespace frame-like elements wherever they are in the subtree |
77
+ | B11 | Inert documents' own `body` setter, and nodes moved into the live document | wrapped | the same prototypes, so A14 and B9 apply |
78
+ | B12 | Template contents and open shadow roots inside any subtree the guard walks | producer stripped | `strip` enters each template's content and each open shadow root's tree, recursively |
79
+
80
+ ## Editing
81
+
82
+ | # | Entry point | Status | How |
83
+ | --- | --- | --- | --- |
84
+ | E1 | Paste, drop, replacement text and yank into editable content (`beforeinput` with `insertFromPaste`, `insertFromPasteAsQuotation`, `insertFromDrop`, `insertReplacementText`, `insertFromYank`) | text only | the shell's own `beforeinput` listener (on `window`, capturing, registered before content runs) cancels one whose data carries any type but `text/plain`, and inserts only its plain text through the editor's `insertText`, which carries no markup. Only the browser's own events are acted on. Composition (`insertCompositionText`) can't be cancelled, and carries text alone |
85
+
86
+ A drop or paste of formatted content into an editable region goes in as plain text. A text field
87
+ (`<input>`, `<textarea>`) takes text only and is unaffected.
88
+
89
+ ## Under `nestedFrames: "own"`
90
+
91
+ The configuration that keeps a page's own iframes (P128) keeps creation open: an `iframe` can be
92
+ made, and the guards above decide when it is connected or changed (a kept frame leaves the
93
+ document before a change would make it any other). Elements that are never kept (`frame`,
94
+ `frameset`, `object`, `embed`, `portal`, `fencedframe`, an iframe that isn't the page's own) are
95
+ removed on every guarded insertion and by the observer. The trade-offs P128 records stand.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.6",
3
+ "version": "0.14.8",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -75,6 +75,8 @@ const REFERENCE_ATTRIBUTES: Readonly<Record<string, readonly string[]>> = {
75
75
  audio: ["src"],
76
76
  track: ["src"],
77
77
  embed: ["src"],
78
+ // A page's own frame (P128, `nestedFrames: "own"`): a file of the set, looked up as the rest.
79
+ iframe: ["src"],
78
80
  input: ["src"],
79
81
  link: ["href"],
80
82
  a: ["href"],
package/src/check/lint.ts CHANGED
@@ -6,8 +6,10 @@ import {
6
6
  librarySources,
7
7
  } from "../compile/policy.ts";
8
8
  import type { PortholeConfig } from "../config/schema.ts";
9
+ import { servesFiles } from "../files/paths.ts";
9
10
  import { sizeWords } from "../guide/limits.ts";
10
11
  import { originMatchesSource } from "../isolation/served.ts";
12
+ import { attributesOf } from "./markup.ts";
11
13
  import { scrollLock } from "./scroll.ts";
12
14
 
13
15
  /**
@@ -124,6 +126,72 @@ const OWN_CDN: readonly {
124
126
  { name: "Plotly", host: /^https:\/\/cdn\.plot\.ly\/plotly/u, pinned: /\d+\.\d+\.\d+/u },
125
127
  ];
126
128
 
129
+ /** The most of a tag's text a frame's attributes are read from: a `srcdoc` may hold markup. */
130
+ const MOST_TAG_CHARS = 65_536;
131
+
132
+ /** The most frame-like tags read for `strayFrame`: past them, the rest isn't looked at. */
133
+ const MOST_FRAMES = 200;
134
+
135
+ /**
136
+ * A tag's attributes' text, from just past its name to its closing `>` outside any quoted value
137
+ * (a `srcdoc` holds `<` and `>`), read at most `MOST_TAG_CHARS` far: linear in what it reads.
138
+ */
139
+ function tagText(content: string, from: number): string {
140
+ const end = Math.min(content.length, from + MOST_TAG_CHARS);
141
+ let quote = "";
142
+ for (let at = from; at < end; at += 1) {
143
+ const char = content[at];
144
+ if (quote !== "") {
145
+ if (char === quote) {
146
+ quote = "";
147
+ }
148
+ } else if (char === '"' || char === "'") {
149
+ quote = char;
150
+ } else if (char === ">") {
151
+ return content.slice(from, at);
152
+ }
153
+ }
154
+ return content.slice(from, end);
155
+ }
156
+
157
+ /**
158
+ * Under `nestedFrames: "own"` (P128), the first frame-like element that never loads, and why: a
159
+ * `<frame>`, `<object>` or `<embed>`; an `<iframe>` of another site (any scheme, `//`), of the
160
+ * origin's root (`/`), or with neither `src` nor `srcdoc`; one with a relative `src` where there
161
+ * are no files to frame (`relative`: false). Null where every frame is the page's own.
162
+ */
163
+ function strayFrame(
164
+ content: string,
165
+ relative: boolean,
166
+ ): { readonly tag: string; readonly src: string; readonly index: number } | null {
167
+ let read = 0;
168
+ for (const match of content.matchAll(/<(iframe|frame|object|embed)\b/giu)) {
169
+ read += 1;
170
+ if (read > MOST_FRAMES) {
171
+ break;
172
+ }
173
+ const tag = (match[1] ?? "").toLowerCase();
174
+ if (tag !== "iframe") {
175
+ return { tag, src: "", index: match.index };
176
+ }
177
+ const attributes = attributesOf(tagText(content, match.index + match[0].length));
178
+ if (attributes.some((each) => each.name === "srcdoc")) {
179
+ continue;
180
+ }
181
+ const src = (attributes.find((each) => each.name === "src")?.value ?? "").trim();
182
+ const elsewhere =
183
+ src === "" ||
184
+ /^[a-z][a-z0-9+.-]*:/iu.test(src) ||
185
+ src.startsWith("/") ||
186
+ src.startsWith("\\") ||
187
+ !relative;
188
+ if (elsewhere) {
189
+ return { tag, src, index: match.index };
190
+ }
191
+ }
192
+ return null;
193
+ }
194
+
127
195
  export function lintContent(config: PortholeConfig, content: string): Finding[] {
128
196
  return lintPage(config, content, { scrollLock: true });
129
197
  }
@@ -179,14 +247,35 @@ export function lintPage(
179
247
  }
180
248
  }
181
249
  }
182
- const frame = /<(iframe|frame|object|embed)\b/iu.exec(content);
183
- if (frame !== null) {
184
- add(
185
- "nested-frame",
186
- "error",
187
- `Remove the <${frame[1]?.toLowerCase()}>: nested frames and plugins are taken out of a ${it} and never run. Draw it inline instead.`,
188
- frame.index,
189
- );
250
+ if (config.nestedFrames === "own") {
251
+ // A page's own frames load (P128): only what never does is said.
252
+ const files = servesFiles(config);
253
+ const own = files
254
+ ? 'an <iframe> of one of its own files (a relative src, src="chart.html") or with srcdoc does'
255
+ : "an <iframe> with srcdoc does";
256
+ const stray = strayFrame(content, files);
257
+ if (stray !== null) {
258
+ add(
259
+ "nested-frame",
260
+ "error",
261
+ stray.tag !== "iframe"
262
+ ? `Remove the <${stray.tag}>: <frame>, <object> and <embed> are taken out of a ${it} and never run; ${own}.`
263
+ : stray.src === ""
264
+ ? `This <iframe> has neither src nor srcdoc, and is taken out of the ${it}: ${own}.`
265
+ : `Remove the <iframe src="${stray.src.slice(0, 200)}">: ${files ? "frames of other sites (or of another path of the address) are" : "frames of an address are"} taken out of a ${it} and never load; ${own}.`,
266
+ stray.index,
267
+ );
268
+ }
269
+ } else {
270
+ const frame = /<(iframe|frame|object|embed)\b/iu.exec(content);
271
+ if (frame !== null) {
272
+ add(
273
+ "nested-frame",
274
+ "error",
275
+ `Remove the <${frame[1]?.toLowerCase()}>: nested frames and plugins are taken out of a ${it} and never run. Draw it inline instead.`,
276
+ frame.index,
277
+ );
278
+ }
190
279
  }
191
280
  const write = /\bdocument\s*\.\s*write(?:ln)?\s*\(/u.exec(content);
192
281
  if (write !== null) {
@@ -139,20 +139,37 @@ export const FILE_SET_DIRECTIVES = [
139
139
  "worker-src",
140
140
  ] as const;
141
141
 
142
+ /**
143
+ * The directives a page of a file set opens to its version's own files under `config` (P082):
144
+ * `FILE_SET_DIRECTIVES`, and `frame-src` too where the config lets content frame its own files
145
+ * (`nestedFrames: "own"`, P128). Never `child-src`: every engine Porthole supports reads frames
146
+ * from `frame-src` (P038), and `child-src` is only its fallback (and workers', which have
147
+ * `worker-src`).
148
+ */
149
+ export function fileSetDirectives(config: PortholeConfig): readonly string[] {
150
+ return config.nestedFrames === "own"
151
+ ? [...FILE_SET_DIRECTIVES, "frame-src"]
152
+ : FILE_SET_DIRECTIVES;
153
+ }
154
+
142
155
  /**
143
156
  * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
144
- * opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
145
- * content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
146
- * paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
147
- * `'none'`. Opaque frames have no files, and keep P022's rule whole.
157
+ * opened for each kind that loads (`opened`: `FILE_SET_DIRECTIVES` by default, a server's
158
+ * `fileSetDirectives(config)`), by `source`, the files' path on the content origin
159
+ * (`https://a-x.example-usercontent.com/v/3/`).
160
+ * Never `'self'`: the origin's other paths (other versions, Porthole's own) stay closed, and
161
+ * plugins, forms and `<base>` stay `'none'`, frames too unless the config opts into its own
162
+ * (P128: `frame-src` its version's path, never another origin). Opaque frames have no files, and
163
+ * keep P022's rule whole.
148
164
  */
149
165
  export function fileSetCspDirectives(
150
166
  directives: readonly CspDirective[],
151
167
  source: string,
168
+ opened: readonly string[] = FILE_SET_DIRECTIVES,
152
169
  ): CspDirective[] {
153
- const opened = new Set<string>(FILE_SET_DIRECTIVES);
170
+ const open = new Set<string>(opened);
154
171
  return directives.map(([name, ...sources]) => {
155
- if (!opened.has(name)) {
172
+ if (!open.has(name)) {
156
173
  return [name, ...sources];
157
174
  }
158
175
  const kept = sources.filter((each) => each !== "'none'");
@@ -269,6 +269,19 @@ export interface PortholeConfig {
269
269
  * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
270
270
  */
271
271
  readonly nested?: true;
272
+ /**
273
+ * Which nested frames content may make (P128). `none` (default, and absent): the shell removes
274
+ * every frame-like element content adds, and the CSP's `frame-src` is `'none'`. `own`: an
275
+ * `<iframe>` of one of the page's own files (its `src` under its version's own address, P082)
276
+ * and a `srcdoc` one load and run; frames of other sites, `<frame>`, `<object>` and `<embed>`
277
+ * are still removed, and a served file set's `frame-src` opens its version's own path only.
278
+ * A weakening, opted into: a child frame is a realm of its own, where the shell's WebRTC
279
+ * removal, clipboard guards and navigation cancel never ran (a page of the set framed there has
280
+ * its own shell; a `srcdoc` frame, or the `about:blank` a new frame starts as, has none), so
281
+ * content reaches WebRTC and the clipboard's events there. Not for url mode, a live widget
282
+ * (no network of its own, P079) or a nested page (P111).
283
+ */
284
+ readonly nestedFrames?: "none" | "own";
272
285
  }
273
286
 
274
287
  export interface StorageConfig {
@@ -325,6 +325,7 @@ export function validateConfig(
325
325
  "errors",
326
326
  "runtime",
327
327
  "nested",
328
+ "nestedFrames",
328
329
  ],
329
330
  "config",
330
331
  );
@@ -710,6 +711,21 @@ export function validateConfig(
710
711
  }
711
712
  }
712
713
 
714
+ // A page's own nested frames (P128): opted into, never a default.
715
+ if (config.nestedFrames !== undefined) {
716
+ if (config.nestedFrames !== "none" && config.nestedFrames !== "own") {
717
+ fail("config.nestedFrames", 'must be "none" or "own", or left out');
718
+ }
719
+ if (config.nestedFrames === "own" && config.mode === "url") {
720
+ fail("config.nestedFrames", "url mode has no shell: its app's frames are its own");
721
+ }
722
+ // A nested page's frames have an opaque ancestor, which no frame-ancestors source matches:
723
+ // none of its own files would load in one. Not measured yet.
724
+ if (config.nestedFrames === "own" && config.nested === true) {
725
+ fail("config.nestedFrames", 'a nested page (P111) has no "own" frames yet: leave it out');
726
+ }
727
+ }
728
+
713
729
  if (config.errors !== undefined) {
714
730
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
715
731
  fail("config.errors", 'must be "agent", "host" or "none"');
@@ -66,6 +66,17 @@ export function attack(code: string, markup = ""): string {
66
66
  document.removeEventListener("securitypolicyviolation", seen);
67
67
  return blocked;
68
68
  };
69
+ // An element of \`tag\`, or null where the shell refuses to make one (P130: a frame-like element,
70
+ // under the default config): the guard held, and \`r.refused\` lists what was refused at creation.
71
+ const created = (tag) => {
72
+ try {
73
+ return document.createElement(tag);
74
+ } catch (error) {
75
+ if (!error || error.name !== "NotSupportedError") throw error;
76
+ r.refused = (r.refused || []).concat(tag);
77
+ return null;
78
+ }
79
+ };
69
80
  try {
70
81
  ${code}
71
82
  } catch (error) {
@@ -78,3 +89,14 @@ ${code}
78
89
  }
79
90
 
80
91
  export const inline = (options: PresetOptions = {}) => presets.inlineWidget(options);
92
+
93
+ /**
94
+ * Records, as a measured fact, the frame-like elements a probe's verdict says the shell refused
95
+ * at creation (`created` in `attack`; P130): the guard held, and nothing was there to remove.
96
+ */
97
+ export function noteRefused(context: ProbeContext, verdict: Record<string, unknown>): void {
98
+ const refused = verdict.refused;
99
+ if (Array.isArray(refused) && refused.length > 0) {
100
+ context.measured(`${context.engine}: ${refused.join(", ")} refused at creation`);
101
+ }
102
+ }
@@ -3,7 +3,7 @@ import type { LimitId } from "../guide/limits.ts";
3
3
  import type { LaunchedDisplay } from "./index.ts";
4
4
  import { presets } from "../presets/presets.ts";
5
5
  import { resolveTheme } from "../theme/variables.ts";
6
- import { attack, inline, js, type Probe } from "./kit.ts";
6
+ import { attack, inline, js, noteRefused, type Probe } from "./kit.ts";
7
7
  import { settle } from "./oracles.ts";
8
8
 
9
9
  /**
@@ -660,8 +660,10 @@ export const LIMIT_PROBES: readonly Probe[] = [
660
660
  document.getElementById("go").addEventListener("click", async () => {
661
661
  try { document.write("<p>x</p>"); r.write = "wrote"; } catch (e) { r.write = "throws"; }
662
662
  try { document.open(); r.open = "opened"; } catch (e) { r.open = "throws"; }
663
- const frame = document.createElement("iframe");
664
- document.body.append(frame);
663
+ // Refused at creation under the default config (P130): the frame can't exist.
664
+ let frame = null;
665
+ try { frame = document.createElement("iframe"); } catch (e) { if (!e || e.name !== "NotSupportedError") throw e; r.refused = ["iframe"]; }
666
+ if (frame) document.body.append(frame);
665
667
  await new Promise((resolve) => setTimeout(resolve, 100));
666
668
  r.frames = document.querySelectorAll("iframe, object, embed").length;
667
669
  r.fullscreen = await document.documentElement.requestFullscreen().then(() => "entered", (e) => "rejected");
@@ -671,8 +673,9 @@ export const LIMIT_PROBES: readonly Probe[] = [
671
673
  </script>`,
672
674
  });
673
675
  await click(display, "#go");
676
+ const shell = await replacedOrRecorded(display, "#go");
674
677
  expect(
675
- await replacedOrRecorded(display, "#go"),
678
+ shell,
676
679
  "probe: write and open throw, nested frames are removed, full screen is closed",
677
680
  ).toMatchObject({
678
681
  write: "throws",
@@ -683,6 +686,7 @@ export const LIMIT_PROBES: readonly Probe[] = [
683
686
  expect(["rejected", "absent"], "probe: the clipboard was written").toContain(
684
687
  (await recorded(display)).clipboard,
685
688
  );
689
+ noteRefused(context, shell);
686
690
  },
687
691
  },
688
692
  {
@@ -731,6 +735,7 @@ export const LIMIT_CHECKS: { readonly [Id in LimitId]: readonly string[] } = {
731
735
  workers: ["14.workers", "3.webrtc"],
732
736
  sound: ["14.sound"],
733
737
  address: ["14.address", "served.domain.address"],
734
- shell: ["14.shell", "4.document-write", "4.light-dom"],
738
+ // A page's own frames, where the config opts in (P128): what loads, and what still doesn't.
739
+ shell: ["14.shell", "4.document-write", "4.light-dom", "4.own-external"],
735
740
  storage: ["14.storage", "served.domain.storage-scope"],
736
741
  };