@botiverse/porthole 0.14.7 → 0.14.9

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 (87) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/dist/bridge/bridge.d.ts +6 -0
  3. package/dist/bridge/bridge.js +5 -0
  4. package/dist/check/files.js +2 -0
  5. package/dist/check/lint.js +82 -3
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +17 -6
  8. package/dist/compile/policy.js +22 -7
  9. package/dist/config/capabilities.d.ts +16 -2
  10. package/dist/config/capabilities.js +8 -0
  11. package/dist/config/schema.d.ts +13 -0
  12. package/dist/config/validate.js +15 -0
  13. package/dist/conformance/harness-source.js +1 -1
  14. package/dist/conformance/kit.d.ts +5 -0
  15. package/dist/conformance/kit.js +21 -0
  16. package/dist/conformance/limits.js +10 -5
  17. package/dist/conformance/probes.js +139 -28
  18. package/dist/conformance/served.js +25 -4
  19. package/dist/find/types.d.ts +83 -0
  20. package/dist/find/types.js +29 -0
  21. package/dist/find/validate.d.ts +17 -0
  22. package/dist/find/validate.js +82 -0
  23. package/dist/guide/guide.js +2 -1
  24. package/dist/guide/limits.js +8 -1
  25. package/dist/host/create-host.js +249 -4
  26. package/dist/host/pass-on.js +3 -2
  27. package/dist/host/types.d.ts +51 -0
  28. package/dist/index.d.ts +4 -2
  29. package/dist/index.js +4 -1
  30. package/dist/presets/presets.d.ts +6 -0
  31. package/dist/presets/presets.js +6 -0
  32. package/dist/react/frame.d.ts +43 -0
  33. package/dist/react/frame.js +107 -3
  34. package/dist/react/view.js +2 -0
  35. package/dist/runtime/contract.d.ts +1 -1
  36. package/dist/runtime/contract.js +1 -1
  37. package/dist/server/files.js +4 -3
  38. package/dist/server/server.js +4 -1
  39. package/dist/shell/annotate.js +2 -95
  40. package/dist/shell/document.d.ts +3 -3
  41. package/dist/shell/document.js +5 -3
  42. package/dist/shell/find.d.ts +82 -0
  43. package/dist/shell/find.js +725 -0
  44. package/dist/shell/plan.d.ts +5 -0
  45. package/dist/shell/plan.js +2 -0
  46. package/dist/shell/runtime.d.ts +30 -1
  47. package/dist/shell/runtime.js +789 -105
  48. package/dist/shell/text.d.ts +17 -0
  49. package/dist/shell/text.js +140 -0
  50. package/docs/ADOPTING.md +103 -0
  51. package/docs/ARCHITECTURE.md +10 -3
  52. package/docs/DECISIONS.md +513 -1
  53. package/docs/DESIGN.md +40 -4
  54. package/docs/THREAT_MODEL.md +75 -6
  55. package/docs/insertion-entry-points.md +112 -0
  56. package/package.json +1 -1
  57. package/src/bridge/bridge.ts +7 -0
  58. package/src/check/files.ts +2 -0
  59. package/src/check/lint.ts +97 -8
  60. package/src/compile/policy.ts +23 -6
  61. package/src/config/capabilities.ts +13 -1
  62. package/src/config/schema.ts +13 -0
  63. package/src/config/validate.ts +16 -0
  64. package/src/conformance/kit.ts +22 -0
  65. package/src/conformance/limits.ts +10 -5
  66. package/src/conformance/probes.ts +149 -28
  67. package/src/conformance/served.ts +24 -4
  68. package/src/find/types.ts +86 -0
  69. package/src/find/validate.ts +101 -0
  70. package/src/guide/guide.ts +3 -1
  71. package/src/guide/limits.ts +9 -1
  72. package/src/host/create-host.ts +267 -4
  73. package/src/host/pass-on.ts +3 -2
  74. package/src/host/types.ts +52 -0
  75. package/src/index.ts +13 -0
  76. package/src/presets/presets.ts +15 -0
  77. package/src/react/frame.tsx +160 -1
  78. package/src/react/view.tsx +3 -0
  79. package/src/runtime/contract.ts +1 -1
  80. package/src/server/files.ts +8 -2
  81. package/src/server/server.ts +4 -1
  82. package/src/shell/annotate.ts +3 -95
  83. package/src/shell/document.ts +5 -3
  84. package/src/shell/find.ts +731 -0
  85. package/src/shell/plan.ts +7 -0
  86. package/src/shell/runtime.ts +792 -105
  87. package/src/shell/text.ts +140 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,80 @@
4
4
  section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
5
5
  P-numbers below.
6
6
 
7
+ ## 0.14.9
8
+
9
+ - **Find in page (P131):** a host's own find bar over a display. Declare `find`
10
+ (`capabilities: { find: {} }`; in no preset by default) and use `display.find`: `query(query, {
11
+ direction, caseSensitive })` finds the query in the page's text (case-insensitive, any spacing,
12
+ what is drawn only, at most 1,000), highlights every match and the current one in a layer of the
13
+ shell's own, brings the current one into view, and resolves with `{ total, active, capped?,
14
+ rect? }` or `"unsupported"` (no `find`, an older shell, no answer in 3 s, superseded by a later
15
+ query: the shell searches only the latest of a burst); `clear()`;
16
+ `takeShortcut(true)` makes Cmd+F or Ctrl+F in the frame open the host's bar (`findRequested`)
17
+ instead of the browser's, unless the page handles the key itself. `findUpdated` tells new numbers
18
+ when the page changes. A query holds only for the content it was asked of: a reload, a restart
19
+ after a navigation away, or other content forgets it (clear the host's find bar then), as does
20
+ the React handle for another `content`, `generation`, `document`, `instance` or `config`. Hosts
21
+ should send queries on a pause or Enter, not at every key (ADOPTING). React: `onFindRequested`,
22
+ `onFindUpdated`, and `find`/`clearFind` on the frame's handle. New exports: `FIND_METHODS`,
23
+ `FIND_LIMITS`, `parseFindResult`, `parseFindReport` and their types. The manual tells the agent people may search the page's words.
24
+ - **Security (P131):** the page reads every query the host sends (the search runs in its
25
+ document), so declare `find` only where it may learn what the person searches for; P131 records
26
+ that exposure as accepted. What the frame says back is the page's word; the host
27
+ takes `findRequested` only with the page's focus in the frame (negative control
28
+ `find-requested-focus`). No CSP, sandbox or egress changes. A host must upgrade its content
29
+ server (the shell) for find to work; an older one answers `"unsupported"`. The find runtime and
30
+ the text index it shares with annotations call only built-ins captured before content runs,
31
+ through `callOf` (P129), and the find layer's nodes go in only through the guarded insertion
32
+ methods (P130; listed in [docs/insertion-entry-points.md](docs/insertion-entry-points.md)).
33
+
34
+ ## 0.14.8
35
+
36
+ - **Frame guard: broader coverage of DOM insertion and parsing entry points (P130),** listed in
37
+ [docs/insertion-entry-points.md](docs/insertion-entry-points.md).
38
+ - **Two default behaviours change (P130):**
39
+ - a page script that creates a frame-like element (`iframe`, `frame`, `frameset`, `object`,
40
+ `embed`, `portal`, `fencedframe`) with `createElement`/`createElementNS` now gets a
41
+ `NotSupportedError` there, so the rest of that script doesn't run; before, the element was
42
+ removed when it was inserted. `nestedFrames: "own"` is unchanged.
43
+ - in every default display, pasting or dropping formatted content into an editable element
44
+ (`contenteditable`, `designMode`) inserts its plain text only, so the formatting is lost.
45
+ - **Conformance:** a frame-like element the shell refuses at creation (P130) counts as the guard
46
+ holding, recorded as "refused at creation", not as a probe whose setup failed.
47
+ - **The shell's guards call only built-ins captured before content runs (P129):** step 3's frame
48
+ guard and its observer, the before-change backstop, and the synchronous insertion and HTML-parse
49
+ wrappers (`append`/`appendChild`/… , `innerHTML`/`outerHTML`/`insertAdjacentHTML`/`execCommand`,
50
+ the attribute-turn guards) take every built-in they use from references kept before any content
51
+ runs and call each only through `callOf`, which is `Reflect.apply` captured first — so nothing
52
+ content later puts on a DOM prototype, on `Array.from`/the array iterator/`Array.prototype.indexOf`,
53
+ or on `Function.prototype.apply`/`call`/`bind` takes part in the guard's reads, calls, walks or
54
+ decisions (live collections are indexed loops, arguments are prototype-less lists). Each name or
55
+ value a guard inspects and then forwards (a command name, an attribute name or value, a token) is
56
+ read once and that same reading is both checked and acted on, so a value that converts one way
57
+ when checked and another when the platform reads it can't slip past. Extends P128 and P030 to
58
+ every built-in the guard touches. No default behaviour, CSP, plan or manual changes.
59
+ - **A frame's size, at most once an animation frame (P127, audit 2026-10-29 C-1):** after a run's
60
+ first size (taken at once, as before), the host takes the last `size-changed` a frame sent on the
61
+ next animation frame, and drops a size the same as the last one taken, so content sending sizes as
62
+ fast as it can no longer reflows the host's page and fires `resize` (`onResize`) for each. A size
63
+ after the first now arrives on the next animation frame, not during the message.
64
+ - **A page's own nested frames, opt-in (P128):** `nestedFrames: "own"` (a preset's option, a
65
+ display kind's `options`; default `"none"`, which changes nothing) lets content keep an
66
+ `<iframe>` of one of its version's own files (a relative `src`) or with `srcdoc`, which load and
67
+ run, as in Claude's Artifacts. Frames of other sites, of another path of the origin, `data:`,
68
+ `blob:` and empty ones, `<frame>`, `<object>` and `<embed>` are still removed, and a kept frame
69
+ is removed before a change would point it elsewhere. A file set's page opens `frame-src` to its
70
+ version's path (`fileSetDirectives(config)`, and `fileSetCspDirectives` takes the directives to
71
+ open), and its files' `frame-ancestors` name its own origin. Opaque frames keep `srcdoc` ones
72
+ only. Refused for url mode, nested pages and `presets.liveWidget`. The `nested-frame` lint then
73
+ names only frames that never load; `lintFiles` looks a frame's `src` up in the set.
74
+ - **Security (P128): opting in is a weakening.** A nested frame is a realm of its own where the
75
+ shell's hardening never ran: content there has WebRTC (a way out past `connect-src`), resource
76
+ hints, `document.write`, and a click's `execCommand("copy")` and copy listeners (pastejacking,
77
+ with no notice). Child frames still can't navigate outside the version's path, and inherit the
78
+ sandbox. Leave it off unless your product accepts that; nothing changes for a host that doesn't
79
+ set it.
80
+
7
81
  ## 0.14.7
8
82
 
9
83
  - **`server.doorAnswer(instance, grant, request?, at?)` (P126):** the door's answer for a grant a
@@ -1,5 +1,6 @@
1
1
  import { type CapabilityName } from "../config/capabilities.ts";
2
2
  import type { AnnotationReport } from "../annotate/types.ts";
3
+ import type { FindReport } from "../find/types.ts";
3
4
  import type { PortholeConfig } from "../config/schema.ts";
4
5
  import { type PageDeclaration } from "../runtime/declaration.ts";
5
6
  import { type ViewerInfo } from "../runtime/levels.ts";
@@ -34,6 +35,11 @@ export type BridgeEvent = {
34
35
  } | {
35
36
  readonly type: "annotation";
36
37
  readonly report: AnnotationReport;
38
+ }
39
+ /** What the frame said of find in page unasked (P131), checked. */
40
+ | {
41
+ readonly type: "find";
42
+ readonly report: FindReport;
37
43
  } | {
38
44
  readonly type: "refused";
39
45
  readonly capability: CapabilityName;
@@ -1,5 +1,6 @@
1
1
  import { MAX_CONTEXT_CHARS, MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
2
2
  import { parseReport } from "../annotate/validate.js";
3
+ import { parseFindReport } from "../find/validate.js";
3
4
  import { callGates, effectiveGates } from "../compile/policy.js";
4
5
  import { boundedText } from "./bounded-text.js";
5
6
  import { isJsonData } from "./json-data.js";
@@ -178,6 +179,7 @@ const VALIDATORS = {
178
179
  : null;
179
180
  },
180
181
  annotate: (args) => parseReport(args),
182
+ find: (args) => parseFindReport(args),
181
183
  // The runtime's own (P088-P090): their shapes and limits, before any gate.
182
184
  user: (args) => (args === undefined || isRecord(args) ? {} : null),
183
185
  comments: (args) => parseCommentRequest(args),
@@ -590,6 +592,9 @@ export function createBridge(options) {
590
592
  else if (capability === "annotate") {
591
593
  onEvent({ type: "annotation", report: args });
592
594
  }
595
+ else if (capability === "find") {
596
+ onEvent({ type: "find", report: args });
597
+ }
593
598
  else {
594
599
  const report = args;
595
600
  if (report.navigationBlocked !== undefined) {
@@ -40,6 +40,8 @@ const REFERENCE_ATTRIBUTES = {
40
40
  audio: ["src"],
41
41
  track: ["src"],
42
42
  embed: ["src"],
43
+ // A page's own frame (P128, `nestedFrames: "own"`): a file of the set, looked up as the rest.
44
+ iframe: ["src"],
43
45
  input: ["src"],
44
46
  link: ["href"],
45
47
  a: ["href"],
@@ -1,6 +1,8 @@
1
1
  import { anyHttps, declaredCapabilities, egressOrigins, librarySources, } from "../compile/policy.js";
2
+ import { servesFiles } from "../files/paths.js";
2
3
  import { sizeWords } from "../guide/limits.js";
3
4
  import { originMatchesSource } from "../isolation/served.js";
5
+ import { attributesOf } from "./markup.js";
4
6
  import { scrollLock } from "./scroll.js";
5
7
  const lineOf = (text, index) => text.slice(0, index).split("\n").length;
6
8
  const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
@@ -71,6 +73,66 @@ const OWN_CDN = [
71
73
  { name: "jQuery", host: /^https:\/\/code\.jquery\.com\//u, pinned: /\d+\.\d+\.\d+/u },
72
74
  { name: "Plotly", host: /^https:\/\/cdn\.plot\.ly\/plotly/u, pinned: /\d+\.\d+\.\d+/u },
73
75
  ];
76
+ /** The most of a tag's text a frame's attributes are read from: a `srcdoc` may hold markup. */
77
+ const MOST_TAG_CHARS = 65_536;
78
+ /** The most frame-like tags read for `strayFrame`: past them, the rest isn't looked at. */
79
+ const MOST_FRAMES = 200;
80
+ /**
81
+ * A tag's attributes' text, from just past its name to its closing `>` outside any quoted value
82
+ * (a `srcdoc` holds `<` and `>`), read at most `MOST_TAG_CHARS` far: linear in what it reads.
83
+ */
84
+ function tagText(content, from) {
85
+ const end = Math.min(content.length, from + MOST_TAG_CHARS);
86
+ let quote = "";
87
+ for (let at = from; at < end; at += 1) {
88
+ const char = content[at];
89
+ if (quote !== "") {
90
+ if (char === quote) {
91
+ quote = "";
92
+ }
93
+ }
94
+ else if (char === '"' || char === "'") {
95
+ quote = char;
96
+ }
97
+ else if (char === ">") {
98
+ return content.slice(from, at);
99
+ }
100
+ }
101
+ return content.slice(from, end);
102
+ }
103
+ /**
104
+ * Under `nestedFrames: "own"` (P128), the first frame-like element that never loads, and why: a
105
+ * `<frame>`, `<object>` or `<embed>`; an `<iframe>` of another site (any scheme, `//`), of the
106
+ * origin's root (`/`), or with neither `src` nor `srcdoc`; one with a relative `src` where there
107
+ * are no files to frame (`relative`: false). Null where every frame is the page's own.
108
+ */
109
+ function strayFrame(content, relative) {
110
+ let read = 0;
111
+ for (const match of content.matchAll(/<(iframe|frame|object|embed)\b/giu)) {
112
+ read += 1;
113
+ if (read > MOST_FRAMES) {
114
+ break;
115
+ }
116
+ const tag = (match[1] ?? "").toLowerCase();
117
+ if (tag !== "iframe") {
118
+ return { tag, src: "", index: match.index };
119
+ }
120
+ const attributes = attributesOf(tagText(content, match.index + match[0].length));
121
+ if (attributes.some((each) => each.name === "srcdoc")) {
122
+ continue;
123
+ }
124
+ const src = (attributes.find((each) => each.name === "src")?.value ?? "").trim();
125
+ const elsewhere = src === "" ||
126
+ /^[a-z][a-z0-9+.-]*:/iu.test(src) ||
127
+ src.startsWith("/") ||
128
+ src.startsWith("\\") ||
129
+ !relative;
130
+ if (elsewhere) {
131
+ return { tag, src, index: match.index };
132
+ }
133
+ }
134
+ return null;
135
+ }
74
136
  export function lintContent(config, content) {
75
137
  return lintPage(config, content, { scrollLock: true });
76
138
  }
@@ -106,9 +168,26 @@ export function lintPage(config, content, options) {
106
168
  }
107
169
  }
108
170
  }
109
- const frame = /<(iframe|frame|object|embed)\b/iu.exec(content);
110
- if (frame !== null) {
111
- add("nested-frame", "error", `Remove the <${frame[1]?.toLowerCase()}>: nested frames and plugins are taken out of a ${it} and never run. Draw it inline instead.`, frame.index);
171
+ if (config.nestedFrames === "own") {
172
+ // A page's own frames load (P128): only what never does is said.
173
+ const files = servesFiles(config);
174
+ const own = files
175
+ ? 'an <iframe> of one of its own files (a relative src, src="chart.html") or with srcdoc does'
176
+ : "an <iframe> with srcdoc does";
177
+ const stray = strayFrame(content, files);
178
+ if (stray !== null) {
179
+ add("nested-frame", "error", stray.tag !== "iframe"
180
+ ? `Remove the <${stray.tag}>: <frame>, <object> and <embed> are taken out of a ${it} and never run; ${own}.`
181
+ : stray.src === ""
182
+ ? `This <iframe> has neither src nor srcdoc, and is taken out of the ${it}: ${own}.`
183
+ : `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}.`, stray.index);
184
+ }
185
+ }
186
+ else {
187
+ const frame = /<(iframe|frame|object|embed)\b/iu.exec(content);
188
+ if (frame !== null) {
189
+ add("nested-frame", "error", `Remove the <${frame[1]?.toLowerCase()}>: nested frames and plugins are taken out of a ${it} and never run. Draw it inline instead.`, frame.index);
190
+ }
112
191
  }
113
192
  const write = /\bdocument\s*\.\s*write(?:ln)?\s*\(/u.exec(content);
114
193
  if (write !== null) {