@botiverse/porthole 0.15.3 → 0.16.0
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 +58 -0
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +6 -51
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +4 -14
- package/dist/isolation/served.js +7 -28
- package/dist/isolation/types.d.ts +2 -25
- package/dist/isolation/types.js +0 -23
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +6 -22
- package/dist/platform/web.js +8 -106
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/plan.d.ts +0 -5
- package/dist/shell/plan.js +2 -4
- package/dist/shell/runtime.js +1 -268
- package/docs/ADOPTING.md +42 -138
- package/docs/ARCHITECTURE.md +0 -33
- package/docs/DECISIONS.md +115 -10
- package/docs/DESIGN.md +27 -64
- package/docs/THREAT_MODEL.md +128 -255
- package/package.json +1 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +6 -52
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +6 -34
- package/src/isolation/types.ts +2 -31
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +6 -21
- package/src/platform/web.ts +8 -129
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/plan.ts +2 -9
- package/src/shell/runtime.ts +1 -268
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -288
- package/dist/platform/focus-guard.js +0 -838
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -121
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -407
- package/src/platform/focus-guard.ts +0 -1114
- package/src/server/nested.ts +0 -157
- package/src/shell/frame.ts +0 -444
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -201,23 +201,6 @@ Access is gated by a one-time ticket exchanged for a scoped cookie. Where the ho
|
|
|
201
201
|
holds the page and needs no stable origin, the shell writes it into an opaque
|
|
202
202
|
frame instead.
|
|
203
203
|
|
|
204
|
-
A **nested** page (P111) splits the shell from the page. The address the host frames
|
|
205
|
-
serves Porthole's shell alone: a document with no content, on an origin of its own (a
|
|
206
|
-
label of the scope's, `porthole-<…>`, on which nothing else is ever served, P114). It
|
|
207
|
-
frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
|
|
208
|
-
the page's sealed files' address on that origin, fetched without a cookie, and passes
|
|
209
|
-
messages between the host and the page:
|
|
210
|
-
|
|
211
|
-
```
|
|
212
|
-
Host app Shell (its own origin) Page (opaque child)
|
|
213
|
-
│ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
|
|
214
|
-
│◄── the page's messages ──────│◄── postMessage (by source) ───│
|
|
215
|
-
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
216
|
-
│◄── porthole/shell/state ─────│ its own activation, its focus │
|
|
217
|
-
│── porthole/shell/look ──────►│ look now (as a move is heard) │
|
|
218
|
-
│── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
|
|
219
|
-
```
|
|
220
|
-
|
|
221
204
|
### URL frame
|
|
222
205
|
|
|
223
206
|
```
|
|
@@ -283,22 +266,6 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
|
283
266
|
matches find found) is the content's word even when the shell says it, since they
|
|
284
267
|
share a realm: the host bounds it and uses it as a UI hint, never as a permission
|
|
285
268
|
(P053, P131). What the host sends in (a mark, a find query) the content can read.
|
|
286
|
-
A nested page (P111) is the one place they don't: the shell is a document of its
|
|
287
|
-
own, the page's parent, on another origin than the page's (opaque), so the page
|
|
288
|
-
reaches nothing of the shell's realm. Nor does any other content: the shell's
|
|
289
|
-
origin is a label of its own that hosts nothing but nested pages' shells, their
|
|
290
|
-
opaque pages, those pages' files and status pages (P114), never the scope's
|
|
291
|
-
origin, where the scope's other displays run content with `allow-same-origin`
|
|
292
|
-
(porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
|
|
293
|
-
`event.source` alone and passes them on unchanged, never in its own namespace
|
|
294
|
-
(`porthole/shell/`); what it says in that namespace is the shell's own word (its
|
|
295
|
-
transient activation, which only a press or key in the page turns on, and whether
|
|
296
|
-
focus is in it), and the host, which knows the frame is nested from its config
|
|
297
|
-
only, uses it to tell the person's gesture from the page's (the focus guard,
|
|
298
|
-
`comments.open`). The host's own words in that namespace (its ask to look, P120)
|
|
299
|
-
go to the shell alone. A key and a press look the same in that word, so the host
|
|
300
|
-
doesn't ask it while it fights a frame for the keyboard (P120). Everything else
|
|
301
|
-
the page says is still the content's word.
|
|
302
269
|
|
|
303
270
|
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
304
271
|
*policy* are the host's; carrying the host's decision safely onto the content
|
package/docs/DECISIONS.md
CHANGED
|
@@ -4874,7 +4874,7 @@ when someone remembered, and what DESIGN.md said they fail had drifted from what
|
|
|
4874
4874
|
a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
|
|
4875
4875
|
a weakening seam (then its controls join the registry).
|
|
4876
4876
|
|
|
4877
|
-
## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133
|
|
4877
|
+
## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133; superseded in part by P149 (a marker's click within a gesture)
|
|
4878
4878
|
|
|
4879
4879
|
Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
|
|
4880
4880
|
review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
|
|
@@ -5500,7 +5500,7 @@ the anchor). Negative control `comment-draft` (the draft taken as given) → the
|
|
|
5500
5500
|
engine. `types/runtime/v1/check.ts` (the page-shaped call compiles); the runtime conformance's
|
|
5501
5501
|
comments case sends a draft.
|
|
5502
5502
|
|
|
5503
|
-
## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text ·
|
|
5503
|
+
## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text · Superseded in part by P149 (the keyboard given back, `comments.open` from the frame the person is in; the draft rules stand)
|
|
5504
5504
|
|
|
5505
5505
|
Amends P090 and P108, and THREAT_MODEL §6 and §7. From the review of P107 and P108 at 0.12.0
|
|
5506
5506
|
(2026-10-26: no P0, two P1s, three P2s, two P3s) and the review of the 0.11.0 and 0.12.0 releases
|
|
@@ -5845,7 +5845,7 @@ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a
|
|
|
5845
5845
|
**Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
|
|
5846
5846
|
or an engine starts counting fixed boxes in what the viewport scrolls.
|
|
5847
5847
|
|
|
5848
|
-
## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` ·
|
|
5848
|
+
## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Superseded by P149
|
|
5849
5849
|
|
|
5850
5850
|
**Context.** P109's focus guard and `comments.open`'s gate ask whether the person, not the page,
|
|
5851
5851
|
moved the keyboard into a frame or clicked in it. In full Chromium a cross-site frame is out of
|
|
@@ -6112,7 +6112,7 @@ told selection kept: each alone fails the probe, measured on Chromium).
|
|
|
6112
6112
|
**Revisit when** a host needs the element picked (`elements: true`) or a held block cleared too
|
|
6113
6113
|
(they leave no highlight now), or the MCP Apps spec gains a host-to-view way to clear a selection.
|
|
6114
6114
|
|
|
6115
|
-
## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served ·
|
|
6115
|
+
## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Superseded by P149
|
|
6116
6116
|
|
|
6117
6117
|
**Context.** porthole#56 (Ferry's audit of what merged after 0.13.0). P111 rests on the shell
|
|
6118
6118
|
being a realm content can't reach (ARCHITECTURE "Trust boundaries" 4): the host trusts the shell's
|
|
@@ -6375,7 +6375,7 @@ pinned at the frame's top… takes a mouse click and a tap where it is drawn" (a
|
|
|
6375
6375
|
pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
|
|
6376
6376
|
with no touch and on a touch screen after a finger).
|
|
6377
6377
|
|
|
6378
|
-
## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen ·
|
|
6378
|
+
## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Superseded by P149
|
|
6379
6379
|
|
|
6380
6380
|
Amends P111. **Context.** The audit of P111's guard (2026-10-28, NG-1, P0 on Firefox; porthole#56):
|
|
6381
6381
|
a nested page that focuses its field as it loads and focuses it again whenever it loses focus read
|
|
@@ -6511,7 +6511,7 @@ out-of-process frame, says what turned activation on, or tells a frame's parent
|
|
|
6511
6511
|
into it; or a host can tell a frame in its own process from one out of it before the pointer has
|
|
6512
6512
|
been over one (then a first move into a nested page there is judged as 0.13 judged it, P120-1).
|
|
6513
6513
|
|
|
6514
|
-
## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded ·
|
|
6514
|
+
## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Superseded in part by P149 (a nested page's shell held to its own label, one source for its files' CSP)
|
|
6515
6515
|
|
|
6516
6516
|
Amends P114 and P115. From the audit of aedc412 (2026-10-29; no P0 or P1): two findings on nested
|
|
6517
6517
|
pages (M1, P2; M2, P3) and two on annotations (AN-1, P2; AN-2, P3).
|
|
@@ -6580,7 +6580,7 @@ second display kind from the app under test, and what it would hold (a Worker's
|
|
|
6580
6580
|
host's; left for when a host with its own Worker asks for one. Hiding the clear from the page:
|
|
6581
6581
|
the `selectionchange` gives it away whatever the message says.
|
|
6582
6582
|
|
|
6583
|
-
## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation ·
|
|
6583
|
+
## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Superseded by P149
|
|
6584
6584
|
|
|
6585
6585
|
Amends P120. **Context.** CI on 0.14.4 (run 40822963445, `loopback (chromium-oopif)`): P120's
|
|
6586
6586
|
case "a page that starts taking the keyboard back on its own blur while the person types…" failed
|
|
@@ -6650,7 +6650,7 @@ pass on full Chromium, the headless shell and Firefox; `navigate-guard`, `pointe
|
|
|
6650
6650
|
it (then the press itself can be told from a key, and the window can go).
|
|
6651
6651
|
|
|
6652
6652
|
|
|
6653
|
-
## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort ·
|
|
6653
|
+
## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Superseded in part by P149 (the risk stays accepted; the guard is gone)
|
|
6654
6654
|
|
|
6655
6655
|
**Context.** P109, P120 and P122 built a guard that gives the keyboard back when a display moves
|
|
6656
6656
|
focus into its frame while the person types in the host's page. P122's review (porthole#81) showed
|
|
@@ -7975,7 +7975,7 @@ Safari; Safari and iOS are unmeasured. Playwright emulates a focused window on e
|
|
|
7975
7975
|
Safari shows `hasFocus` disagreeing with the host's `activeElement` after `display.focus()`; or a
|
|
7976
7976
|
word must expire by itself (a host that sends many, or content that stays out for long).
|
|
7977
7977
|
|
|
7978
|
-
## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own ·
|
|
7978
|
+
## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own · Superseded by P149
|
|
7979
7979
|
|
|
7980
7980
|
Amends P111 and closes P135's known gap (#proj-workspace:#214). Tenny's requirement, #proj-workspace:#211:
|
|
7981
7981
|
`marker-late` covers the nested case.
|
|
@@ -9357,7 +9357,7 @@ would then be no better than the event, and no worse); a host needs marks in the
|
|
|
9357
9357
|
scrollers to ride too (a timeline per scroller, named from the mark's nearest one); or decision 6's
|
|
9358
9358
|
case is reported.
|
|
9359
9359
|
|
|
9360
|
-
## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds ·
|
|
9360
|
+
## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds · Superseded by P149
|
|
9361
9361
|
|
|
9362
9362
|
Amends P111 (its "Rejected", and item 4 of its "Threat it re-opens"). From Raft (xxchan,
|
|
9363
9363
|
2026-11-11): a page's own button that calls `comments.open`; the host answers with a dialog; the
|
|
@@ -9524,3 +9524,108 @@ held: a second wall behind item 2, held by the unit test).
|
|
|
9524
9524
|
condition: this and the activation rule could then both go); a host reports the residual for
|
|
9525
9525
|
controls that aren't native (then a rule for `role` that typing can't satisfy); or the 500 ms
|
|
9526
9526
|
after a stall drops presses people notice.
|
|
9527
|
+
|
|
9528
|
+
## P149 · 2026-11-11 · What guessed at the person's intent is taken out: nested pages, the focus guard, the proof of a click but `copyText`'s · Accepted
|
|
9529
|
+
|
|
9530
|
+
**Context.** A host reported that a page's own "comment" button, pressed by a real person,
|
|
9531
|
+
was refused: "This needs a click". The press was real. `comments.open` asked for a gesture
|
|
9532
|
+
*with the host page's focus in the calling frame* (P109), the host's page can't see a press
|
|
9533
|
+
inside a cross-site frame (out of process on full Chromium; no event on Firefox), and so the
|
|
9534
|
+
rule ran on a guess: `:active`, the pointer's place, the time since the last key, and for a
|
|
9535
|
+
nested page its shell's word on its activation (P111), then on which keys count (P120, P122),
|
|
9536
|
+
then on each real press told over a port (P148), with a storage design for nested pages next in
|
|
9537
|
+
line. Each step made the guess better and the machine larger, and each release still refused
|
|
9538
|
+
some real clicks. The question that should have come first: what does the check protect?
|
|
9539
|
+
|
|
9540
|
+
**What the checks protected.** Followed to the end, each one of them stops a page from *asking
|
|
9541
|
+
at a moment it picks*, never from doing:
|
|
9542
|
+
|
|
9543
|
+
- `sendPrompt`, `openLink`, `downloadFile`, `artifact.publish`, `assets.delete`: each already
|
|
9544
|
+
ends at the person's confirmation, shown the whole effect, and declines mute the display. A
|
|
9545
|
+
page that asks unprompted gets a dialog the person says no to.
|
|
9546
|
+
- `comments.open`: opens the host's composer with a draft that posts nothing by itself; the
|
|
9547
|
+
host's handler may answer no (P108's duties stand).
|
|
9548
|
+
- A marker's `activated`: opens the host's view of a mark, which takes no focus and no press
|
|
9549
|
+
for its first 500 ms (§6's guard stands).
|
|
9550
|
+
- The focus guard: gave the keyboard back when a page took it. P123 had already accepted that
|
|
9551
|
+
it couldn't hold (typing slower than one key per 250 ms passed it), so it was a wall with a
|
|
9552
|
+
known hole whose false positives were the person's own clicks.
|
|
9553
|
+
|
|
9554
|
+
And the proof itself proved little: the host-side check passed for any click anywhere on the
|
|
9555
|
+
host's page in the last 5 s, and the shell-side one is the content's own realm speaking.
|
|
9556
|
+
|
|
9557
|
+
**Decision.**
|
|
9558
|
+
|
|
9559
|
+
1. **No proof of a click is asked by default, but `copyText`'s.** The default gates of
|
|
9560
|
+
`sendPrompt`, `openLink` and `downloadFile` are `confirm` and a rate of 30 a minute (they had
|
|
9561
|
+
no rate: the gesture was their bound, so they get one); `comments` keeps its rate alone;
|
|
9562
|
+
`artifact.publish` and `assets.delete` keep `confirm`. `copyText` keeps `user-activation`:
|
|
9563
|
+
it has no confirmation, the clipboard is the person's, and the browser's own rule for writing
|
|
9564
|
+
it is a gesture. The gate itself stays in the vocabulary: a host may name `user-activation`
|
|
9565
|
+
for any capability or method (`gates`, `methodGates`), and the shell and the bridge check it
|
|
9566
|
+
as before. `CapabilitySpec.inFrame` (P109's "in the calling frame") is removed.
|
|
9567
|
+
2. **A marker's `activated` is taken with or without a gesture** (supersedes P105's point 2).
|
|
9568
|
+
Every other check on it stands: only for a mark the host shows with a marker, rebuilt,
|
|
9569
|
+
clamped, within the rate.
|
|
9570
|
+
3. **The focus guard is removed** (supersedes P109's decisions 1 and 2; P123's risk stays
|
|
9571
|
+
accepted, now without a guard in front of it). No `focusTaken`, no `onFocusTaken`, no display
|
|
9572
|
+
stopped for taking the keyboard, no shell words about focus. `display.focus()` is the
|
|
9573
|
+
frame's own `focus()`. `focusField(field)` stays as a plain helper (it blurs a frame that
|
|
9574
|
+
holds the focus, then focuses the field: Firefox ignores a plain `focus()` there).
|
|
9575
|
+
`Surface.focused`, where a platform gives it, says only whether the keyboard is in the
|
|
9576
|
+
display (the frame's root's `activeElement`), and only the find shortcut reads it (P131).
|
|
9577
|
+
4. **Nested pages are removed** (supersedes P111, P114, P120, P121's M1 and M2, P122, P136,
|
|
9578
|
+
P148). `nested: true` is no field; the shell document, its label (`porthole-<…>`), its
|
|
9579
|
+
namespace (`porthole/shell/*`), its press port and the `/server` routes and helpers for it
|
|
9580
|
+
are gone. They existed to give the guard and `comments.open` a realm the page couldn't speak
|
|
9581
|
+
for; with nothing left to ask it, the mode is a second way to serve a page with no reader.
|
|
9582
|
+
The label prefix `porthole-` stays reserved (`PORTHOLE_LABEL_PREFIX`): no host's naming makes
|
|
9583
|
+
one.
|
|
9584
|
+
5. **What stays, and is not this kind of rule.** P135 and P137 (a late `focusMark` doesn't land
|
|
9585
|
+
once the person has moved on) guard the host's *own* move of the focus, not the page's. The
|
|
9586
|
+
find shortcut's focus rule (P131) refuses no real press: the key is always pressed in the
|
|
9587
|
+
frame. The host view's 500 ms (§6) is the host's own guard of its own controls.
|
|
9588
|
+
|
|
9589
|
+
**The served path.** No wall moves: origins, sandboxes, CSP, tickets, the door and every message
|
|
9590
|
+
check are as in 0.15.3. The page runtime every served document inlines is 0.15.2's with the
|
|
9591
|
+
nine lines of the nested-only renewal hook taken out (its pin in `test/framed-by.test.ts`);
|
|
9592
|
+
`use` and `legacy` are unchanged, and follow the plan's gates as they did.
|
|
9593
|
+
|
|
9594
|
+
**Rejected.** *Keep the checks and widen the guess again* (a storage relay for nested pages was
|
|
9595
|
+
designed next): the fifth step on the same road, for a check that protects a moment, not an
|
|
9596
|
+
effect. *Keep nested mode without the guard*, as an opaque page for scopes that distrust their
|
|
9597
|
+
own displays: no host uses it, and different scopes already give displays that distrust each
|
|
9598
|
+
other different origins (THREAT_MODEL S7); it can come back as its own decision with its own
|
|
9599
|
+
reader. *Remove `copyText`'s click too*: it is the one call with no person between the page and
|
|
9600
|
+
the effect. *Remove the `user-activation` gate from the vocabulary*: a host with a reason of its
|
|
9601
|
+
own may still want it, and `copyText` needs it.
|
|
9602
|
+
|
|
9603
|
+
**Cost.** A page can interrupt: a confirmation, a composer or a comment view at a moment the
|
|
9604
|
+
person didn't pick, within 30 a minute, until declines mute it. A page that takes the keyboard
|
|
9605
|
+
keeps it until the person clicks back. A host that wants the old default for one capability names
|
|
9606
|
+
the gate again (`gates: ["user-activation", "confirm"]`), with the false refusals that come with
|
|
9607
|
+
it. A host that served nested pages must go back to served ones (CHANGELOG 0.16.0 says how).
|
|
9608
|
+
|
|
9609
|
+
**Tested.** `test/bridge.test.ts` (a gesture gate refuses where named and for `copyText`;
|
|
9610
|
+
nothing else asks one); `test/agreement.test.ts` (every capability a page can call without a
|
|
9611
|
+
gesture has a default rate, P103's rule, now three more); `test/runtime-review.test.ts`
|
|
9612
|
+
(publish and delete: a confirmation with or without a gesture; a host's `methodGates` bring the
|
|
9613
|
+
gesture back, in the plan and the manual); `test/annotate.test.ts` (a marker's click taken
|
|
9614
|
+
whatever the platform says of activation, still only for a shown marker); `test/config.test.ts`
|
|
9615
|
+
(`nested` is refused as an unknown field); `test/sandbox.test.ts` (the static rule on
|
|
9616
|
+
`allow-same-origin`, re-homed from the nested suite); `test/framed-by.test.ts` (the runtime's
|
|
9617
|
+
pins). Conformance: `12.prompt-confirm` (a prompt on load is asked, and a no sends nothing),
|
|
9618
|
+
`12.raw-message` (a raw `ui/message` is asked too), `12.copy-text` and the new `12.raw-copy`
|
|
9619
|
+
(the gesture gate that stays, shell side and host side; controls `shell-gesture`,
|
|
9620
|
+
`host-gesture`). 28 negative controls go with the code they took out (the registry and
|
|
9621
|
+
DESIGN.md's table); `leak/late-word.spec.ts` keeps `chromium-oopif`'s one case.
|
|
9622
|
+
|
|
9623
|
+
**Revisit when** an engine tells a host's page, truthfully, that the person pressed inside a
|
|
9624
|
+
cross-site frame (then a check could be a fact, not a guess); a host reports the interruptions
|
|
9625
|
+
as abuse its own handler can't bound; or a host needs an opaque page inside a shared scope
|
|
9626
|
+
(nested pages' one use that was not the guard).
|
|
9627
|
+
|
|
9628
|
+
**Amended 2026-11-11, before the release.** `chromium-oopif` runs every served case too
|
|
9629
|
+
(`leak/served/*.spec.ts`, 142 more on full Chromium), not `leak/late-word.spec.ts` alone: with
|
|
9630
|
+
the nested cases gone the project had seven tests left, and a served display out of process is
|
|
9631
|
+
the setting the removed guesses failed in. No served case needed a change to pass there.
|
package/docs/DESIGN.md
CHANGED
|
@@ -106,9 +106,9 @@ no `components` field (P015).
|
|
|
106
106
|
|
|
107
107
|
| Capability | Default gates | Served by | Shell global | MCP Apps request (App SDK) |
|
|
108
108
|
| --- | --- | --- | --- | --- |
|
|
109
|
-
| `sendPrompt` |
|
|
110
|
-
| `openLink` |
|
|
111
|
-
| `downloadFile` |
|
|
109
|
+
| `sendPrompt` | confirm, 30/min (P149) | handler | `sendPrompt(text)` | `ui/message` (`app.sendMessage`) |
|
|
110
|
+
| `openLink` | confirm, 30/min (P149) | handler | `openLink(url)` | `ui/open-link` (`app.openLink`) |
|
|
111
|
+
| `downloadFile` | confirm, 30/min (P149) | handler | — | `ui/download-file` (`app.downloadFile`) |
|
|
112
112
|
| `callTool` | confirm, 30/min (P103) | handler | — | `tools/call` (`app.callServerTool`) |
|
|
113
113
|
| `readData` | 120/min | handler | `readData(uri)` | `resources/read` (`app.readServerResource`) |
|
|
114
114
|
| `subscribeData` | 60/min (needs `readData`) | handler (`changed`, `signal`) | `subscribeData(uri, onData, onError)` | `resources/subscribe`, `resources/unsubscribe`; the host's `notifications/resources/updated` (MCP's own; none in MCP Apps, P079) |
|
|
@@ -118,7 +118,7 @@ no `components` field (P015).
|
|
|
118
118
|
| `copyText` | user-activation, 30/min | handler | `copyText(text)` | `porthole/copy-text` (none in the standard) |
|
|
119
119
|
| `annotate` | 120/min (the frame's reports) | event | — | `porthole/annotate.*` (the host drives it, P053) |
|
|
120
120
|
| `user` (runtime) | 60/min | viewer (the host's `ViewerInfo`) | `porthole.use("user")` | `porthole/call` (P087) |
|
|
121
|
-
| `comments` (runtime) |
|
|
121
|
+
| `comments` (runtime) | 30/min (P149) | handler (answers a boolean) | `porthole.use("comments")` | `porthole/call` (P090) |
|
|
122
122
|
| `artifact` (runtime, artifact mode) | 10/min | handler (`op: get \| publish`) | `porthole.use("artifact")` | `porthole/call` (P088) |
|
|
123
123
|
| `assets` (runtime, served artifacts) | 30/min | handler (`op: list \| upload \| delete`) | `porthole.use("assets")` | `porthole/call`; `/server` serves `/_blob/<id>` (P089) |
|
|
124
124
|
| `db` (runtime) | 600/min | handler (`op: get \| query \| watch \| set \| update \| delete \| batch`) | `porthole.use("db")` | `porthole/call`, `porthole/event`, `porthole/unwatch` (P088) |
|
|
@@ -126,7 +126,8 @@ no `components` field (P015).
|
|
|
126
126
|
Every preset declares only `resize` and `reportError` (they report to the host and
|
|
127
127
|
carry nothing out); the host declares the rest. Gates are explained in P021: all
|
|
128
128
|
must pass; `confirm` calls the host's `confirm` function and fails closed without
|
|
129
|
-
one; `user-activation`
|
|
129
|
+
one; `user-activation` (by default `copyText`'s alone since 0.16.0, P149; a host may name it
|
|
130
|
+
for any other) is checked by the shell (advisory: it shares the content's
|
|
130
131
|
realm) and by the host where the engine passes the gesture up; `consent` asks the
|
|
131
132
|
host's `consent` function once per display, before its first consent-gated call,
|
|
132
133
|
and fails closed without one (P079); a `Refused` given as `consent` refuses them all,
|
|
@@ -848,7 +849,7 @@ if (db) {
|
|
|
848
849
|
(shape, bounded walks, limits: `too_large`) → the call's level (a batch's writes', a watch's
|
|
849
850
|
read's), `data`'s names (with a viewer or without one, P094), `db`'s paths and rules → mute →
|
|
850
851
|
rates → gesture → consent → confirm (the host function's gates and the own gates of each method
|
|
851
|
-
the call runs: `artifact.publish` and `assets.delete` a
|
|
852
|
+
the call runs: `artifact.publish` and `assets.delete` a yes, an upload whose code
|
|
852
853
|
may run a yes; a db batch its writes', confirmed once whole, a rate counting each write; a watch
|
|
853
854
|
its read's, P094) → the handler, or for a read a result the host already gave for it (P094)
|
|
854
855
|
(context: `viewer`, `declared`, `instance`) → `db` answers with `data/users/me` (P091).
|
|
@@ -970,24 +971,25 @@ official App SDK connects under the inline, artifact and MCP Apps presets
|
|
|
970
971
|
| 11 | auto-size | the shell reports its height (`size-changed`) as it changes; the host clamps it to `minHeightPx`..`maxHeightPx` and sizes the frame; past the cap the content scrolls inside | `11.size` (grows, shrinks, stops at the cap and scrolls, floors at the minimum; events carry the clamped height), `11.size-document` (a whole page's height; its own `load` fires; its title kept) | — |
|
|
971
972
|
| 11 | theming | `setTheme(scheme)`: the host sends the resolved variables (the host's live values over the defaults, P028), the shell sets them in place, with `data-theme` and `color-scheme`, then fires the config's theme event once, only when the scheme or a value changed (never at mount, never for a host re-sending what the content has, P061); the frame element's `color-scheme` follows | `11.theme-flip` (no event at mount or for the same scheme; in place: content state kept, the event fired once per flip, back and forth), `11.theme-host-values` (live values for standard and own names; undeclared names dropped) | — |
|
|
972
973
|
| 11 | base styles | plain CSS at zero specificity (`:where`): native buttons, inputs, selects and text areas take the theme's borders, radius, colors and focus ring, 44 px tall (the manual's touch size); the manual says so for inline widgets | `11.base-styles` (themed; content's own CSS overrides them) | — |
|
|
973
|
-
| 12 | `sendPrompt` | the
|
|
974
|
+
| 12 | `sendPrompt` | the host asks `confirm` with the whole text, whether a click came with the call or not (no proof of a gesture is asked since 0.16.0, P149); declines count toward a mute; at most 30 a minute | `12.prompt-confirm` (a call on load asks, and a no sends nothing; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: asked too, and a no sends nothing), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-confirm, raw-message, link, mute, no-confirm, `14.windows` |
|
|
974
975
|
| 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update; a refusal tells content why (`data: { code, message }`, P080) | `test/live-data.test.ts`, `test/refusals.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs, `denied` with its sentence; a host refusing all without handlers; a handler's `Refused`) | — |
|
|
975
976
|
| 12 | `openLink` | link clicks go out through `openLink`; the bridge takes http(s) only, without credentials in the URL; confirmed | `12.link` (a web link asks and opens; `javascript:` links and `openLink("javascript:…")` do nothing and are refused) | `link-scheme` → `12.link` |
|
|
976
977
|
| 14 | error reports (`reportError`, S05, P095) | the adapters hand the bridge what content logged as it came; the bridge counts reportError's rate before reading it, then makes bounded text of it (`boundedText`: each object once, `[Circular]`/`[Repeated]`; 1,000 values, 16 levels, 8,000 characters; a BigInt as `"5n"`), scrubs sealed addresses and cuts to 2,000; nothing a log holds throws out of an adapter | `14.error-shapes` (a cycle, a BigInt and a 20-level shared graph from an inline widget and from an MCP Apps view, each reported as bounded text); `test/log-bounds.test.ts` (undeclared or past its rate: nothing of it read) | `report-unbounded` → `14.error-shapes`, `14.silent` (its blocked-load report read as the text it was), on both host pages (P096) |
|
|
977
978
|
| 12 | model context (`setModelContext`, S5, P100) | the `show` gate by default: the bridge hands the host's `show` the whole update (text blocks rebuilt, structured content P095's JSON data, at most `MAX_CONTEXT_CHARS`, no character the person can't see: format characters, variation selectors, private use, lone surrogates, controls but `\n` and `\t`, save the selectors and joiners of real emoji and the joiners that shape Arabic, Indic and Myanmar letters) after every other gate and before the handler; no `show`, or one that throws, refuses it (`no-show`, `not_allowed`), and `close` ends its wait; the manual calls it the content's unconfirmed text, never instructions, and says what is refused; the React provider's default `show` draws `ContextNotice`, whole, and lets a call go once its own update is on the page (one replaced before it was drawn is refused); named gates without `show` and without `withoutShow: true` earn a `ConfigWarning` | `12.model-context` (a raw `ui/update-model-context`: shown whole, then handled; a host without `show`: refused, no handler); `test/model-context.test.ts` (both adapters, the order, the shapes, the size, each invisible character in text, values and keys, the warning); `leak/react.spec.ts` (the default notice is drawn before the handler runs, with its size; two updates in one task: only the drawn one goes; stacked displays all reachable; no provider: refused) | `model-context-show` → `12.model-context` (all three, `scripts/controls.ts`; the kit's harness is built unweakened), and both React cases (measured on Chromium) |
|
|
978
979
|
|
|
979
980
|
Measured: a click in the frame gives the host page user activation (it propagates to
|
|
980
|
-
ancestors) on Chromium, WebKit and Firefox, so the host-side gesture check
|
|
981
|
-
clicks; it is still advisory, since a person may have clicked
|
|
982
|
-
before. Playwright's own page evaluations count as gestures, so the gate
|
|
983
|
-
|
|
981
|
+
ancestors) on Chromium, WebKit and Firefox, so the host-side gesture check (`copyText`'s, and
|
|
982
|
+
any a host names) holds for real clicks; it is still advisory, since a person may have clicked
|
|
983
|
+
the host a moment before. Playwright's own page evaluations count as gestures, so the gate
|
|
984
|
+
probes (`12.copy-text`, `12.raw-copy`; `shell-gesture` → copy-text, `host-gesture` → raw-copy)
|
|
985
|
+
wait for that to lapse and click with raw input.
|
|
984
986
|
|
|
985
987
|
### Served content, each with its test
|
|
986
988
|
|
|
987
989
|
| What | Mechanism | Tests (all three engines unless noted) | Negative control → fails |
|
|
988
990
|
|------|-----------|-------|------------------|
|
|
989
991
|
| The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so (after `loaded` too in url mode; a served display that isn't nested is told by its next run's door, which takes a fresh ticket, P125) | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load (every engine: its next run's door); an app and a page in a tab | `authorize` → every case but WebKit's framed app (no framed cookie) |
|
|
990
|
-
| Who may say how loading went (P124, P125) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it. **A served display
|
|
992
|
+
| Who may say how loading went (P124, P125) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it. **A served display** (a served shell, a page, a view through the sandbox proxy) is framed on its scope's origin, where the scope's others run content: **no frame status from its frame is ever taken** (one `frame-status` host error a run), and its silence is a `timeout`, never `framing`. Its **door** said how loading went first, from a frame of the host's that no content can reach (`open`, or `blocked` and why, P125). An **opaque frame**'s every status is the content's. A **url-mode app**'s is taken, as before (S6). A served location **without a door** (an older server) raises a `hostError` of kind `door` once a mount and is strict (no status taken) | `test/outcome.test.ts` ("who may say how loading went (P124)", "a served display takes no frame status from its frame (P125)", and through `createHost`: the door hand-off, a door block with its code, door silence, a restart's new door); `leak/served/siblings-status.spec.ts`: a same-scope sibling that injects, reloads, stops, wipes a display, attacks the proxy, or reaches for the door, each on all three; `leak/served/outcome.spec.ts`: a served shell's content, a served page, an opaque widget and a nested page each say `blocked` and are shown nothing (the opaque and served-non-nested cases are the ordering rule / the door rule; the opaque rule 1 is proven by `test/outcome.test.ts` only, P124-3; the door's opacity, its namelessness and the sibling's navigation flag by the static sandbox test and `[door-reach]`) | `content-status` → the two served-content cases, `[sibling-inject]`, `[sibling-reload]`, `[proxy]`; `door-status` → `[sibling-inject]`, `[sibling-reload]`, `[proxy]`; `door-silence` → `[sibling-wipe]`; `door-opaque` → `[door-reach]`; `frame-status-order` → the nested case |
|
|
991
993
|
| Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
|
|
992
994
|
| Siblings on the content domain (P101) | over https only `__Host-porthole-` names are read (a sibling sets any other name for the whole domain, never a `__Host-` one), names trimmed of spaces and tabs only; the entered mark is its label's and path's, read from a nonce cookie only; a url-mode app's request rides its cookie only from its own origin (`Origin`; `Sec-Fetch-Site` `same-origin` or `none`) or as a GET/HEAD navigation, else a 403 before the upstream and the host's check; a socket (`access`, `nodeHost`'s `appSocket`, a Worker's upgrade path) from its own origin only | `test/siblings.test.ts` (planted names, the mark on another label, every kind of request and socket, `nodeHost` over a real socket); `test/workers.test.ts` (workerd: a sibling's POST and socket refused, the app's own open); `served.url.siblings`: another app's frame (Chromium, Firefox: WebKit keeps no framed cookie, P025) or tab loading the app's script is refused, its own loads; `leak/kit.spec.ts`: the app's own WebSocket opens through `nodeHost`, a same-site sibling's doesn't; prod shape: a session copied under an unprefixed name and planted with `Domain=` opens nothing, and the socket case over wss | `url-origin` → `served.url.siblings` on the reference serving (Chromium, Firefox; its labels are cross-site on `*.localhost`, so only the framed half rides a cookie) |
|
|
993
995
|
| Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
|
|
@@ -1006,15 +1008,9 @@ for that to lapse and click with raw input.
|
|
|
1006
1008
|
| The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
|
|
1007
1009
|
| The runtime: a comment's draft is visible text (P108) | the bridge refuses a draft that isn't a string, is blank, past 2,000 characters, or holds what a person can't see (`unseen`), before any handler | `test/runtime.test.ts`: "a draft (P108)"; `leak/served/runtime.spec.ts`: "a comment's draft is the host's to check" | `comment-draft` → that case (all three) |
|
|
1008
1010
|
| The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
|
|
1009
|
-
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
1010
|
-
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
1011
|
-
| A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows), asking the shell to look as it hears the move; where the host's page sees the pointer over its frames, not with the pointer elsewhere within a second of typing; in a fight over a text field, a frame that takes focus again is judged without the shell and taken back at once, counted (P120); no press within 250 ms of the person's key on the host's page (P122) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three); `pointer-rule` (P120's pointer rule out) → "an activation that came as the person typed…" (all three); `key-press` (P122's 250 ms out) → "an activation that turned on within 250 ms of the person's key…" (all three); `nested-fight` (a frame that takes focus back in a fight let be) → "a page that holds the keyboard from its load…" (Firefox); `leak/served/nested-keyboard.spec.ts` (a page that takes the keyboard as the person types: a race, no control's probe) |
|
|
1012
|
-
| A nested page's real presses, told to its shell (P148) | the shell sends its page a `MessagePort` at each load and hears only the last load's; the page's runtime takes it before content runs (the first listener, capturing; the browser's own message, from the parent read at start, exactly one port; the event stopped) and tells on it only the browser's own events: a mouse down, a finger or pen up, Enter or Space not held on a native control that isn't editable (by tag and type, never `role`), a click on one, but none while a key is down nor a form's own for Enter in a field; installed only under a nested page's plan and only if `document.open`, `write` and `writeln` are fixed shut; the host takes a press told as an activation that turned on (a second, no press or key on its page since, P120's and P122's rules, not within 500 ms of a stall of the shell) | `test/nested.test.ts` "the page's real presses, told to the shell over a port"; `leak/served/nested-press.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `press-untrusted`, `press-role`, `press-editable`, `press-repeat`, `press-key-click`, `press-submit` (with `press-key-click`), `press-touch-down` (Chromium), `press-port-heard`, `press-port-forged` (Chromium, WebKit), `press-open-lock`, `press-still-here` (WebKit), `press-host-input`, `shell-stall` |
|
|
1013
|
-
| A nested page's shell passes the focus on at the host's word (P136) | `display.focus()` sends `porthole/shell/focus`, only a move that landed; the shell acts only while the focus is on its own document, blurring its frame first, and a page's message in its namespace never reaches that code | `test/nested.test.ts` "the host's word that it moved the focus into a nested page's frame"; `leak/served/nested.spec.ts`: "a page that had the focus gets it back by the host's own move…", "a page that never had the focus…", "a second host's move into a page it just handed the focus to…", "the host's move into a page that holds the focus…", "the host's move from its own text field…", "the host's move takes no keyboard…", "the host's move from inside a key's own handler…" (`test.fail` on Firefox) | `shell-focus-held` |
|
|
1014
|
-
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
|
|
1015
1011
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
1016
1012
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
1017
|
-
| An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page
|
|
1013
|
+
| An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page; signed into the session as `m` and into the sealed address) → `frame-ancestors *` for that session's answers alone (its document, a file set's pages and files and own frames, assets, renewals, its status and ended-access pages); an embed session's cookie has a name of its own (`e-<key>`) and never stands in for another session; the plan names no host (`origins: []`): the shell asks no host, ends its handshake at once (`"none"`), says nothing to any parent (no `*` notices, no annotation or find report) and hears no one; no door; `statusPage` and `doorStatusResponse` take `embed` (`*`, `data-porthole-hosts="[]"`); the host kit refuses an `access` answer with `embed` (P145: minted through `host.server.issue` alone) | `test/embed.test.ts` (refused without `embeds`, with a viewer, a level or a user, for url mode, a nested display, a served shell or the proxy, at a clean address and at the door; the host kit refuses it from `access` at its issue endpoint, a clean address's resolve and its tab, with `embeds` or without; the flag can't be added or stripped, nor a session moved to the other name; **the bound**: 23 kinds of answer under an embed session say `*` and name no host, and the same under a public and a viewer's session are byte for byte what a server without `embeds` answers, on the same server while an embed session of the same artifact exists, and with both cookies sent; the host's check is told `embed`; cookies host-only, never `Domain=`); `test/shell.test.ts` (P143's handshake); `leak/served/embed.spec.ts`: `[embed.loads]`, `[embed.unheard]` (the words before the document loads too, P145), `[embed.untold]`, `[embed.no-escape]`, `[embed.reader-unframeable]` | `embed-ancestors` → `[embed.reader-unframeable]`; `embed-handshake` → `[embed.untold]`; `embed-origins` → `[embed.unheard]` (all three) |
|
|
1018
1014
|
|
|
1019
1015
|
### The clipboard, and copy buttons
|
|
1020
1016
|
|
|
@@ -1200,7 +1196,7 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1200
1196
|
all of it, read what `show` sends (ids, anchors, counts), or fake any report. The
|
|
1201
1197
|
host takes a selection only while it asked for that kind, a cancel only while
|
|
1202
1198
|
picking, results only for its own marks, a marker's click only for a mark it shows
|
|
1203
|
-
with a marker (a count or a draft)
|
|
1199
|
+
with a marker (a count or a draft), with or without a gesture (P149); it rebuilds
|
|
1204
1200
|
each from known fields within `ANNOTATION_LIMITS` (a label without what the person can't see, P105) and
|
|
1205
1201
|
drops the rest, through the bridge's rate limit. UI hints only, never
|
|
1206
1202
|
permissions: what a report says decides where a comment is drawn, never who may
|
|
@@ -1232,11 +1228,8 @@ host's `display.focus()` landing (P135, `marker-late`), by the kept
|
|
|
1232
1228
|
`hasFocus`, which a page's patch can't answer (`marker-has-focus`), a word a busy page takes late
|
|
1233
1229
|
held to the same test, by the host's stamp and the kept clock, a calm close landing, and a second
|
|
1234
1230
|
word after the host's move landing (P137, `marker-busy`, `marker-clock`, in
|
|
1235
|
-
`
|
|
1236
|
-
word)
|
|
1237
|
-
moved on (`marker-late`), a late word not either (`marker-busy`), and after
|
|
1238
|
-
the host's move, which the shell passes on (P136, `shell-focus-held`; on Firefox not from inside a
|
|
1239
|
-
key's own handler, `test.fail`), at its paragraph's end past the last word, a nested block's
|
|
1231
|
+
`late-word.spec.ts`, which full Chromium runs too, where a person's click comes before the
|
|
1232
|
+
word), at its paragraph's end past the last word, a nested block's
|
|
1240
1233
|
words not its own, a draft's by its words; focus and
|
|
1241
1234
|
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1242
1235
|
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
@@ -1249,8 +1242,7 @@ follow-ups a second apart however fast the machine (`follow-throttle`,
|
|
|
1249
1242
|
reports it alone, even when the deadline cut its run short; a hostile page faking a
|
|
1250
1243
|
marker's click for no mark, an unknown id or a mark without a marker, or clicking
|
|
1251
1244
|
the layer itself (`annotation-activated`, `annotation-activated-count`,
|
|
1252
|
-
`marker-trusted` → that case)
|
|
1253
|
-
(`annotation-activated-gesture`); and a page that patches `Event`'s and
|
|
1245
|
+
`marker-trusted` → that case); and a page that patches `Event`'s and
|
|
1254
1246
|
`MouseEvent`'s prototypes neither hearing a marker's press nor stopping its report
|
|
1255
1247
|
(`marker-originals`; `marker-click` too); a tap on a marker reported on each
|
|
1256
1248
|
engine, a touch screen and a phone's emulation (iPhone 13, Pixel 5), content hearing
|
|
@@ -1562,9 +1554,9 @@ control the tables above name to the registry):
|
|
|
1562
1554
|
| `style-split` | `leak.spec.ts` | `[0.app-sdk-inline]`, `[0.app-sdk-artifact]`, `[0.app-sdk-mcp-app]` | — | — |
|
|
1563
1555
|
| `draft-inert` | `leak.spec.ts` | `[11.streaming]` | — | — |
|
|
1564
1556
|
| `document-theme` | `leak.spec.ts` | `[11.document-theme]`, `[14.theme-never]` | — | — |
|
|
1565
|
-
| `confirm-gate` | `leak.spec.ts` | `[12.prompt-
|
|
1566
|
-
| `shell-gesture` | `leak.spec.ts` | `[12.
|
|
1567
|
-
| `host-gesture` | `leak.spec.ts` | `[12.raw-
|
|
1557
|
+
| `confirm-gate` | `leak.spec.ts` | `[12.prompt-confirm]`, `[12.raw-message]`, `[12.link]`, `[12.mute]`, `[12.no-confirm]`, `[14.windows]` | — | — |
|
|
1558
|
+
| `shell-gesture` | `leak.spec.ts` | `[12.copy-text]` | — | — |
|
|
1559
|
+
| `host-gesture` | `leak.spec.ts` | `[12.raw-copy]` | — | — |
|
|
1568
1560
|
| `model-context-show` | `leak.spec.ts` | `[12.model-context]` | — | — |
|
|
1569
1561
|
| `link-scheme` | `leak.spec.ts` | `[12.link]` | — | — |
|
|
1570
1562
|
| `clipboard` | `leak.spec.ts` | `[13.clipboard-command]`, `[13.clipboard-event]` | WebKit, Firefox: `[13.clipboard-api]`, `[14.shell]` | — |
|
|
@@ -1579,17 +1571,16 @@ control the tables above name to the registry):
|
|
|
1579
1571
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1580
1572
|
| `marker-key` | `annotate.spec.ts` | `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)` | — | — |
|
|
1581
1573
|
| `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
|
|
1582
|
-
| `marker-late` | `annotate.spec.ts
|
|
1583
|
-
| `marker-busy` | `
|
|
1584
|
-
| `marker-clock` | `
|
|
1585
|
-
| `marker-has-focus` | `annotate.spec.ts`, `
|
|
1574
|
+
| `marker-late` | `annotate.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
|
|
1575
|
+
| `marker-busy` | `late-word.spec.ts` | `a focusMark a busy page takes late doesn't land once the host's page has moved on (P137)`, `a page that stopped Date.now gets no landing for a word it took late (P137)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
|
|
1576
|
+
| `marker-clock` | `late-word.spec.ts` | `a page that stopped Date.now gets no landing for a word it took late (P137)` | — | — |
|
|
1577
|
+
| `marker-has-focus` | `annotate.spec.ts`, `late-word.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
|
|
1586
1578
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1587
1579
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1588
1580
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1589
1581
|
| `follow-count` | `annotate.spec.ts` | `following: a host that gives no counts hears no follow-up after a scroll, as before markers` | — | — |
|
|
1590
1582
|
| `draft-count` | `annotate.spec.ts` | `what the page reads of a draft (P107): that it is one, never its count; a posted mark as before` | — | — |
|
|
1591
1583
|
| `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
|
|
1592
|
-
| `annotation-activated-gesture` | `annotate.spec.ts` | `a hostile page's marker click with no gesture is dropped; one on the person's own press is the host's view to guard (P105)` | — | — |
|
|
1593
1584
|
| `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)`, `a selection's and a mark's last line come in the document's coordinates with the scroll, offscreen ones too; rect stays clamped (P133)` | — | — |
|
|
1594
1585
|
| `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host` | — |
|
|
1595
1586
|
| `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
|
|
@@ -1613,10 +1604,7 @@ control the tables above name to the registry):
|
|
|
1613
1604
|
| `runtime-data-names` | `served/runtime.spec.ts` | `a resource outside the page's data names: refused with a viewer and without one, its handler never asked` | — | — |
|
|
1614
1605
|
| `live-held-read` | `served/runtime.spec.ts` | `a read above the viewer's level: a result the host pushed is refused as a cold read is` | — | — |
|
|
1615
1606
|
| `db-private` | `served/runtime.spec.ts` | `a person's own data is theirs: another person's is refused, never reaching the service` | — | — |
|
|
1616
|
-
| `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens
|
|
1617
|
-
| `focus-guard` | `served/runtime.spec.ts` | `a page that takes the keyboard while the person types in the host's composer gets a key or two at most, and is stopped` | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | — |
|
|
1618
|
-
| `focus-guard-watch` | `served/runtime.spec.ts` | nothing | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | no probe can see it on Chromium and WebKit: they blur the host's window on every move into a frame and a take-back lands, and a page can't take focus back from its own blur there (measured) |
|
|
1619
|
-
| `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
|
|
1607
|
+
| `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens when the page asks, with a click or without one, and content hears only that` | — | — |
|
|
1620
1608
|
| `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
|
|
1621
1609
|
| `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
|
|
1622
1610
|
| `track-selection-checks` | `annotate.spec.ts` | `a followed selection's place comes as it moves, highlighted, out of view and back, gone and found again, only while the host follows it, at most 60 a second (P138)`, `without keepSelection or a follow, a pick's outline goes with the pick and nothing is kept: a follow asked after it has nothing, one asked before it follows it; a page's malformed word is no refusal (P140)` | — | — |
|
|
@@ -1630,31 +1618,6 @@ control the tables above name to the registry):
|
|
|
1630
1618
|
| `embed-ancestors` | `served/embed.spec.ts` | `[embed.reader-unframeable]` | — | — |
|
|
1631
1619
|
| `embed-handshake` | `served/embed.spec.ts` | `[embed.untold]` | — | — |
|
|
1632
1620
|
| `embed-origins` | `served/embed.spec.ts` | `[embed.unheard]` | — | — |
|
|
1633
|
-
| `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
|
|
1634
|
-
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1635
|
-
| `shell-focus-held` | `served/nested.spec.ts` | `the host's move takes no keyboard from where the host's page went on to in the same task (P136)`, `a second host's move into a page it just handed the focus to leaves it there: no blur, and its field keeps the keyboard (P136)` | — | — |
|
|
1636
|
-
| `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
|
|
1637
|
-
| `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
|
|
1638
|
-
| `nested-shell-origin` | `served/nested-siblings.spec.ts` | nothing | — | the host's mount refuses a shell located on any other label first, and /server serves none there (`shell-label,nested-host-label,nested-shell-origin`) |
|
|
1639
|
-
| `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
|
|
1640
|
-
| `nested-fight` | `served/nested.spec.ts` | nothing | Firefox: `a page that holds the keyboard from its load and takes it back on its own blur gets none of what the person types in the host's composer, and is stopped (P120)` | no probe can see it on Chromium and WebKit: a page can't take focus back from its own blur there, so no fight has a frame take focus again (measured) |
|
|
1641
|
-
| `shell-stall` | `served/nested.spec.ts`, `served/nested-press.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)`, `a press a shell tells after a stall is no one's (P148)` | — | — |
|
|
1642
|
-
| `press-untrusted` | `served/nested-press.spec.ts` | `a press the page makes up is none: a dispatched pointer, key or click tells the shell nothing (P148)` | — | — |
|
|
1643
|
-
| `press-role` | `served/nested-press.spec.ts` | `typing is no press, whatever the content calls the field: a role of button, a custom element's, an editable button (P148)` | — | — |
|
|
1644
|
-
| `press-editable` | `served/nested-press.spec.ts` | `typing is no press, whatever the content calls the field: a role of button, a custom element's, an editable button (P148)` | — | — |
|
|
1645
|
-
| `press-repeat` | `served/nested-press.spec.ts` | `a key held down is one press, however long it repeats (P148)` | — | — |
|
|
1646
|
-
| `press-key-click` | `served/nested-press.spec.ts` | `Enter typed in a text field is no press, though the page moves the focus to its button as the key goes down (P148)`, `a key held down is one press, however long it repeats (P148)` | — | — |
|
|
1647
|
-
| `press-submit` | `served/nested-press.spec.ts` | nothing | — | a key is down while a form clicks its submit button for an Enter, and no click is a press then: that rule refuses the click first (`press-key-click,press-submit`) |
|
|
1648
|
-
| `press-key-click,press-submit` | `served/nested-press.spec.ts` | `Enter typed in a text field is no press, though the page moves the focus to its button as the key goes down (P148)`, `a key held down is one press, however long it repeats (P148)`, `Enter in a form's text field is no press, though the form clicks its submit button (P148)` | — | — |
|
|
1649
|
-
| `press-touch-down` | `served/nested-press.spec.ts` | nothing | Chromium: `a finger that scrolls the page is no press; a tap is (P148)` | no probe can drive a finger's drag on WebKit and Firefox: a test has a tap there and no touch scroll |
|
|
1650
|
-
| `press-port-heard` | `served/nested-press.spec.ts` | `the shell's port is the runtime's alone: content's first listener hears no message that carries one (P148)` | — | — |
|
|
1651
|
-
| `press-port-forged` | `served/nested-press.spec.ts` | nothing | Chromium, WebKit: `a port message content sends itself first is not taken, and takes no place: the person's press still reaches the shell (P148)` | no probe can make the event on Firefox: its MessageEvent constructor takes no window of another origin as a source (measured), and the runtime takes a port from its parent's alone |
|
|
1652
|
-
| `press-open-lock` | `served/nested-press.spec.ts` | `a page can't open its document again to hear the port the shell sends at the next load (P148)`, `nor as soon as it runs, to hear the first port in the runtime's place (P148)` | — | — |
|
|
1653
|
-
| `press-still-here` | `served/nested-press.spec.ts` | nothing | WebKit: `a press after a link within the document is heard: the load WebKit fires for it leaves the first port the one (P148)` | no probe can see it on Chromium and Firefox: they fire no load for a navigation within the document (measured), so the shell sends no second port |
|
|
1654
|
-
| `press-host-input` | `served/nested-press.spec.ts` | `a page's focus() just after a second press in it, the person gone back to the host's composer, is taken back (P148)` | — | — |
|
|
1655
|
-
| `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
|
|
1656
|
-
| `key-press` | `served/nested-key.spec.ts` | `an activation that turned on within 250 ms of the person's key on the host's page is no gesture, where the pointer is never seen too (P122)` | — | — |
|
|
1657
|
-
| `pointer-rule` | `served/nested.spec.ts` | `an activation that came as the person typed, the pointer elsewhere, is no gesture a second on either (P120, after its review)` | — | — |
|
|
1658
1621
|
| `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
|
|
1659
1622
|
| `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
|
|
1660
1623
|
| `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
|