@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.
- package/CHANGELOG.md +74 -0
- package/dist/bridge/bridge.d.ts +6 -0
- package/dist/bridge/bridge.js +5 -0
- package/dist/check/files.js +2 -0
- package/dist/check/lint.js +82 -3
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +17 -6
- package/dist/compile/policy.js +22 -7
- package/dist/config/capabilities.d.ts +16 -2
- package/dist/config/capabilities.js +8 -0
- package/dist/config/schema.d.ts +13 -0
- package/dist/config/validate.js +15 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/kit.d.ts +5 -0
- package/dist/conformance/kit.js +21 -0
- package/dist/conformance/limits.js +10 -5
- package/dist/conformance/probes.js +139 -28
- package/dist/conformance/served.js +25 -4
- package/dist/find/types.d.ts +83 -0
- package/dist/find/types.js +29 -0
- package/dist/find/validate.d.ts +17 -0
- package/dist/find/validate.js +82 -0
- package/dist/guide/guide.js +2 -1
- package/dist/guide/limits.js +8 -1
- package/dist/host/create-host.js +249 -4
- package/dist/host/pass-on.js +3 -2
- package/dist/host/types.d.ts +51 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.js +4 -1
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +6 -0
- package/dist/react/frame.d.ts +43 -0
- package/dist/react/frame.js +107 -3
- package/dist/react/view.js +2 -0
- package/dist/runtime/contract.d.ts +1 -1
- package/dist/runtime/contract.js +1 -1
- package/dist/server/files.js +4 -3
- package/dist/server/server.js +4 -1
- package/dist/shell/annotate.js +2 -95
- package/dist/shell/document.d.ts +3 -3
- package/dist/shell/document.js +5 -3
- package/dist/shell/find.d.ts +82 -0
- package/dist/shell/find.js +725 -0
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.d.ts +30 -1
- package/dist/shell/runtime.js +789 -105
- package/dist/shell/text.d.ts +17 -0
- package/dist/shell/text.js +140 -0
- package/docs/ADOPTING.md +103 -0
- package/docs/ARCHITECTURE.md +10 -3
- package/docs/DECISIONS.md +513 -1
- package/docs/DESIGN.md +40 -4
- package/docs/THREAT_MODEL.md +75 -6
- package/docs/insertion-entry-points.md +112 -0
- package/package.json +1 -1
- package/src/bridge/bridge.ts +7 -0
- package/src/check/files.ts +2 -0
- package/src/check/lint.ts +97 -8
- package/src/compile/policy.ts +23 -6
- package/src/config/capabilities.ts +13 -1
- package/src/config/schema.ts +13 -0
- package/src/config/validate.ts +16 -0
- package/src/conformance/kit.ts +22 -0
- package/src/conformance/limits.ts +10 -5
- package/src/conformance/probes.ts +149 -28
- package/src/conformance/served.ts +24 -4
- package/src/find/types.ts +86 -0
- package/src/find/validate.ts +101 -0
- package/src/guide/guide.ts +3 -1
- package/src/guide/limits.ts +9 -1
- package/src/host/create-host.ts +267 -4
- package/src/host/pass-on.ts +3 -2
- package/src/host/types.ts +52 -0
- package/src/index.ts +13 -0
- package/src/presets/presets.ts +15 -0
- package/src/react/frame.tsx +160 -1
- package/src/react/view.tsx +3 -0
- package/src/runtime/contract.ts +1 -1
- package/src/server/files.ts +8 -2
- package/src/server/server.ts +4 -1
- package/src/shell/annotate.ts +3 -95
- package/src/shell/document.ts +5 -3
- package/src/shell/find.ts +731 -0
- package/src/shell/plan.ts +7 -0
- package/src/shell/runtime.ts +792 -105
- package/src/shell/text.ts +140 -0
package/docs/DECISIONS.md
CHANGED
|
@@ -6260,7 +6260,7 @@ Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole
|
|
|
6260
6260
|
unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
|
|
6261
6261
|
after `<` draws neither).
|
|
6262
6262
|
|
|
6263
|
-
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted
|
|
6263
|
+
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131
|
|
6264
6264
|
|
|
6265
6265
|
**Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
|
|
6266
6266
|
which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
|
|
@@ -7019,3 +7019,515 @@ with one more frame ancestor, each turn the identity test red (the second, that
|
|
|
7019
7019
|
|
|
7020
7020
|
**Revisit when** a host needs the door's answer to differ from its content route's (it must not:
|
|
7021
7021
|
P125's invariant), or Porthole verifies a host's own tickets itself.
|
|
7022
|
+
|
|
7023
|
+
## P127 · 2026-11-01 · A frame's size is taken at most once an animation frame after its first, and only when it changed · Accepted
|
|
7024
|
+
|
|
7025
|
+
From the audit of 2026-10-29 (C-1): `resize` has no gate (`capabilities.ts`), and the host applied
|
|
7026
|
+
every `size-changed` a frame sent: `setHeight` (a reflow of the host's page, for a display not in
|
|
7027
|
+
fill mode) and a `resize` to its listeners (the React binding re-renders on each). Porthole's shell
|
|
7028
|
+
already measures once an animation frame and only when the height changed; content that speaks the
|
|
7029
|
+
protocol itself need not, and could send thousands a second. Its reach is the tab showing it: it
|
|
7030
|
+
reads nothing and touches no other display, but it can make that tab slow.
|
|
7031
|
+
|
|
7032
|
+
**Decision.** A run's first size is taken at once (until then its frame has no height of its own:
|
|
7033
|
+
waiting a frame for it left the frame 0 px tall a frame longer than before, which the leak suite saw
|
|
7034
|
+
on WebKit). After it, the host keeps the last size a frame sent and takes it on the next animation
|
|
7035
|
+
frame of the container's window (at once where there is none): one `setHeight` and one `resize` an
|
|
7036
|
+
animation frame at most, and none for a size the same as the last one taken (height and width). A
|
|
7037
|
+
run started again drops a size still waiting and takes the new run's first size at once. Not a rate:
|
|
7038
|
+
a rate would refuse an honest page's sizes during an animation, where taking the last one per frame
|
|
7039
|
+
loses nothing a person can see.
|
|
7040
|
+
|
|
7041
|
+
**Threat.** None re-opened; a gate added. `resize` still has no `defaultGates`: what bounds it is the
|
|
7042
|
+
host, for every config.
|
|
7043
|
+
|
|
7044
|
+
**Revisit when** a host needs every intermediate size (none does: the frame's height is all the host
|
|
7045
|
+
draws), or `resize` gets a gate of its own.
|
|
7046
|
+
|
|
7047
|
+
## P128 · 2026-11-01 · A page's own nested frames, opted into: `nestedFrames: "own"` · Accepted
|
|
7048
|
+
|
|
7049
|
+
xxchan (product owner, Raft #proj-workspace:04df2a51, message 14100c19, 2026-11-01): Raft's
|
|
7050
|
+
Artifacts should let a page have nested frames of its own, as Claude's Artifacts do. That means an
|
|
7051
|
+
`<iframe>` of a file of the same artifact (the same version's files, by a relative address) and a
|
|
7052
|
+
`srcdoc` frame load and run; frames of other sites stay blocked. He accepted the trade-off below
|
|
7053
|
+
(a nested frame is a realm of its own that the shell's hardening never reaches, so WebRTC is
|
|
7054
|
+
there; Claude has the same). It weakens a security default, so it is **opt-in per config**, and
|
|
7055
|
+
every other host keeps today's behaviour without changing anything. Amends P006 (the shell's
|
|
7056
|
+
defenses for channels a CSP doesn't cover: nested frames), P030 (guarded elements) and P082 (a set
|
|
7057
|
+
page's `frame-src`), for configs that opt in only.
|
|
7058
|
+
|
|
7059
|
+
**Decision.**
|
|
7060
|
+
- **The switch.** `PortholeConfig.nestedFrames: "none" | "own"` (`presets.*({ nestedFrames })`,
|
|
7061
|
+
a display kind's `options`). Absent or `"none"` is the default: the plan, the CSPs, the manual
|
|
7062
|
+
and the lint are the same as before. `"own"` is refused for url mode (no shell), for a nested page
|
|
7063
|
+
(`nested: true`, P111: its page is an opaque origin, which no `frame-ancestors` source matches, so
|
|
7064
|
+
none of its own files could be framed; not measured), and by `presets.liveWidget` (P079: no
|
|
7065
|
+
network of its own, and a child frame has WebRTC).
|
|
7066
|
+
- **The shell** (`plan.nestedFrames: "own"`, step 3 of the runtime) keeps an `<iframe>` (HTML
|
|
7067
|
+
namespace) with a `srcdoc` attribute (which wins over any `src`), or whose `src`, resolved by the
|
|
7068
|
+
platform's URL parser against the document's base, is under the version's own files' address
|
|
7069
|
+
(`plan.files.base`, P082). Everything else is removed as before: `frame`, `frameset`, `object`,
|
|
7070
|
+
`embed`, `portal`, `fencedframe`; an iframe without `src` or `srcdoc` (its `about:blank`), or of
|
|
7071
|
+
another path of the origin, another origin, `data:`, `blob:` or `javascript:`. The rule is one
|
|
7072
|
+
pure function (`OWN_FRAME`, spliced into the runtime as `HELD_BACK` is) that uses no prototype
|
|
7073
|
+
method content could replace, given the attributes and the base through the platform's own
|
|
7074
|
+
getters, kept before content runs. A frame that is kept can't become one that isn't: a change to
|
|
7075
|
+
it (an attribute, an IDL setter such as `src`, an attribute node or map, `toggleAttribute`) that
|
|
7076
|
+
would make it so first takes it out of the document, synchronously, as P030 does for a link or
|
|
7077
|
+
meta; the observer watches `src` and `srcdoc` as the backstop. Opaque frames and single pages
|
|
7078
|
+
have no files: there only `srcdoc` frames are kept.
|
|
7079
|
+
- **The CSP.** The frame's own policy is unchanged (`frame-src 'none'`): a `srcdoc` frame needs no
|
|
7080
|
+
source (P033 measured it loads under the embedding page's `frame-src 'none'`). A page of a file
|
|
7081
|
+
set opens `frame-src` to its version's files, the same source its scripts load from
|
|
7082
|
+
(`fileSetDirectives(config)`, `fileSetCspDirectives(…, opened)`): never another origin, never
|
|
7083
|
+
`'self'`, and not `child-src` (every engine Porthole supports reads frames from `frame-src`,
|
|
7084
|
+
P038). The embedding page's `frame-src` is unchanged.
|
|
7085
|
+
- **The server.** Below a file set's base, `frame-ancestors` names the page's own origin before
|
|
7086
|
+
the app's, so the set's pages frame its files (`frame-ancestors` names every ancestor). The
|
|
7087
|
+
ticket's answer, the shell's own pages and every other display keep the app's origins alone.
|
|
7088
|
+
Every page of a set is served in the shell (P081), so a page of the set in a child frame has its
|
|
7089
|
+
own shell: it takes messages only from the host origins, which its parent isn't. That child
|
|
7090
|
+
realm is same-origin with its parent, which is content, so the parent can reach the child's
|
|
7091
|
+
built-ins before the child's shell captures them; the shell's "captured before content runs"
|
|
7092
|
+
hardening (P129) is not guaranteed there, which is part of what opting in gives up (below).
|
|
7093
|
+
- **The lint.** `nested-frame` stays an error; under `"own"` it names only what never loads: a
|
|
7094
|
+
`<frame>`, `<object>` or `<embed>`, an iframe of another site (any scheme, `//`), of the origin's
|
|
7095
|
+
root (`/`), or with neither `src` nor `srcdoc`, and one with a relative `src` where there are no
|
|
7096
|
+
files. Its message says what does load. `lintFiles` looks an iframe's `src` up in the set.
|
|
7097
|
+
- **The manual** says which frames load ("an <iframe> of one of the page's own files (a relative
|
|
7098
|
+
src) or with srcdoc loads, set before it is added"), from the same config
|
|
7099
|
+
(`test/agreement.test.ts`).
|
|
7100
|
+
- **Raft** opts in on its artifact kind: `defineDisplays({ artifact: { preset: "artifact",
|
|
7101
|
+
options: { …, nestedFrames: "own" } } })` (`raftContentDisplays.ts` in the content Worker, and
|
|
7102
|
+
the web's `RAFT_ARTIFACT_DISPLAYS`, kept equal).
|
|
7103
|
+
|
|
7104
|
+
**Threat it re-opens** (for a config that opts in; accepted by xxchan).
|
|
7105
|
+
- **A child frame is a realm of its own, where the shell never ran** (steps 1, 2, 5 and 6 of the
|
|
7106
|
+
runtime): in a `srcdoc` frame, and in the `about:blank` document every new iframe starts with
|
|
7107
|
+
(which a same-origin page reaches in the task that added it), the WebRTC constructors are there,
|
|
7108
|
+
so content can reach any STUN or TURN server outside `connect-src` and carry what it holds out
|
|
7109
|
+
(`webrtc 'block'` stops it only in an engine that honors it); resource hints there are not
|
|
7110
|
+
removed (a `dns-prefetch` or `preconnect` reaches any host); `document.write` works. In a served
|
|
7111
|
+
page (`allow-same-origin`), its kept frames are its own origin, so it reaches their realms
|
|
7112
|
+
directly; in an opaque frame, a child is a new opaque origin (the sandbox is inherited) whose own
|
|
7113
|
+
script still runs. In short: a page that opts in has WebRTC, and egress is closed only as far as
|
|
7114
|
+
CSP closes it (P006's other walls are the CSP's, and they hold in the child: it inherits its
|
|
7115
|
+
parent's policy, or, a page of the set, is served with its own).
|
|
7116
|
+
- **The clipboard** (P051): the frame's `allow` denies `clipboard-read` and `clipboard-write`,
|
|
7117
|
+
and a child's features are its parent's at most, so the async Clipboard API stays closed. But
|
|
7118
|
+
the shell's guards don't run there: `execCommand("copy")` from a click in the child, and its
|
|
7119
|
+
copy and cut listeners, can put text the person didn't select on their clipboard
|
|
7120
|
+
(pastejacking), without `copyText` and the host's notice.
|
|
7121
|
+
- **Navigation.** A child frame's navigations, its own or its parent's of it, are governed by its
|
|
7122
|
+
embedding document's `frame-src` (the page's): a set's page frames only its version's path, an
|
|
7123
|
+
opaque frame nothing. So a child carries data out by navigating only to its own version's path,
|
|
7124
|
+
which reaches the host's content server, as a fetch there does (P082, P084). A child that
|
|
7125
|
+
navigates the page itself is stopped by the page's navigation guard and the app's `frame-src`,
|
|
7126
|
+
as before (P079). The sandbox is inherited: no popups, forms, downloads, modals or top
|
|
7127
|
+
navigation in a child.
|
|
7128
|
+
- **No new reach into the host.** A child is on the content's origin (or an opaque one); a
|
|
7129
|
+
file set's files now name that origin in `frame-ancestors`, which is the page's own: anything on
|
|
7130
|
+
it is already same-origin with the page.
|
|
7131
|
+
|
|
7132
|
+
**Why.** Pages people make with agents frame their own pages (a slide in a deck, a chart page in a
|
|
7133
|
+
report) and draw demos in `srcdoc` frames, which Claude's Artifacts run; removing them breaks those
|
|
7134
|
+
pages in Raft. Frames of other sites stay out: each would be a channel to its site.
|
|
7135
|
+
|
|
7136
|
+
**Rejected.** On by default (CLAUDE.md: never weaken a default silently; other hosts keep the
|
|
7137
|
+
strict rule). Running Porthole's shell in `srcdoc` children: the page reaches a child's realm
|
|
7138
|
+
before any script of ours could (its `about:blank`), so it would cost the page its frames' markup
|
|
7139
|
+
and buy nothing against content that wants out. An allowlist of other origins (as MCP Apps'
|
|
7140
|
+
`frameDomains`): not asked for, and each origin is a channel out.
|
|
7141
|
+
|
|
7142
|
+
**Tested** (written 2026-11-01, not yet run: run `pnpm check`, `pnpm test:leak` on Chromium, WebKit
|
|
7143
|
+
and Firefox, and `test:controls own-frame-rule` and `frame-guard,sync-guard` before release).
|
|
7144
|
+
Unit: `test/config.test.ts` (default off in every preset and plan; the refusals; a display kind's
|
|
7145
|
+
option reaches its served and opaque configs), `test/shell.test.ts` (`OWN_FRAME`'s rule, case by
|
|
7146
|
+
case; the plan), `test/files.test.ts` (a set's page frames its version's path only; served, its
|
|
7147
|
+
files' `frame-ancestors` and the ticket's; `lintFiles`), `test/check.test.ts` (the lint),
|
|
7148
|
+
`test/agreement.test.ts` (shell ↔ CSP ↔ manual, for a Raft-shaped and an inline config). Browser:
|
|
7149
|
+
probes `4.own-external` (another site, a relative `src` with no files, `data:`, a plugin, an empty iframe:
|
|
7150
|
+
none stays, the canary hears nothing), `4.own-turned` (a kept frame turned elsewhere by a setter,
|
|
7151
|
+
an attribute, a map, `toggleAttribute` leaves), `4.own-default` (the same frames, without the
|
|
7152
|
+
option: none runs), and `leak/served/files.spec.ts`'s "a page's own frames" (its own file, with its
|
|
7153
|
+
shell, a srcdoc and a frame it made run; another site, `/`, `/__porthole/d/…`, `../../`, plugins
|
|
7154
|
+
stay out; by default none). Negative control `own-frame-rule` (the rule keeps every iframe) fails
|
|
7155
|
+
`4.own-external` and `4.own-turned`; `frame-guard,sync-guard` fails the three
|
|
7156
|
+
probes that need a frame removed. Measured (CI, all three engines): under an opaque inline widget
|
|
7157
|
+
a `srcdoc` child's scripts don't run (it inherits the frame's nonce policy), so there the option
|
|
7158
|
+
keeps only frames that stay inert; on a served page (Raft's Artifacts) a `srcdoc` frame and a frame
|
|
7159
|
+
of its own files load and run. The served case's frames of elsewhere stand on two walls, each
|
|
7160
|
+
with its control: the shell's rule takes them out of the tree (`own-frame-rule` fails "stays out
|
|
7161
|
+
of the tree"), and the page's `frame-src` (its version's path; a `srcdoc` child inherits it)
|
|
7162
|
+
stops what a frame left there would load (`own-frame-rule,own-frame-src` fails "loads nothing"
|
|
7163
|
+
too; the rule alone out, `frame-src` holds it). A served page's shell and CSP are made in the
|
|
7164
|
+
served harness's process, so the two weakenings reach it there (the rule in `SERVED`, the header
|
|
7165
|
+
rewritten by the harness): an earlier run edited only the sources the browser loads, so neither
|
|
7166
|
+
reached a served page and the case looked held by "more than one wall" (CI, 9843f99: the combined
|
|
7167
|
+
control blind on Chromium). `navigate-guard` and `file-self` alone leave it held, by the rule.
|
|
7168
|
+
|
|
7169
|
+
Also accepted (Tenny's review): a same-origin `srcdoc` child has its own realm's untouched natives
|
|
7170
|
+
(`Document.prototype.write`, `Element.prototype.setHTMLUnsafe`, …) and can call them on the
|
|
7171
|
+
parent's document, so the parent shell's own hooks (the `document.write` lock, the declarative
|
|
7172
|
+
shadow DOM check) can be bypassed too, not only absent in the child. The CSP still closes the
|
|
7173
|
+
network the same way, so no way out is added beyond those named above, but "the parent page's
|
|
7174
|
+
guards stay whole" does not hold under `"own"`. A host's content origin must be the artifact's
|
|
7175
|
+
alone (Raft: `w-<uuid>.<content domain>`, one per artifact), since a file set's `frame-ancestors`
|
|
7176
|
+
names it.
|
|
7177
|
+
|
|
7178
|
+
**Revisit when** a host asks for frames of other origins (an allowlist, with its own channel
|
|
7179
|
+
accepted), a nested page (P111) needs frames of its own, Claude's Artifacts change their rule, or
|
|
7180
|
+
every engine closes WebRTC through CSP in every realm (then the trade-off is the clipboard's only).
|
|
7181
|
+
|
|
7182
|
+
## P129 · 2026-11-04 · The shell's guards call only built-ins captured before content runs · Accepted
|
|
7183
|
+
|
|
7184
|
+
**Decision.** Step 3's frame guard and its MutationObserver, the before-change backstop, and the
|
|
7185
|
+
synchronous insertion and HTML-parse guards (`strip`, `admit`, the insertion wrappers, `watched`,
|
|
7186
|
+
`beforeChange`, the `innerHTML`/`outerHTML`/`insertAdjacentHTML`/`execCommand` wrappers, the
|
|
7187
|
+
attribute-turn guards) read every built-in they use through references captured before any content
|
|
7188
|
+
runs, and call each one only through `callOf` — the DOM `nodeType`, `isConnected`, `parentNode`,
|
|
7189
|
+
`childNodes`, `shadowRoot`, `localName`, `namespaceURI`, `baseURI` getters; `querySelectorAll` (by
|
|
7190
|
+
node type), `remove`, `cloneNode`, `createTextNode`, `createElement(NS)`, `setAttributeNS`,
|
|
7191
|
+
`removeAttribute`, `attachShadow`, the kept insertion methods; the `NodeList` `length` getter;
|
|
7192
|
+
`WeakSet` `has`/`add`, `WeakMap` `get`/`set`; `MutationObserver.observe`; the `MutationRecord`
|
|
7193
|
+
`addedNodes`/`type`/`target` and `Attr` `name`/`namespaceURI`/`value`/`ownerElement` getters. It
|
|
7194
|
+
calls none of them as a member on an object content controls, and reaches none through
|
|
7195
|
+
`Function.prototype.call`/`apply`/`bind`: `callOf` is `Reflect.apply` itself, kept before content
|
|
7196
|
+
and invoked directly, so what the guard calls and with what is never seen by anything content later
|
|
7197
|
+
puts on `Function.prototype`. It also walks and decides without any replaceable `Array`/`Object`
|
|
7198
|
+
prototype method: live collections are indexed loops over the captured length getter (never
|
|
7199
|
+
`Array.from`, `for…of`, or the spread, whose `Array.prototype[Symbol.iterator]` is replaceable), the
|
|
7200
|
+
arguments it passes on are prototype-less lists given to `callOf`, and the positional decision in the
|
|
7201
|
+
insertion wrappers is a lookup built before content, not `Array.prototype.indexOf`. This extends
|
|
7202
|
+
P128's rule (which already read `matches`, `OWN_FRAME`'s inputs and the navigation getters this way)
|
|
7203
|
+
and P030's guard to every built-in the guard touches. Default behaviour is unchanged; no config,
|
|
7204
|
+
CSP, plan or manual moves.
|
|
7205
|
+
|
|
7206
|
+
**Why.** The guard inspects objects content controls, so it must not depend on anything content can
|
|
7207
|
+
replace first — a prototype method or getter, the global `Array.from` or array iterator,
|
|
7208
|
+
`Array.prototype.indexOf`, or `Function.prototype.apply`/`call`/`bind` — otherwise a page could make
|
|
7209
|
+
the guard overlook a frame-like element it must remove. The invariant — **the shell's guards call
|
|
7210
|
+
only built-ins captured before content runs** — is the property the fix establishes, and
|
|
7211
|
+
`test/shell.test.ts` asserts it generically (the guard captures each built-in once, `callOf` is
|
|
7212
|
+
`Reflect.apply` captured first, and the whole guard-and-wrapper region of the source makes no live
|
|
7213
|
+
`.call(`, `.apply(`, `.bind(`, `.querySelectorAll(`, `.remove()`, `Array.from(`, `.cloneNode(`,
|
|
7214
|
+
`.indexOf(`, `.forEach(` or `document.createTextNode(` call).
|
|
7215
|
+
|
|
7216
|
+
**Rejected.** Capturing only `matches` (P128's extent), or only the walk's getters and methods: the
|
|
7217
|
+
insertion wrappers still reached built-ins through `.apply`, `.call` and `Array.prototype.indexOf`,
|
|
7218
|
+
which content can replace to the same end. Leaving the walk on `Array.from`/`for…of`/the spread:
|
|
7219
|
+
`Array.from` and `Array.prototype[Symbol.iterator]` are replaceable too. Checking a value and then
|
|
7220
|
+
forwarding the original argument: the platform reads the argument again, so a value that converts
|
|
7221
|
+
to a benign string when checked and a guarded one when the platform reads it would slip past; each
|
|
7222
|
+
inspected name or value is pinned to a single conversion (`once`) and that reading is both checked
|
|
7223
|
+
and forwarded.
|
|
7224
|
+
|
|
7225
|
+
**Where this does not reach.** The invariant is for a shell in its own realm, which runs first
|
|
7226
|
+
there. Under `nestedFrames: "own"` (P128), a kept child frame is a realm the shell shares with
|
|
7227
|
+
content that can reach it first: a page of a set in a child frame is same-origin with its parent,
|
|
7228
|
+
and the parent is content, so it can touch that realm's built-ins before the child's shell captures
|
|
7229
|
+
them. There the "captured before content runs" ordering is not guaranteed — as P128 records, a
|
|
7230
|
+
config that opts in gives up the shell's defenses inside its own frames and stands on the CSP there.
|
|
7231
|
+
This fix changes nothing about that trade-off; it holds for the top-level shell every config has.
|
|
7232
|
+
|
|
7233
|
+
**Tested** (written 2026-11-04; run `pnpm check` and `pnpm test:leak` on Chromium, WebKit and
|
|
7234
|
+
Firefox before release). Unit: `test/shell.test.ts` (the capture table and the no-live-call
|
|
7235
|
+
invariant). The leak suite's frame and hint probes (item 4, the served "own" cases) stand as the
|
|
7236
|
+
behavioural check; a probe that replaces each captured built-in before inserting a nested frame,
|
|
7237
|
+
with its negative control, belongs with the leak suite when the egress-probe harness is next
|
|
7238
|
+
extended.
|
|
7239
|
+
|
|
7240
|
+
**Revisit when** a new built-in is used anywhere in the guard or a new guarded channel is added
|
|
7241
|
+
(capture it the same way and extend the invariant test), or the leak suite gains the
|
|
7242
|
+
per-built-in replacement probe.
|
|
7243
|
+
|
|
7244
|
+
## P130 · 2026-11-04 · Every insertion entry point is guarded, every subtree producer strips, and by default no frame-like element can be made · Accepted
|
|
7245
|
+
|
|
7246
|
+
**Decision.** The shell's frame guard (step 3, P030, P129) holds one invariant: **every insertion
|
|
7247
|
+
entry point is guarded, every subtree producer strips before returning, and under the default
|
|
7248
|
+
configuration no frame-capable element can exist in a content-reachable tree.** The list of entry
|
|
7249
|
+
points and how each is guarded is [insertion-entry-points.md](insertion-entry-points.md);
|
|
7250
|
+
`test/shell.test.ts` checks every row against the runtime.
|
|
7251
|
+
- **Insertion.** Every DOM method or setter that connects a node runs its node arguments through
|
|
7252
|
+
the same synchronous `admit`/`strip`, whatever the parent (connected or detached), on built-ins
|
|
7253
|
+
captured before content runs and called through `callOf` (P129): the P030 methods, `moveBefore`
|
|
7254
|
+
where an engine has it, `HTMLSelectElement.add` and `HTMLOptionsCollection.add`, and the
|
|
7255
|
+
`document.body` and `HTMLTableElement` `tHead`/`tFoot`/`caption` setters (a refused value refuses
|
|
7256
|
+
the set: a setter has no harmless stand-in).
|
|
7257
|
+
- **Producers.** Every API that hands content a subtree it can insert later strips it
|
|
7258
|
+
synchronously before it returns: `DOMParser.parseFromString` (every MIME type),
|
|
7259
|
+
`Document.parseHTMLUnsafe` and `Document.parseHTML`, `HTMLTemplateElement.content` (and what a
|
|
7260
|
+
template's `innerHTML` fills), `DOMImplementation.createHTMLDocument`/`createDocument`,
|
|
7261
|
+
`Range.createContextualFragment`, `XSLTProcessor.transformToFragment`/`transformToDocument`,
|
|
7262
|
+
`XMLHttpRequest` `responseXML` and a document `response`, `Document.importNode` (the clone) and
|
|
7263
|
+
`adoptNode` (the node; one that is itself frame-like is refused). `strip` enters what
|
|
7264
|
+
`querySelectorAll` doesn't: each template's content and each open shadow root's tree, at any
|
|
7265
|
+
depth (a work list, not recursion).
|
|
7266
|
+
- **Creation, under the default configuration.** `createElement` and `createElementNS` refuse a
|
|
7267
|
+
`FRAMES` name (any case, any namespace, the local name after a prefix included) with a neutral
|
|
7268
|
+
error, as `document.write` is refused; so does `CustomElementRegistry.define` with an `extends`
|
|
7269
|
+
naming one (its constructor would make one). With the parsers stripped, nothing else makes a
|
|
7270
|
+
frame-like element (`cloneNode` and `importNode` copy trees that hold none; `Option`, `Image`
|
|
7271
|
+
and `Audio` make their own kinds), so the indexed setters that can't be wrapped
|
|
7272
|
+
(`select[i] = …`, `options[i] = …`, `length`) have nothing to connect. Under `nestedFrames:
|
|
7273
|
+
"own"` (P128) creation stays open and the guards decide when a frame is connected or changed.
|
|
7274
|
+
The manual says so from the same config ("making one in script throws", default only).
|
|
7275
|
+
- **Markup methods the shell doesn't know** (one a later engine adds, on Element, ShadowRoot,
|
|
7276
|
+
Document, DocumentFragment or Range, with `HTML` in its name) are refused.
|
|
7277
|
+
- **Editing.** A `beforeinput` listener the shell registers before content runs (on `window`,
|
|
7278
|
+
capturing, with the platform's own getters) cancels a paste, a drop, a replacement or a yank
|
|
7279
|
+
(`insertFromPaste`, `insertFromPasteAsQuotation`, `insertFromDrop`, `insertReplacementText`,
|
|
7280
|
+
`insertFromYank`) whose data carries any type but `text/plain`, and inserts its plain text
|
|
7281
|
+
through the editor's `insertText`, which carries no markup. Only the browser's own events are
|
|
7282
|
+
acted on. Composition events can't be cancelled and carry text alone.
|
|
7283
|
+
- **Read once.** Every value a guard inspects and forwards passes as it is only if it is a string,
|
|
7284
|
+
number, boolean, bigint, `null` or `undefined` itself (`value === undefined`); anything else is
|
|
7285
|
+
converted once, and that reading is both checked and forwarded; a symbol, or a conversion that
|
|
7286
|
+
throws, is refused (`PASSES_AS_IS`, `ONCE`). `attachShadow`'s `init` is read field by field,
|
|
7287
|
+
once, into a fresh object with no prototype, which is all the platform is given.
|
|
7288
|
+
|
|
7289
|
+
**Why.** A guard that covers most entry points is as strong as the one it doesn't: the invariant
|
|
7290
|
+
is stated over all of them, producers included, so a subtree can't reach the document by a route
|
|
7291
|
+
the list doesn't name. Refusing creation makes the invariant hold for trees content builds by hand
|
|
7292
|
+
too, where no producer is involved. Under the default configuration no page needs a frame-like
|
|
7293
|
+
element: the lint already reports every one (`nested-frame`), and the guard removes them.
|
|
7294
|
+
|
|
7295
|
+
**Rejected.** Covering the indexed setters by stripping at the producers alone: a tree built by
|
|
7296
|
+
hand is no producer's. Replacing a refused element with a placeholder at creation: a page would
|
|
7297
|
+
get an element that silently isn't what it asked for; a refusal says why. Letting editing insert
|
|
7298
|
+
markup and relying on the observer: the editor connects it before the observer's microtask.
|
|
7299
|
+
|
|
7300
|
+
**Under `nestedFrames: "own"`** the creation refusal doesn't apply, and P128's trade-offs stand.
|
|
7301
|
+
|
|
7302
|
+
**Tested** (written 2026-11-04, not yet run: run `pnpm check`, `pnpm test:leak` on Chromium,
|
|
7303
|
+
WebKit and Firefox, and `test:controls` before release). Unit: `test/shell.test.ts` (every entry
|
|
7304
|
+
of the list found in the runtime, the doc's rows and statuses matching; `PASSES_AS_IS` and `ONCE`
|
|
7305
|
+
in isolation, fail-closed cases included; the creation refusal only under the default
|
|
7306
|
+
configuration), `test/agreement.test.ts` (the manual's sentence, default only). The `sync-guard` negative control also takes out the creation refusal and the
|
|
7307
|
+
producers' strips. The conformance probes that build a frame-like element with `createElement`
|
|
7308
|
+
(4.light-dom, 4.sync-realm, the shadow-root and plugin cases, 4.own-default, 7.base-plugins,
|
|
7309
|
+
14.shell, and the served egress case) count a refusal at creation under the default configuration
|
|
7310
|
+
as the guard holding, and record it ("refused at creation"); with the refusal taken out (the
|
|
7311
|
+
`sync-guard` control) they build the element as before.
|
|
7312
|
+
|
|
7313
|
+
**Revisit when** an engine adds an insertion or parsing entry point (add it to the list, the
|
|
7314
|
+
runtime and the test), the default configuration is to allow frames, or the leak suite's probes
|
|
7315
|
+
cover each row.
|
|
7316
|
+
|
|
7317
|
+
## P131 · 2026-11-04 · Find in page: the host's find bar, the shell's matches in a layer of its own (`find`) · Accepted
|
|
7318
|
+
|
|
7319
|
+
Raft's task: an Artifact viewer's find bar, like the thread panel's "search this thread": a query
|
|
7320
|
+
box, previous and next, a "3/12" count, highlights, Escape closes. The host can't read a display's
|
|
7321
|
+
text (its frame is another origin, opaque or the content's own), and the browser's own find gives
|
|
7322
|
+
it no count, no UI of its own and no say over Cmd+F. Only the shell, in the frame, can find the
|
|
7323
|
+
words and draw over them, so Porthole provides that part; the bar is the host's. Amends P118: the
|
|
7324
|
+
React handle holds `find` and `clearFind` beside `clearSelection`. Holds to P129 and P130: the find
|
|
7325
|
+
runtime calls only built-ins captured before content runs, and its layer's nodes go in only
|
|
7326
|
+
through the guarded insertion methods (**Drawing**, below).
|
|
7327
|
+
|
|
7328
|
+
**Decision.**
|
|
7329
|
+
- **A capability, `find`**, declared per config (`capabilities: { find: {} }`; in no preset by
|
|
7330
|
+
default; Raft opts in on its artifact kind). Served as an event, as `annotate` is; its default
|
|
7331
|
+
gate is a rate (120 a minute) on what the frame says unasked. The manual's entry tells the agent
|
|
7332
|
+
the person may search the page's words with the app's find bar (keep them as text) and that a
|
|
7333
|
+
page handling Cmd+F itself keeps the key (`test/agreement.test.ts` covers it). A url-mode app has
|
|
7334
|
+
no shell and declares no capability: find there is the browser's.
|
|
7335
|
+
- **The protocol** (own-prefixed, P002; `FIND_METHODS`):
|
|
7336
|
+
- `porthole/find.query`, host → frame, a **request**: `{ query, direction?: "next" | "prev" |
|
|
7337
|
+
"none", caseSensitive?: boolean }`, answered with `{ total, active, capped?: true, rect? }`:
|
|
7338
|
+
how many matches (at most `FIND_LIMITS.matches`, 1,000; `capped`: it stopped looking, there may
|
|
7339
|
+
be more), the current one from 1 (0 for none), and the current one's box in the frame's
|
|
7340
|
+
viewport once it was scrolled into view. A new query makes current the first match at or after
|
|
7341
|
+
the viewport's top (`prev`: the one before it); the same query with `next` or `prev` moves on
|
|
7342
|
+
from the current one by its place, wrapping; `none` keeps it. An empty query (or only spaces)
|
|
7343
|
+
clears and answers `{ total: 0, active: 0 }`. A query that a later query or a clear
|
|
7344
|
+
superseded before the shell ran it is answered with an error (`-32800`, "superseded by a later
|
|
7345
|
+
query"), which the host makes `"unsupported"` as it does any error (**Only the latest**,
|
|
7346
|
+
below).
|
|
7347
|
+
- `porthole/find.clear`, host → frame: highlights gone, query forgotten.
|
|
7348
|
+
- `porthole/find.handled { handled }`, host → frame: whether the host draws its own find bar.
|
|
7349
|
+
- `porthole/find.requested {}`, frame → host: the person pressed the shortcut (below).
|
|
7350
|
+
- `porthole/find.updated { total, active, capped? }`, frame → host: the matches changed while a
|
|
7351
|
+
query is shown (the content changed), at most once a second.
|
|
7352
|
+
- **Matching** (`FIND_MATCH`, one pure function spliced into the runtime, unit-tested): over
|
|
7353
|
+
annotations' text index (`TEXT_INDEX`, moved out of the annotation runtime and spliced into both:
|
|
7354
|
+
the body's text nodes, without scripts, styles, noscript and templates; the same text and
|
|
7355
|
+
offsets as before, now read through built-ins captured before content runs, P129).
|
|
7356
|
+
Case-insensitive unless asked (`RegExp` with `iu`: Unicode simple case folding, offsets kept),
|
|
7357
|
+
loose about spacing as annotations' `squash` is (trimmed; a run of white space in the query
|
|
7358
|
+
matches any run in the text), every other character literal (no pattern syntax reaches the
|
|
7359
|
+
expression). A match counts only if it has a box (text that is drawn: not `display: none`, not
|
|
7360
|
+
a closed `<details>`). At most 1,000 kept, 10,000 looked at, a query of at most 256 code units
|
|
7361
|
+
(the host refuses longer, the shell cuts).
|
|
7362
|
+
- **Drawing**: a layer of the shell's own, a closed shadow root over the content with the same
|
|
7363
|
+
forced inline style as annotations' layer (one constant, a test holds them equal), apart from
|
|
7364
|
+
it; a match is a light warm fill with a thin edge, the current one stronger with a ring (neither
|
|
7365
|
+
looks like a comment's yellow underline). Boxes from `Range.getClientRects`, only for matches in
|
|
7366
|
+
view, redrawn at each scroll and resize (an animation frame), and found again once a run of
|
|
7367
|
+
changes settles (150 ms quiet, at most a second late), the current match kept by its place. The
|
|
7368
|
+
current match is brought into view, centred, in its scrolling ancestors first (innermost first,
|
|
7369
|
+
`overflow` auto, scroll or overlay that overflows), then in the window; instantly. The selection
|
|
7370
|
+
is never touched (annotations would report it as the person's).
|
|
7371
|
+
- **Only the latest** (`FIND_LATEST`, one pure function spliced into the runtime, unit-tested). A
|
|
7372
|
+
search is synchronous, and on a large page long (measured: 150-730 ms on a page of 30,000
|
|
7373
|
+
spans), so a bar that asks at every key queued a search per key (50 queries at once took 14-22
|
|
7374
|
+
s). A query that comes while none waits, and not within 16 ms of the end of the last one run, is
|
|
7375
|
+
run at once, answered before any content's listener could answer it, as before. Otherwise it
|
|
7376
|
+
waits for the next task, after the messages already queued; a later query supersedes it, and a
|
|
7377
|
+
clear drops it, each answering it with the superseded error at once. A burst is so at most two
|
|
7378
|
+
searches: the one running and the latest. What a waiting query will search is read from the
|
|
7379
|
+
host's message when it comes (each field once, as an own property) and kept as those values,
|
|
7380
|
+
never read from the message again (P129). The host sends only the latest of the queries asked
|
|
7381
|
+
while a frame loads, and answers the others `"unsupported"`.
|
|
7382
|
+
- **Built-ins and insertion (P129, P130).** Every built-in the find runtime and the text index call
|
|
7383
|
+
once content may have run is captured before content runs and called only through `callOf`:
|
|
7384
|
+
`createRange`, `createTreeWalker` and the walker's `nextNode`, the `nodeType`, `localName`,
|
|
7385
|
+
`nodeValue`, `parentElement`, `body` and `documentElement` getters, `Range`'s `setStart`,
|
|
7386
|
+
`setEnd`, `collapse`, `comparePoint`, `startContainer` and boxes, `DOMRectList`'s and `DOMRect`'s
|
|
7387
|
+
getters, the sizes, `getComputedStyle` and `getPropertyValue`, `scrollBy`, the `style` getter and
|
|
7388
|
+
`cssText` accessors, the `className` and `nonce` setters, `Map`'s `set`/`get`/`has`, `RegExp` and
|
|
7389
|
+
its `exec`, the timers, `postMessage`, `MutationObserver.observe` and the `MutationRecord`
|
|
7390
|
+
getters, the `MessageEvent` `data`/`origin`/`source` getters, `KeyboardEvent`'s getters, and the
|
|
7391
|
+
platform's `preventDefault`. No live `.call`, `.apply` or `.bind`, no `Array`/`Object` prototype
|
|
7392
|
+
method (`map`, `concat`, `indexOf`, `push`, `for…of`, `Object.assign`) and no `Math` function:
|
|
7393
|
+
its lists are the shell's prototype-less ones (`listOf`, `pushTo`, also given to `FIND_MATCH`),
|
|
7394
|
+
its lookups and answers objects with no prototype. What it reads from the host's message (the
|
|
7395
|
+
event's fields, the request's own properties) is read once, and only a string, number or boolean
|
|
7396
|
+
is acted on; a box's numbers are read once and only numbers are used. The layer's nodes are made
|
|
7397
|
+
and inserted only through the shell's guarded methods, which step 3 wrapped before the find
|
|
7398
|
+
runtime runs (it is spliced after the guard and takes them then): `createElement` (A21 of
|
|
7399
|
+
[insertion-entry-points.md](insertion-entry-points.md)), `attachShadow` (A19), `appendChild`
|
|
7400
|
+
(A1), `replaceChildren` on an element and a shadow root (A2), and the `textContent` setter
|
|
7401
|
+
(A5). It inserts nothing into the content's own trees, and its inline styles go through CSSOM
|
|
7402
|
+
(`cssText`), not a `style` attribute.
|
|
7403
|
+
- **The shortcut**: Cmd+F on Apple's platforms (`navigator.platform`, read before content runs),
|
|
7404
|
+
Ctrl+F elsewhere, no Alt or Shift (`FIND_SHORTCUT`, unit-tested; on a layout whose letters aren't
|
|
7405
|
+
Latin, the key in F's place). Read in a listener on the window as the key bubbles, after the
|
|
7406
|
+
page's own: only while the host said `handled`, only a trusted key, and only one the page didn't
|
|
7407
|
+
take (`defaultPrevented`: a page with a find of its own keeps its key). Then the shell cancels
|
|
7408
|
+
the browser's find and says `requested`. Otherwise the key is left alone: a host without its own
|
|
7409
|
+
bar keeps the browser's.
|
|
7410
|
+
- **The host** (`display.find`): `query(query, { direction, caseSensitive })` resolves with the
|
|
7411
|
+
checked answer (its box clamped to the frame's viewport, P104) or `"unsupported"`: a config
|
|
7412
|
+
without `find`, an error (an older shell answers `-32601`, "isn't offered here"; the shell's own
|
|
7413
|
+
fallback now leaves `porthole/find.query` to the find runtime where it is declared), a malformed
|
|
7414
|
+
answer, or none within `FIND_LIMITS.timeoutMs` (3 s) of the frame running (asked before, the
|
|
7415
|
+
load's time too). A query too long, or options that aren't these, reject with a `TypeError`.
|
|
7416
|
+
`clear()`; `takeShortcut(take)` sends `handled`. The shortcut is kept and given to every frame
|
|
7417
|
+
the display runs. The query holds only for the content it was asked of: every new run (a
|
|
7418
|
+
`reload()`, a restart after the content navigated its frame away, so a new location) and other
|
|
7419
|
+
content (`setContent` with content that doesn't continue what was given; more of a streamed
|
|
7420
|
+
page does) forget it, answer what waits `"unsupported"` and, for other content, clear the frame
|
|
7421
|
+
running now. A new page is so never searched with the last one's query (not even unheard: the
|
|
7422
|
+
shell's scrolling and its layer would tell the page which of its words matched) unless the host
|
|
7423
|
+
asks again; the host clears its find bar then (ADOPTING).
|
|
7424
|
+
Events: `findRequested` (taken only while the host takes the shortcut and the platform says the
|
|
7425
|
+
page's focus is in the frame, or can't tell) and `findUpdated` (taken only while a query is
|
|
7426
|
+
shown); both checked (`parseFindReport`) and through the bridge's rate.
|
|
7427
|
+
- **React**: the handle (`PortholeFrameHandle`, P118) adds `find(query, options)` and
|
|
7428
|
+
`clearFind()`: with no display running, `"unsupported"`, and the query is kept, with what the
|
|
7429
|
+
frame showed when it was asked (`findScopeOf`: the config, instance with its version,
|
|
7430
|
+
declaration, viewer and generation by value, the document, the content). A display made later
|
|
7431
|
+
that shows the same (the frame neared the screen again; the content continued) finds it again
|
|
7432
|
+
and tells `onFindUpdated`; any other (`sameFindScope` false: another source, document, version
|
|
7433
|
+
or config, a new generation, content that doesn't continue it) forgets it. A refused query is `onHostError`
|
|
7434
|
+
(kind `"find"`) and `"unsupported"`, never a rejection. `onFindRequested`, given, makes the
|
|
7435
|
+
frame's shortcut the host's (`takeShortcut(true)`); `onFindUpdated` hears updates.
|
|
7436
|
+
|
|
7437
|
+
**Why a capability, gated per config** (THREAT_MODEL §7). Find gives content no power: nothing it
|
|
7438
|
+
can call, nothing of the host's it can read. But:
|
|
7439
|
+
1. The query is the person's words, typed in the host's own UI, and it is posted into the content's
|
|
7440
|
+
realm, where the page can read it (each keystroke, for a bar that searches as the person
|
|
7441
|
+
types). A page with a way out (an MCP App's `connectDomains`, S5; egress a host opened; the
|
|
7442
|
+
runtime's `db` and other carriers, `mayPassOn`) can send what the person searched for to its
|
|
7443
|
+
author. A host opts in per config, knowing which displays may learn that.
|
|
7444
|
+
2. The shell carries nothing the config doesn't declare (PRINCIPLE 4): a host that upgrades gets
|
|
7445
|
+
no new listener or message in its existing displays.
|
|
7446
|
+
3. What the frame says unasked goes through the bridge, with a rate, as annotations' reports do.
|
|
7447
|
+
|
|
7448
|
+
**Accepted exposure.** The page can read every query the host sends it: the search runs in the
|
|
7449
|
+
page's document, so the query is in the page's realm (and, without reading the message, the
|
|
7450
|
+
shell's scrolling and its layer show the page which of its words matched). This was accepted by
|
|
7451
|
+
the product owner, with hosts sending queries on a pause or Enter rather than at every key, which
|
|
7452
|
+
limits what the page sees of the person's typing (ADOPTING).
|
|
7453
|
+
Accepted by xxchan (product owner, Raft #proj-workspace:e56d96e4, message 3d68e461, 2026-11-04):
|
|
7454
|
+
the page can read the queries sent to it; hosts send them on a pause or Enter, only while their
|
|
7455
|
+
find bar is open.
|
|
7456
|
+
|
|
7457
|
+
**Threat.** No wall moves: no CSP, sandbox, `allow`, egress or storage changes, nothing secret
|
|
7458
|
+
enters the frame, and annotations behave as before (the text index moved into a shared constant,
|
|
7459
|
+
spliced in the same place, and now reads through captured built-ins, P129). New on the message
|
|
7460
|
+
boundary:
|
|
7461
|
+
- *What content learns*: the query, whether it is case-sensitive, each move (next, previous), when
|
|
7462
|
+
the bar opens and closes, and whether the host draws its own bar.
|
|
7463
|
+
- *What content can say*: any count, any current match, any box inside its frame (clamped), and
|
|
7464
|
+
`updated` while a query is shown. All of it the content's word: a find bar's numbers, never a
|
|
7465
|
+
fact about the content. `requested` it can say at will, but the host takes it only with the
|
|
7466
|
+
page's focus in the frame (the web platform's focus guard: a press on the frame or a Tab put it
|
|
7467
|
+
there, P109). Without that rule a page could open the host's bar, which takes focus, while the
|
|
7468
|
+
person types in the host's composer, and their next keys would go into the bar, and so into the
|
|
7469
|
+
frame as queries. With the person already in the frame, the page has their keys anyway, and a bar
|
|
7470
|
+
opening moves the keyboard out of it. Negative control `find-requested-focus`.
|
|
7471
|
+
- *What content can always do*: hide, cover or move the layer, change its words so the count
|
|
7472
|
+
changes, keep the key from the shell (its own `preventDefault`, as intended; or stopping the
|
|
7473
|
+
event, which leaves the browser's find to open), patch built-ins to reach the closed shadow root
|
|
7474
|
+
(as annotations' layer, P105), or make the search dear by its size (linear in its text, bounded
|
|
7475
|
+
by the limits above; found again at most once a second while it changes; in an opaque frame that
|
|
7476
|
+
shares the host's process that time is the host's too, as annotations' is, §5); a burst of
|
|
7477
|
+
queries costs at most two searches (**Only the latest**).
|
|
7478
|
+
|
|
7479
|
+
**Rejected.**
|
|
7480
|
+
- The CSS Custom Highlight API (as P053 and P104 rejected it for marks): `CSS.highlights` is the
|
|
7481
|
+
content's registry, to read, clear or restyle; the shell's drawing must be its own.
|
|
7482
|
+
- `window.find()` or the browser's find: non-standard or out of reach, no count, and it moves the
|
|
7483
|
+
selection, which annotations report as the person's.
|
|
7484
|
+
- Always on, ungated: every display's page would get the person's search terms after an upgrade, a
|
|
7485
|
+
third-party MCP App's (S5) included.
|
|
7486
|
+
- A find bar drawn in the frame: the content could cover or fake it; the host's own UI is the
|
|
7487
|
+
point.
|
|
7488
|
+
- Taking Cmd+F wherever `find` is declared: a host without a bar of its own would lose the
|
|
7489
|
+
browser's find. And a notification only (no request): an older shell couldn't say it doesn't
|
|
7490
|
+
know it, and the host would wait out a timeout for every query.
|
|
7491
|
+
- The host searching text the page sends it: a new channel for the page's words into the host's
|
|
7492
|
+
UI, and its word of its own text anyway.
|
|
7493
|
+
|
|
7494
|
+
**Not covered** (each a gap a host may hear about): text in open shadow roots, in a page's own
|
|
7495
|
+
nested frames (P128) or in form fields' values, words in images or a canvas (the manual says to keep
|
|
7496
|
+
them as text), and words split across elements with no space between in the text (a table's
|
|
7497
|
+
cells: "foo bar" doesn't find `<td>foo</td><td>bar</td>`). Escape and Cmd+G in the frame are the
|
|
7498
|
+
page's: the host's bar closes and moves on from its own UI.
|
|
7499
|
+
|
|
7500
|
+
**Tested** (written 2026-11-04, not yet run: the authoring machine runs no tests; run `pnpm check`,
|
|
7501
|
+
`pnpm test:leak` on Chromium, WebKit and Firefox, and `pnpm --filter @botiverse/porthole
|
|
7502
|
+
test:controls find-requested-focus` before merging). Unit, `test/find.test.ts`: the matching
|
|
7503
|
+
(case, Unicode folding, spacing, literal syntax, no overlaps, the limits, `keep`, ten times the most
|
|
7504
|
+
looked at), the shortcut rule, the host's checks (`parseFindResult`, `parseFindReport`,
|
|
7505
|
+
`checkFindQuery`), only the latest query (`FIND_LATEST`: at once when nothing is queued, a burst
|
|
7506
|
+
of fifty as two searches with the rest answered superseded, a clear dropping what waits, its
|
|
7507
|
+
splice reading a request once), the shell (the runtime only where declared, beside annotations' with the text
|
|
7508
|
+
index in both, a plain script, the built-ins taken before the message listener, no live call or
|
|
7509
|
+
replaceable prototype method in the find runtime or the text index and the layer inserted through
|
|
7510
|
+
the guarded methods (P129, P130), the same layer style, no Highlight API, the fallback leaving the
|
|
7511
|
+
request alone), `createHost` over a stand-in
|
|
7512
|
+
platform (asked once the frame ran, its own id only, the box clamped; `-32601`, malformed and no
|
|
7513
|
+
answer are `"unsupported"`; nothing without `find`; an empty query clears; a query too long
|
|
7514
|
+
rejects; the shortcut sent to every frame, `requested` only while taken and with the page's focus;
|
|
7515
|
+
`updated` only while a query is shown; a reload, a restart after a navigation away and other
|
|
7516
|
+
content forget the query, content continued keeps it; a query cleared before the frame ran
|
|
7517
|
+
answers nothing; a query waiting when its frame stops is `"unsupported"` and never sent to the
|
|
7518
|
+
next frame; of the queries asked while the frame loads only the latest is sent; a superseded
|
|
7519
|
+
answer is `"unsupported"`; a destroyed display answers `"unsupported"`), the React handle's scope
|
|
7520
|
+
(`findScopeOf`, `sameFindScope`: the same content again or continued, by value, versus another
|
|
7521
|
+
generation, content, document, config, viewer, source or version), and the bridge (an event, a
|
|
7522
|
+
refusal, the rate). `test/agreement.test.ts`: a case
|
|
7523
|
+
with `find`, and Raft's shape with it. `test/react-ssr.test.ts`: the handle's and props' types.
|
|
7524
|
+
Browser, `leak/find.spec.ts` (three engines): highlights in the closed layer, next and previous into
|
|
7525
|
+
view (a scrolling box too), the box, case, clear; a change found again and told; a page's own query
|
|
7526
|
+
message ignored; the shortcut the browser's until taken, then the host's, a page's own find keeping
|
|
7527
|
+
it; and the hostile page's `requested` while the person types in the host's composer (the control's
|
|
7528
|
+
probe, with its positive control: taken with the person in the frame).
|
|
7529
|
+
|
|
7530
|
+
**Revisit when** a host needs matches in open shadow roots or a page's own frames, the person's
|
|
7531
|
+
Escape or Cmd+G in the frame should reach the host's bar, a host searches as the person types and
|
|
7532
|
+
wants the page not to see each keystroke (debounce in the host first), or engines give a frame a
|
|
7533
|
+
highlight registry content can't reach.
|
package/docs/DESIGN.md
CHANGED
|
@@ -990,6 +990,7 @@ for that to lapse and click with raw input.
|
|
|
990
990
|
| Files: the version's own path in the CSP (P082) | `fileSetCspDirectives`: `<origin><base>` (tab) or `<origin>/__porthole/f/` (frame) in the seven loading directives; never `'self'` | `leak/served/files.spec.ts`: a page loads no other version's files; a way out past the base is blocked | `file-self` → those two cases (another version's data and module load; `%2e%2e` past the base reaches the server; all three) |
|
|
991
991
|
| Files in a frame: access in the path (P083) | the ticket's answer is the entry; `/__porthole/f/<AES-GCM sealed session>/`; `history.replaceState` before anything loads; the host's check per file; an address opens on its own for an hour (then only the running page's own same-origin loads, till the session ends), renewed by the shell; reported as `./`, never whole | `test/files.test.ts` (sealed: no viewer or subject in it; another origin, a tampered or ended one: 401; revoked: 403; its hour, the page's own loads after it, renewal; redaction); `test/workers.test.ts` (workerd); every framed case of `leak/served/files.spec.ts` on WebKit (no cookie in frames), its reports never naming the address, its renewal under a moved clock | — |
|
|
992
992
|
| Files: pages navigate within the set (P084, P098) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating`, and the page it opened says so as it arrives, each naming its version; the host takes the next load as that page, or the load the notice came after: a load no notice for the mounted version explained waits `LATE_NOTICE_MS` holding the frame (nothing it says reaches the display), then starts it again | `leak/served/files.spec.ts`: a link opens another page in the frame, the display goes on, also with the leaving page's notice dropped or every notice late; a non-page file, `/`, `/__porthole/d/…` never open; `test/pages-of-set.test.ts`: another version's notice or a hello first restarts at once, nothing is answered during the wait | `navigate-guard` → the three link cases, "opens nothing else" and the sealed-address reports case (all three; the last measured failing before P098 too) |
|
|
993
|
+
| A page's own nested frames, opt-in (P128) | `nestedFrames: "own"` (off by default): the shell keeps an iframe with `srcdoc` or whose `src` is under `files.base` (`OWN_FRAME`, through the platform's getters) and removes every other frame and plugin as before; a kept frame leaves before a change would point it elsewhere (P030's guard; the observer watches `src`/`srcdoc`); a set's page has `frame-src` its version's path, its files `frame-ancestors` its own origin and the app's; refused for url mode, nested pages, live widgets. Inside a child frame none of the shell's defenses run (accepted) | `4.own-external`, `.own-turned`, `.own-default` (opaque: a srcdoc child's scripts don't run there, measured); `leak/served/files.spec.ts` "a page's own frames": its file (with its shell), a srcdoc and a made frame run; another site, `/`, `/__porthole/d/…`, `../../`, plugins stay out; by default none runs; `test/shell.test.ts`, `test/files.test.ts`, `test/check.test.ts` | `own-frame-rule` → `4.own-external`, `4.own-turned`, the served "stays out of the tree"; `own-frame-rule,own-frame-src` → that and "loads nothing" (the page's `frame-src`, the second wall); `frame-guard,sync-guard` → `4.own-external`, `4.own-turned`, `4.own-default` |
|
|
993
994
|
| A page on a tab of its own (P099) | every served page's CSP header carries the frame's sandbox (`sandbox allow-scripts allow-same-origin`, `servedSandboxDirective`) and its `Permissions-Policy` denies what the frame's `allow` doesn't grant (`servedPermissionsPolicy`); on a tab the shell answers `window.open` with null (but `_self`), refuses picture-in-picture windows, devices, location, full screen, passkeys, the share sheet, payments (Apple Pay too) and a video's full screen; its navigation guard (P079) stops the page navigating itself, and `navigation.navigate()` and a tab's `open(…, "_self")` ask its rule before they start (the address read once, through the platform's own functions); a tab's links are followed by the shell as clicked (cancelled in its first listener, found through the composed path, closed shadow roots made open to it), never by the browser; a lock that can't take says so (`data-porthole-unfixed`, a report to the host) | `test/server.test.ts`, `test/files.test.ts`, `test/policy.test.ts`, `test/agreement.test.ts` (every served page, in a frame, on a tab, without fetch metadata; never a script, a url-mode app or Porthole's own pages; the header held to the frame's `allow`); served conformance `served.domain.tab-window-open`, `.tab-escapes` (a target=_blank link clicked past the shell, forms, a blob download, `prompt`), `.tab-opener` (its opener sent elsewhere), `.tab-navigation` (a `blob:` document of its own and an outside site, each from a fresh tab by `location`, `assign`, `replace`, a link past the shell, `navigation.navigate()` and `open(…, "_self")`, the last two given a two-faced address too, a link and `navigate()` with the built-ins lying), `.tab-links` (a link's `href`, `target` or `download` changed after the shell read it, a link in an open or closed shadow root; a fragment link still jumps, a cancelled one goes nowhere), `.tab-devices` (location, camera and microphone granted by the browser, full screen after a click), `.tab-prompts` (a passkey, a payment to a canary method, a share, a video's full screen: each refused at once); `test/permissions-policy.test.ts` (the denied list against Chromium's, checked in); `leak/served/tab.spec.ts`: those five, a file set's page on a tab (its module, fetch and links to its own pages work; nothing else opens), a frame's sealed address opened on a tab | `tab-sandbox` → tab-escapes, tab-opener, the file set's and the sealed address's cases (all three); `tab-sandbox,window-open` → those and tab-window-open (all three; picture-in-picture opens on Chromium and Firefox, absent on WebKit); `permissions-policy,device-locks` → tab-devices (all three), tab-prompts (Chromium, Firefox; WebKit refused each at once here either way); `device-locks` alone → tab-devices on WebKit and Firefox (they don't apply the header; Chromium holds), tab-prompts on Firefox; `window-open` or `permissions-policy` alone → none; `navigate-guard` → tab-navigation, tab-links (all three; P096 measured the second); `navigate-ask` (the rule asked first, alone) → tab-navigation and tab-links on WebKit (Chromium and Firefox hold by the event); `link-rule` (the browser follows links again) → tab-links and tab-navigation on WebKit; `scripts/controls.ts` |
|
|
994
995
|
| The runtime: a page's declaration (P086) | the bridge refuses a capability the page didn't declare (`undeclared`), on `porthole/call` and 0.6's requests alike, before any handler | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "an undeclared capability: null from use, refused when sent anyway, its handler never asked" | `runtime-declaration` → that case (all three) |
|
|
995
996
|
| The runtime: levels (P087) | each method's least level against the host's viewer, before any handler | `test/runtime.test.ts`, `test/assets.test.ts` (the grant's level to the bridge); `leak/served/runtime.spec.ts`: "a method above the viewer's level: forbidden, its handler never asked" | `runtime-level` → that case, and P094's "a read above the viewer's level: a result the host pushed is refused as a cold read is", whose reads stand on it (all three) |
|
|
@@ -1180,6 +1181,38 @@ a selection away from a page that patched `Selection.prototype.removeAllRanges`,
|
|
|
1180
1181
|
nothing back, leaves marks and drafts found, and the same words selected again are told
|
|
1181
1182
|
(`clear-selection`).
|
|
1182
1183
|
|
|
1184
|
+
### Find in page
|
|
1185
|
+
|
|
1186
|
+
A host's own find bar over a display (P131), where the config declares `find`:
|
|
1187
|
+
|
|
1188
|
+
- **Shell.** `FIND_RUNTIME` (`src/shell/find.ts`), spliced in as the annotation runtime is, before
|
|
1189
|
+
content runs. It finds a query (`porthole/find.query`, a request) in annotations' text index
|
|
1190
|
+
(`TEXT_INDEX`, `src/shell/text.ts`, shared), case-insensitive and loose about spacing
|
|
1191
|
+
(`FIND_MATCH`), only matches that are drawn, at most 1,000; draws them in a layer of its own (a
|
|
1192
|
+
closed shadow root, annotations' layer style), the current one apart, redrawn on scroll and
|
|
1193
|
+
resize and found again as the content changes (`porthole/find.updated`, at most once a second);
|
|
1194
|
+
brings the current one into view through its scrolling ancestors and the window; and, while the
|
|
1195
|
+
host says it draws its own bar (`porthole/find.handled`), cancels the browser's find on Cmd+F or
|
|
1196
|
+
Ctrl+F a page didn't take (`FIND_SHORTCUT`) and says `porthole/find.requested`. Like the guards
|
|
1197
|
+
(P129), it and the text index call only built-ins captured before content runs, through
|
|
1198
|
+
`callOf`; its layer goes in through the guarded insertion methods (P130,
|
|
1199
|
+
[insertion-entry-points.md](insertion-entry-points.md) § The shell's own layers).
|
|
1200
|
+
- **Host API.** `display.find.query(query, { direction, caseSensitive })` → `{ total, active,
|
|
1201
|
+
capped?, rect? }` or `"unsupported"` (no `find`, an older shell's `-32601`, a malformed answer, no
|
|
1202
|
+
answer in `FIND_LIMITS.timeoutMs`, a query superseded by a later one: the shell searches only the
|
|
1203
|
+
latest of a burst, `FIND_LATEST`), `clear()`, `takeShortcut(take)`; the query holds only for the
|
|
1204
|
+
content it was asked of (a new run or other content forgets it); events `findRequested`
|
|
1205
|
+
(only while taken, with the page's focus in the frame) and `findUpdated` (only while a query is
|
|
1206
|
+
shown), checked and rate-limited through the bridge. React: `onFindRequested`, `onFindUpdated`,
|
|
1207
|
+
and the handle's `find` and `clearFind`.
|
|
1208
|
+
- **Trust.** The page reads every query; what it says back is a find bar's numbers. Tests:
|
|
1209
|
+
`test/find.test.ts` (the matching and its limits, the shortcut rule, the checks, the shell's
|
|
1210
|
+
splice and built-ins, only the latest query, `createHost`'s requests, answers, forgetting and
|
|
1211
|
+
gates, the React handle's scope); `leak/find.spec.ts`
|
|
1212
|
+
on three engines (highlights, next and previous into view, a scrolling box, a change found again,
|
|
1213
|
+
the shortcut the host's only while taken and the page's own find keeping it, and a hostile page's
|
|
1214
|
+
`requested` while the person types in the host's composer dropped: `find-requested-focus`).
|
|
1215
|
+
|
|
1183
1216
|
## The shell runtime
|
|
1184
1217
|
|
|
1185
1218
|
The runtime (`src/shell/runtime.ts`, plain ES2020, no build) runs first in every
|
|
@@ -1263,7 +1296,7 @@ how content behaves, each one line derived from the config (`manualLimits`, P064
|
|
|
1263
1296
|
| `workers` | blob: Web Workers work; no service workers; no WebRTC | always | `14.workers`, `3.webrtc` |
|
|
1264
1297
|
| `sound` | sound plays only from a click | always | `14.sound` |
|
|
1265
1298
|
| `address` | about:srcdoc (opaque) or its own address with Porthole's ticket (domain) | always | `14.address`, `served.domain.address` |
|
|
1266
|
-
| `shell` | document.write/open throw; nested frames removed; full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom` |
|
|
1299
|
+
| `shell` | document.write/open throw; nested frames removed (with `nestedFrames: "own"`, P128: but `srcdoc` ones and frames of the page's own files); full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom`, `4.own-external` |
|
|
1267
1300
|
| `storage` (interactive topic) | per isolation; in domain mode reads and writes can throw: try/catch | always | `14.storage`, `served.domain.storage-scope` |
|
|
1268
1301
|
|
|
1269
1302
|
Three more limits sit outside the list:
|
|
@@ -1422,10 +1455,12 @@ control the tables above name to the registry):
|
|
|
1422
1455
|
|---------|----------|-----------------------|---------------|-----------------------------|
|
|
1423
1456
|
| `connect-src` | `leak.spec.ts` | `[1.connect]`, `[14.silent]` | — | — |
|
|
1424
1457
|
| `webrtc` | `leak.spec.ts` | `[3.webrtc]`, `[14.workers]` | — | — |
|
|
1425
|
-
| `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would (`frame-guard,sync-guard`) |
|
|
1426
|
-
| `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
|
|
1458
|
+
| `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would, or refuses it at creation (P130) (`frame-guard,sync-guard`) |
|
|
1459
|
+
| `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard refuses the frame at creation (P130), and reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
|
|
1427
1460
|
| `sync-guard` | `leak.spec.ts` | nothing | WebKit: `[8.preconnect]` | on Chromium and Firefox the observer removes what the synchronous guard would, and no preconnect opens even unsandboxed (measured) (`frame-guard,sync-guard`) |
|
|
1428
|
-
| `frame-guard,sync-guard` | `leak.spec.ts` | `[4.light-dom]`, `[4.sync-realm]`, `[4.plugins]`, `[4.foreign-object]`, `[4.template-clone]`, `[7.base-plugins]`, `[14.shell]` | WebKit: `[8.preconnect]` | — |
|
|
1461
|
+
| `frame-guard,sync-guard` | `leak.spec.ts` | `[4.light-dom]`, `[4.sync-realm]`, `[4.plugins]`, `[4.foreign-object]`, `[4.template-clone]`, `[7.base-plugins]`, `[14.shell]`, `[4.own-external]`, `[4.own-turned]`, `[4.own-default]` | WebKit: `[8.preconnect]` | — |
|
|
1462
|
+
| `own-frame-rule` | `leak.spec.ts`, `served/files.spec.ts` | `[4.own-external]`, `[4.own-turned]`, `a page's own frames, opted in (P128): a frame of another site, of another path of its origin, or a plugin stays out of the tree` | — | — |
|
|
1463
|
+
| `own-frame-rule,own-frame-src` | `served/files.spec.ts` | `a page's own frames, opted in (P128): a frame of another site, of another path of its origin, or a plugin stays out of the tree`, `a page's own frames, opted in (P128): a frame of another site or of another path of its origin loads nothing` | — | — |
|
|
1429
1464
|
| `attach-shadow,sync-guard` | `leak.spec.ts` | `[4.closed-shadow]`, `[4.shadow-nested]` | WebKit: `[8.preconnect]` | — |
|
|
1430
1465
|
| `declarative-shadow` | `leak.spec.ts` | `[4.declarative-shadow]` | — | — |
|
|
1431
1466
|
| `parser-entry-points` | `leak.spec.ts` | `[4.document-write]`, `[14.shell]` | — | — |
|
|
@@ -1511,6 +1546,7 @@ control the tables above name to the registry):
|
|
|
1511
1546
|
| `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
|
|
1512
1547
|
| `blob-script,blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'`, `scripts load from /_blob/ only where uploads are the admins' (a tab, its session)` | — | — |
|
|
1513
1548
|
| `blob-inert` | `served/runtime.spec.ts` | `an asset opened on its own runs nothing, on a tab with the artifact's session` | — | — |
|
|
1549
|
+
| `find-requested-focus` | `find.spec.ts` | `a hostile page says the find shortcut was pressed while the person types in the host's composer: the host's find bar stays shut (P131)` | — | — |
|
|
1514
1550
|
|
|
1515
1551
|
## Milestones
|
|
1516
1552
|
|