@botiverse/porthole 0.15.1 → 0.15.3
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 +42 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +5 -0
- package/dist/isolation/served.js +10 -3
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/focus-guard.d.ts +36 -0
- package/dist/platform/focus-guard.js +82 -8
- package/dist/platform/web.js +10 -2
- package/dist/server/nested.js +2 -1
- package/dist/server/pages.d.ts +9 -2
- package/dist/server/pages.js +28 -8
- package/dist/shell/annotate.js +50 -9
- package/dist/shell/frame.d.ts +1 -1
- package/dist/shell/frame.js +72 -3
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.js +259 -0
- package/docs/ADOPTING.md +5 -2
- package/docs/DECISIONS.md +370 -3
- package/docs/DESIGN.md +18 -3
- package/docs/THREAT_MODEL.md +39 -8
- package/package.json +1 -1
- package/src/isolation/served.ts +12 -3
- package/src/isolation/types.ts +7 -0
- package/src/platform/focus-guard.ts +126 -11
- package/src/platform/web.ts +15 -2
- package/src/server/nested.ts +2 -1
- package/src/server/pages.ts +38 -12
- package/src/shell/annotate.ts +50 -9
- package/src/shell/frame.ts +76 -3
- package/src/shell/plan.ts +7 -0
- package/src/shell/runtime.ts +259 -0
package/docs/DECISIONS.md
CHANGED
|
@@ -3149,7 +3149,7 @@ a page's updates heard by the next page, code a viewer uploaded made runnable by
|
|
|
3149
3149
|
keeps partitioned cookies there (then `/_blob/<id>` loads everywhere and `assets.url` is a
|
|
3150
3150
|
convenience); or a host needs per-collection levels beyond a batch's.
|
|
3151
3151
|
|
|
3152
|
-
## P097 · 2026-10-19 · A release is a commit of main that passed all of CI; the open-source materials · Accepted
|
|
3152
|
+
## P097 · 2026-10-19 · A release is a commit of main that passed all of CI; the open-source materials · Accepted; amended by P146
|
|
3153
3153
|
|
|
3154
3154
|
The 2026-10-19 audit's V03 and its licenses-and-materials findings (baseline 264b12fa). Before,
|
|
3155
3155
|
a pushed `v*` tag published from one job that ran `check`, the build and the Chromium bundle test,
|
|
@@ -4757,7 +4757,7 @@ the content can't steal, likely the host's own overlay), a bubble must follow du
|
|
|
4757
4757
|
coarser report, or the host drawing markers itself from `anchored`), or MCP Apps defines
|
|
4758
4758
|
annotations.
|
|
4759
4759
|
|
|
4760
|
-
## P096 · 2026-10-19 · The negative controls: one registry, every control run, and a run that proves nothing fails · Accepted
|
|
4760
|
+
## P096 · 2026-10-19 · The negative controls: one registry, every control run, and a run that proves nothing fails · Accepted; amended by P146
|
|
4761
4761
|
|
|
4762
4762
|
Amends P032 (what DESIGN.md records per control), P091's harness item (`scripts/controls.ts`) and
|
|
4763
4763
|
P097's CI triggers. From the audit of 2026-10-19 (V01, V02).
|
|
@@ -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` · Accepted
|
|
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` · Accepted; amended by P148
|
|
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
|
|
@@ -9157,3 +9157,370 @@ each fail exactly their probe on all three. The old spec with its document in tw
|
|
|
9157
9157
|
**Revisit when** the runtime pin changes (say what changed), a host needs `embed` from a reader's
|
|
9158
9158
|
route (then it needs its own entry, never `access`), or a browser stops exposing
|
|
9159
9159
|
`ancestorOrigins` to a framed page.
|
|
9160
|
+
|
|
9161
|
+
**Amended in 0.15.3, after the audit of 0.15.1 (N1): the helpers that take host origins check
|
|
9162
|
+
them.** Decision 4 says every helper that takes host origins or `framedBy` throws on a bad one.
|
|
9163
|
+
For `framedBy` that held (`ancestorsOf`). For host origins it held in `createServer`, the host kit
|
|
9164
|
+
and `frameShellScript`, and not in four helpers a content Worker of a host's own calls itself:
|
|
9165
|
+
`statusPage`, `doorResponse`, `doorStatusResponse` and `nestedShellCsp` took `hostOrigins` as they
|
|
9166
|
+
came, so `https://app.example:0` passed and `"https://a; script-src *"` went into the
|
|
9167
|
+
`Content-Security-Policy` header as written. What they are given is the host's own configuration,
|
|
9168
|
+
not content's, so nothing reached them that a host didn't write; the claim was wrong, and a header
|
|
9169
|
+
built from an unchecked string is not something to leave. Each now runs `hostOriginProblem` over
|
|
9170
|
+
every origin and throws a `TypeError` naming itself (`doorResponse: hostOrigins: …`), with
|
|
9171
|
+
`frameAncestors` given or not; an embed's status pages name no host and check none. And the
|
|
9172
|
+
exported `isHostOrigin` now says no to what `hostOriginProblem` refuses (`:0`, a port past 65535 or
|
|
9173
|
+
with a leading zero, a host the URL parser rewrites): it tested the shape alone. `test/origins.test.ts`.
|
|
9174
|
+
|
|
9175
|
+
## P146 · 2026-11-10 · CI's full set runs before a release, not on every push · Accepted
|
|
9176
|
+
|
|
9177
|
+
Amends P096 (its decision 4: what a push runs; its decision 6: the shards run by hand) and P097
|
|
9178
|
+
(its decision 1: which run the gate takes). From the owner's direction (xxchan, 2026-11-10:
|
|
9179
|
+
Porthole's tests cut to what is needed or made cheaper; Raft's Artifacts are the real-world check;
|
|
9180
|
+
the security tests are worth keeping; the heavy suites only at a release is fine) and the CI cost
|
|
9181
|
+
review that moved CI to GitHub's runners (#130).
|
|
9182
|
+
|
|
9183
|
+
**Context**, measured on 2026-11-03T16:00Z to 11-10T16:00Z (Blacksmith's 4-vCPU runners, each job
|
|
9184
|
+
rounded up to a minute):
|
|
9185
|
+
- 94 ci.yml runs (57 pull requests', 35 pushes to main, 2 by hand) and 14 releases: 36,789 runner
|
|
9186
|
+
minutes. The controls were 31,760 of them (86%), the loopback suites 3,756, prod-shape 830, the
|
|
9187
|
+
examples 324, the checks 119.
|
|
9188
|
+
- One whole run is about 420 minutes: the controls 370 (12 shards of 25 to 35), loopback 36 (the
|
|
9189
|
+
headless shell 11, full Chromium 2, WebKit 12, Firefox 12), prod-shape 8, the examples 3, the
|
|
9190
|
+
checks 1 (types, lint, format and the unit tests together are 15 seconds of it).
|
|
9191
|
+
- The registry has 105 controls. Each is one Playwright run of its specs with one wall out, on one
|
|
9192
|
+
engine: 7 seconds (`url-permissions`) to 14 minutes (`nonce`), about two hours an engine (116,
|
|
9193
|
+
121 and 124 minutes). 46 of them run the whole of `annotate.spec.ts` or `leak.spec.ts` (226 of
|
|
9194
|
+
the 361 minutes), `nonce` 43.
|
|
9195
|
+
- Every pull request's push and every merge paid all of it; a release needs it once, on the commit
|
|
9196
|
+
it publishes.
|
|
9197
|
+
|
|
9198
|
+
**Decision.**
|
|
9199
|
+
1. **ci.yml has two sets of jobs.** The quick set runs on every pull request's push, every push to
|
|
9200
|
+
main and by hand: `check`, `examples`, `loopback (chromium)` and `loopback (chromium-oopif)`
|
|
9201
|
+
(every spec on Chromium, and the nested page's cases on full Chromium, frames out of process:
|
|
9202
|
+
P111). The full set runs only in a run started by hand (`workflow_dispatch`): `loopback
|
|
9203
|
+
(webkit)`, `loopback (firefox)`, the twelve `controls (<engine>, k/4)` shards, `controls` and
|
|
9204
|
+
`prod-shape`. Each job of the full set carries `if: github.event_name == 'workflow_dispatch'`,
|
|
9205
|
+
the one condition a job of ci.yml may carry (P097 had none), and no step that runs the
|
|
9206
|
+
project's code is conditional. The two loopback jobs (`loopback`, and `loopback-engines` under
|
|
9207
|
+
the same names) have the same steps; a test holds them equal. A run started by hand skips
|
|
9208
|
+
nothing, so it is the whole of ci.yml, as every run was before.
|
|
9209
|
+
2. **A release needs the full run on its commit, as before, and now asks for it.** release.yml's
|
|
9210
|
+
gate takes the newest ci.yml run on `main` for the released commit that was started by hand,
|
|
9211
|
+
and no other: a push's run (its full set skipped) is no run to it, as a pull request's never
|
|
9212
|
+
was. `REQUIRED_CI_JOBS` is unchanged, all twenty jobs by name, and each must have passed in its
|
|
9213
|
+
latest attempt, so a run whose full set was skipped fails on each skipped job even if it were
|
|
9214
|
+
taken. A release is two commands: `stamp workflow run ci.yml --repo botiverse/porthole` (main's
|
|
9215
|
+
head), then `stamp workflow run release.yml --repo botiverse/porthole -f version=X.Y.Z`. The
|
|
9216
|
+
gate waits for a full run that is still going (`CI_WAIT_MINUTES`) and, after ten minutes with
|
|
9217
|
+
none, says to start one. The gate's permissions stay `contents: read`, `actions: read`: it
|
|
9218
|
+
starts nothing itself.
|
|
9219
|
+
3. **Nothing cancels a run started by hand.** ci.yml's concurrency group is
|
|
9220
|
+
`ci-<event>-<ref>-push` for a push (was `ci-<ref>`) and `ci-<event>-<ref>-<run id>` for a run
|
|
9221
|
+
started by hand: a newer push still replaces an older push's run on its ref, but neither a
|
|
9222
|
+
merge to main nor a second full run started for a newer commit cancels the full run a release
|
|
9223
|
+
is waiting for (before, a merge cancelled main's run, and the release of the earlier commit
|
|
9224
|
+
with it; Tenny's review of #131 for the second case).
|
|
9225
|
+
4. **A change to a wall asks for the full set before it merges** (AGENTS.md): a pull request that
|
|
9226
|
+
touches isolation, egress, the shell, the focus guard, a probe or a control starts the full
|
|
9227
|
+
run on its branch (`--ref <branch>`), since its own CI shows Chromium and no control.
|
|
9228
|
+
5. **No test was removed.** Looked at for this: the unit tests are seconds for all 60 files, and
|
|
9229
|
+
the whole loopback suite is 10 to 12 minutes an engine (652 tests), now run on Chromium per
|
|
9230
|
+
push and on the others per release, so removing behaviour tests would save a minute or two of
|
|
9231
|
+
a run that is no longer the cost. The behaviour cases share their specs with the probes
|
|
9232
|
+
(`annotate.spec.ts`: a hostile page's faked reports beside the markers' placing), and every
|
|
9233
|
+
control judges the other tests of its specs too (P096), so a case cut from one changes what 23
|
|
9234
|
+
controls check; none was clearly redundant enough to cut without running the suites. The
|
|
9235
|
+
candidates, measured on Chromium, are for a change that can run them: `check.spec.ts`'s ten
|
|
9236
|
+
presets over every manual example (124 of the suite's 1,240 test-seconds), and the shipped
|
|
9237
|
+
probes run again against the strict page, the kit's app, the example app and prod-shape (the
|
|
9238
|
+
same walls in each deployment's shape: security, kept).
|
|
9239
|
+
|
|
9240
|
+
**Expected**, for the same week's activity: the quick set's four jobs were 1,739 of the minutes
|
|
9241
|
+
above; 14 full runs are about 5,900; about 7,600 in all, a fifth of 36,789. Full runs on branches
|
|
9242
|
+
(decision 4) add 420 each. On GitHub's runners the minutes cost nothing; what they save there is
|
|
9243
|
+
the queue (a full run is 19 jobs at once, a quick one 4).
|
|
9244
|
+
|
|
9245
|
+
**Why.** The controls test the tests (PRINCIPLE 6: a wall never seen to fail proves nothing): they
|
|
9246
|
+
change when a wall, a probe or the registry changes, and what must never happen is a release
|
|
9247
|
+
whose walls were not seen to fail. That is a property of the released commit, and the gate holds
|
|
9248
|
+
it there, with the same twenty jobs, by name. Running it 94 times a week to publish 14 commits
|
|
9249
|
+
bought an earlier answer for the pull requests that touch a wall, at five times the price; those can
|
|
9250
|
+
ask for it (decision 4). The quick set keeps what a pull request most often breaks in front of its
|
|
9251
|
+
author: types, lint, the unit tests, the built package, the example app through the adopter's
|
|
9252
|
+
suite, and every browser spec on one engine in both its builds: about 18 runner minutes, and 12
|
|
9253
|
+
of waiting.
|
|
9254
|
+
|
|
9255
|
+
**Accepted limits.**
|
|
9256
|
+
- A regression only WebKit or Firefox shows, or only a control sees (a probe gone blind), or only
|
|
9257
|
+
prod-shape, is found at the release's full run, or at a branch's, not at every pull request. The
|
|
9258
|
+
cost is a fix and another full run; nothing unverified is published.
|
|
9259
|
+
- The pull request's checks list the full set's jobs as skipped (a matrix job once, under its
|
|
9260
|
+
name's template). Skipped is not passed: the gate reads each job's conclusion.
|
|
9261
|
+
- As P097: the gate is in the file it guards, and stops mistakes, not someone who can push.
|
|
9262
|
+
|
|
9263
|
+
**Rejected.**
|
|
9264
|
+
- *The full set on pushes to main, the quick set on pull requests*: 35 merges a week at 420
|
|
9265
|
+
minutes is still 14,700, for commits most of which are never published, and the release's
|
|
9266
|
+
answer then arrives after the merge either way.
|
|
9267
|
+
- *The controls on one engine per push*: a third of 86% is still most of the cost, and the
|
|
9268
|
+
controls' per-engine entries (`fails` per engine, `holds`, `measured`) are what the other two
|
|
9269
|
+
engines check.
|
|
9270
|
+
- *A second workflow file for the full set*: two lists of required jobs (or the quick jobs written
|
|
9271
|
+
twice), and a gate that reads two workflows' runs; one file with one condition keeps
|
|
9272
|
+
`REQUIRED_CI_JOBS` the one list.
|
|
9273
|
+
- *release.yml running the suites itself* (a called workflow before `build`): the release's run
|
|
9274
|
+
would execute the project's browser suites for an hour, a flake would fail the release rather
|
|
9275
|
+
than a run one can start again, and the suites could no longer be run without releasing.
|
|
9276
|
+
- *The gate starting the full run* (`actions: write`): more than the gate needs to read a verdict.
|
|
9277
|
+
- *A weekly scheduled full run*: with two releases a day it adds nothing; see Revisit.
|
|
9278
|
+
- *Each control run with its named probes alone* (`--grep`): the controls' cost would fall
|
|
9279
|
+
several times over, but P096's "and nothing else" (a control that fails more is a probe that
|
|
9280
|
+
depends on something else) would go unchecked. A design question of its own, not a trim.
|
|
9281
|
+
- *Removing behaviour tests now* (decision 5).
|
|
9282
|
+
|
|
9283
|
+
**Tested.** `test/release.test.ts`: the quick set is exactly `check`, `examples`, `loopback
|
|
9284
|
+
(chromium)`, `loopback (chromium-oopif)`, and the full set the other sixteen; a job's only
|
|
9285
|
+
condition is the one above, whole; a job that needs one of the full set is of it; the two sets
|
|
9286
|
+
together are `REQUIRED_CI_JOBS`, each once; the two loopback jobs' steps are equal; no step that
|
|
9287
|
+
runs code is conditional, none may fail; the concurrency group; the gate's script selects
|
|
9288
|
+
`workflow_dispatch` and names no other event. `test/release-scripts.test.ts`, against the
|
|
9289
|
+
simulated API: a run by hand that passed is let through, whatever the commit's push run said; a
|
|
9290
|
+
push's run alone is "no full ci.yml run", and the jobs are never read; a run whose full set was
|
|
9291
|
+
skipped names each of the sixteen and stops; the newest run by hand decides; a pull request's is
|
|
9292
|
+
ignored; a pending one is waited for. `test/controls.test.ts`: the shards and their summary are of
|
|
9293
|
+
the full set. With the gate taking pushes again, a job's condition removed, or the old concurrency
|
|
9294
|
+
group, five of these fail.
|
|
9295
|
+
|
|
9296
|
+
**Revisit when** releases come less than weekly (add a scheduled full run on main, and let the
|
|
9297
|
+
gate take it); a release's full run fails on what the quick set could have shown more than now and
|
|
9298
|
+
then (move that suite or engine into the quick set); GitHub's runners queue a full run for long
|
|
9299
|
+
(the shard count, `MEASURED`); or the controls are redesigned to run less (the rejected `--grep`).
|
|
9300
|
+
|
|
9301
|
+
## P147 · 2026-11-11 · Marks ride the document's scroll: a scroll timeline moves them, not the scroll event · Accepted
|
|
9302
|
+
|
|
9303
|
+
Amends P104 (how a mark follows a scroll) and P132. From Raft (xxchan, 2026-11-10, a screen
|
|
9304
|
+
recording): scrolling a page with comments, the highlight on the commented words and the marker
|
|
9305
|
+
beside them trail the text and catch up a moment later.
|
|
9306
|
+
|
|
9307
|
+
**Context.** The layer is fixed and covers the viewport (P104), and every box in it is placed in
|
|
9308
|
+
the viewport. A scroll moved the page and not the layer; the runtime heard the scroll event, drew
|
|
9309
|
+
again in that frame's animation callback, and the boxes were right again. That is as early as a
|
|
9310
|
+
script can be, and it is late: a browser scrolls on its compositor, and puts frames on the screen
|
|
9311
|
+
at the new scroll offset before the main thread has run the scroll event for it. In those frames
|
|
9312
|
+
the words have moved and the boxes have not. No ordering of the script fixes it; only something the
|
|
9313
|
+
compositor moves with the scroll does.
|
|
9314
|
+
|
|
9315
|
+
**Decision.**
|
|
9316
|
+
1. **One box in the layer holds everything drawn** (marks, markers, the held selection, the
|
|
9317
|
+
picking outline and its tag): `.ride`, a child of the layer's shadow root. The layer itself is
|
|
9318
|
+
unchanged: fixed, the viewport's size, clipped, its inline style reset at each draw (P104), so
|
|
9319
|
+
it still adds nothing to what the page can scroll and nothing of the page's sizes it.
|
|
9320
|
+
2. **Each box's top is its place in the document down the page**: its top in the viewport plus how
|
|
9321
|
+
far the document is scrolled, both read in the one task that draws (`scrollTop` of
|
|
9322
|
+
`document.scrollingElement`, through getters taken before content runs, P129). `.ride` is moved
|
|
9323
|
+
up by the scroll by a scroll-driven animation: `animation-timeline: scroll(root y)`, one
|
|
9324
|
+
keyframe at `translateY(-range)`, where the range (`scrollHeight - clientHeight`, set as
|
|
9325
|
+
`--ride` at each draw) is what that timeline runs over. The engine runs it with the scroll, so
|
|
9326
|
+
in every frame a box is where its words are.
|
|
9327
|
+
3. **The scroll event still draws**, as before. For a page scrolled down by its root, that draw
|
|
9328
|
+
now writes the places the boxes already have. It is what still moves a mark in a scroller of
|
|
9329
|
+
the page's own (an `overflow: auto` element), which no root timeline follows: there a mark
|
|
9330
|
+
catches up from the event, as it did everywhere before.
|
|
9331
|
+
4. **Down the page only.** Sideways a box stays placed in the viewport and follows from the event:
|
|
9332
|
+
a document scrolled sideways is rare, its scroll runs the other way where the text does (a
|
|
9333
|
+
right-to-left page), and one axis keeps the arithmetic to one number.
|
|
9334
|
+
5. **Where there is no scroll timeline** (`CSS.supports("animation-timeline: scroll()")`, asked
|
|
9335
|
+
once before content runs: Firefox today), and where the root does not scroll (the range is 0,
|
|
9336
|
+
the timeline is inactive and moves nothing), every top is the viewport's and the event draws,
|
|
9337
|
+
exactly as before this decision.
|
|
9338
|
+
6. **A mark on something the page keeps in place** (`position: fixed`, or `sticky` while stuck)
|
|
9339
|
+
now does the opposite of what the others did: it rides with the document for the frames before
|
|
9340
|
+
the event's draw puts it back. Accepted for now: comments on a fixed header are few beside
|
|
9341
|
+
comments on the text, and telling them apart costs a computed style up the tree for every mark
|
|
9342
|
+
at every draw. **Revisit** with a second, unridden box for such marks if a host reports it.
|
|
9343
|
+
|
|
9344
|
+
**What a page can do with it.** Nothing it could not: the layer was always in the page's own
|
|
9345
|
+
document, where the page can cover it or move it with its ancestors (P104). The animation and its
|
|
9346
|
+
keyframes are in the closed shadow root's sheet; `--ride` is set on `.ride` there, where no page
|
|
9347
|
+
style reaches (a custom property inherits into a shadow tree from its host, and `.ride` sets its
|
|
9348
|
+
own). A page that changes how tall it is between two draws shifts the boxes by the difference
|
|
9349
|
+
times how far it is scrolled, until the next draw (a mutation, a resize or a scroll): the marks of
|
|
9350
|
+
its own content, drawn a little off, for a moment.
|
|
9351
|
+
|
|
9352
|
+
**Threat.** None opened. No new message, no new reading: the scroll offset was already read for
|
|
9353
|
+
P132's reports (through the root's box; here through `scrollTop`, the number the timeline uses).
|
|
9354
|
+
|
|
9355
|
+
**Revisit when** an engine ships scroll timelines without running them on the compositor (the ride
|
|
9356
|
+
would then be no better than the event, and no worse); a host needs marks in the page's own
|
|
9357
|
+
scrollers to ride too (a timeline per scroller, named from the mark's nearest one); or decision 6's
|
|
9358
|
+
case is reported.
|
|
9359
|
+
|
|
9360
|
+
## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds · Accepted
|
|
9361
|
+
|
|
9362
|
+
Amends P111 (its "Rejected", and item 4 of its "Threat it re-opens"). From Raft (xxchan,
|
|
9363
|
+
2026-11-11): a page's own button that calls `comments.open`; the host answers with a dialog; the
|
|
9364
|
+
person cancels it and presses the button again, and nothing happens ("This needs a click"), nor at
|
|
9365
|
+
the next press; some seconds later it works. Raft's pages are served, not nested: in full Chromium
|
|
9366
|
+
the host's page sees no press in their frame, and a press there counts only once the host's page
|
|
9367
|
+
has had no gesture of its own for 5 s (P109). ADOPTING's answer is to nest such pages (P111). But a
|
|
9368
|
+
nested page had the same dead button, for the 5 s after any gesture (below), so nesting was no
|
|
9369
|
+
answer to this report until that was closed. This decision closes it; it changes nothing for a
|
|
9370
|
+
page that isn't nested. Designed on one page first, attacked by Ferryman before any code (his
|
|
9371
|
+
findings are items 2, 4 and 5 below), accepted by the CTO with the bounds of item 1.
|
|
9372
|
+
|
|
9373
|
+
**Context.** P111 takes "the person is in this frame" from the shell's own transient activation
|
|
9374
|
+
turning on: within the last second, with no trusted press or key on the host's page since. An
|
|
9375
|
+
activation stays on for about 5 s, so a press in the page within 5 s of the last gesture turns
|
|
9376
|
+
nothing on, and a press in the page within 5 s of a press on the host's page can't be told from
|
|
9377
|
+
the page borrowing the host's. P111 accepted that. In use it is a button that does nothing:
|
|
9378
|
+
`leak/served/nested-press.spec.ts`'s first case, run against 0.15.2, has a press one second after
|
|
9379
|
+
a press on the host's page refused on full Chromium and on Firefox (the headless shell and WebKit
|
|
9380
|
+
show the host's page the press on the frame itself, and pass).
|
|
9381
|
+
|
|
9382
|
+
P111 rejected "the page's runtime reporting its own gestures (the page's word, in the page's
|
|
9383
|
+
realm)": the runtime and the content share a document, and whatever the runtime posts to the
|
|
9384
|
+
shell, the content can post from the same window. That holds for a message to a window. It doesn't
|
|
9385
|
+
for a `MessagePort` only the runtime holds, carrying an event only the browser makes.
|
|
9386
|
+
|
|
9387
|
+
**Decision.**
|
|
9388
|
+
1. **A port per load, from the shell.** At each `load` of its page's frame the shell makes a
|
|
9389
|
+
`MessageChannel`, keeps one end and posts the other to the page (`porthole/shell/press-port`,
|
|
9390
|
+
in the shell's own namespace, which it passes neither way). It hears only the port of the
|
|
9391
|
+
frame's last load, and forgets what it heard of a press before that load.
|
|
9392
|
+
2. **The runtime takes it before any content runs, and no content ever holds it.** The first
|
|
9393
|
+
listener there is (on `window`, capturing) takes the port from the first message that is the
|
|
9394
|
+
browser's own (`isTrusted`), from the parent read at the runtime's start, naming the method,
|
|
9395
|
+
with exactly one port, and stops the event there. Every other event of that name is stopped
|
|
9396
|
+
too. One that fails a check doesn't use up the one port (a page that dispatches a
|
|
9397
|
+
`MessageEvent` of its own before the shell's arrives would otherwise have the real port dropped:
|
|
9398
|
+
no press forged, but the feature silently off). The port lives in the runtime's closure.
|
|
9399
|
+
Two walls this rests on, both already there, now named as its preconditions:
|
|
9400
|
+
`document.open()` takes every listener off a window, the runtime's among them, and a document
|
|
9401
|
+
opened and closed again fires the frame's `load` again (measured on Chromium 153 and Firefox
|
|
9402
|
+
155, and WebKit here): the runtime's lock on `Document.prototype.open`, `write` and `writeln`
|
|
9403
|
+
(there for declarative shadow DOM) is what keeps a page from hearing the port in the runtime's
|
|
9404
|
+
place; and a nested page is `sandbox="allow-scripts"`, so every frame of its own is another
|
|
9405
|
+
opaque origin, with no unlocked `open` to borrow. If the lock on any of the three couldn't be
|
|
9406
|
+
fixed in place, or any built-in this uses is missing, or the plan names no host, **none of it is
|
|
9407
|
+
installed**: no port is taken and no press is told, and the host has the shell's activation
|
|
9408
|
+
alone, as before.
|
|
9409
|
+
3. **What is told is that there was a press, and nothing else**: no place, no target, no time. The
|
|
9410
|
+
shell notes when it heard it, on its own clock, and tells the host in its state (`pressed`: how
|
|
9411
|
+
long ago; `presses`: how many it has heard, so the host knows a new one).
|
|
9412
|
+
4. **What a press is** (every one the browser's own event, read through getters kept before
|
|
9413
|
+
content ran):
|
|
9414
|
+
- a mouse going down (`pointerdown`, `pointerType` `mouse`);
|
|
9415
|
+
- a finger or a pen coming up (`pointerup`, any other `pointerType`). A finger that scrolls goes
|
|
9416
|
+
down too and ends in `pointercancel`: counted as it lands, scrolling the page would open the
|
|
9417
|
+
gate for a second. This is HTML's own list of what activates;
|
|
9418
|
+
- Enter or Space going down, not a repeat of a held key, on a native control that isn't
|
|
9419
|
+
editable: `button`, `summary`, `input` of type button, submit or reset; Enter alone on
|
|
9420
|
+
`a[href]`. By tag and type, never `role`, which is the content's word: `role="button"` on a
|
|
9421
|
+
text field (or on a custom element around one) would make every space typed there a press,
|
|
9422
|
+
and P120's "typing is no press" would be the content's to decide. A custom element is never
|
|
9423
|
+
one, so the focus inside its shadow tree, open or closed, tells nothing;
|
|
9424
|
+
- a click on such a control (an assistive technology activates a button with a click alone),
|
|
9425
|
+
but none while a key is down (from the browser's own `keydown` to its `keyup`, or the next
|
|
9426
|
+
press of a pointer): the key's own press was judged as it went down, where it went down.
|
|
9427
|
+
Without that, content that moves the focus to its button inside the `keydown` of an Enter
|
|
9428
|
+
typed in a text field gets the button a click of the browser's own, the focus on it
|
|
9429
|
+
(Ferryman, on the code: measured on Chromium 153 and Firefox 155, and WebKit here); and a
|
|
9430
|
+
held key's repeats give a button a click each. Behind it, not the click a form gives its
|
|
9431
|
+
submit button for Enter in another of its controls (the two forms read through each
|
|
9432
|
+
control's own `form`: a field tied by its `form` attribute is not inside the form's
|
|
9433
|
+
element).
|
|
9434
|
+
5. **The host judges a press told exactly as an activation that turned on.** For a second
|
|
9435
|
+
(`SHELL_GESTURE_MS`), a move of focus into the frame, or a `comments.open`, is the person's,
|
|
9436
|
+
**with no trusted press or key on the host's page since** (the design page had this signal
|
|
9437
|
+
need no quiet host; it keeps one, which costs the case this is for nothing: the dialog's
|
|
9438
|
+
Cancel is before the press). And, as for an activation: not a press told in a fight over a
|
|
9439
|
+
text field (P120), not one within 250 ms of the person's key on the host's page (P122), not
|
|
9440
|
+
one told within a second of their typing with the pointer elsewhere, where the host's page
|
|
9441
|
+
sees the pointer (P120), and not one told in or just after a stall of the shell (below). A
|
|
9442
|
+
press told while the focus is already in the frame makes the frame the person's from there on,
|
|
9443
|
+
as a move they made into it does.
|
|
9444
|
+
6. **A stalled shell.** The shell notes a press when it hears it. Where the page shares the
|
|
9445
|
+
shell's thread, a page that holds it from its own click handler makes that as late as it
|
|
9446
|
+
likes, past the person going back to the host's page (P111, after its review). An activation
|
|
9447
|
+
seen after a stall is uncertain because the look that sees it turn on is the first look after
|
|
9448
|
+
the stall, and says its gap. A press is another message: when the page lets go, the shell's own
|
|
9449
|
+
timer may run first and say the stall, and the press follow a moment later with no gap of its
|
|
9450
|
+
own (seen on the first cut of this decision: `leak/served/nested-stall.spec.ts` failed on
|
|
9451
|
+
Chromium with frames in process). So the host notes when the shell was last seen to have
|
|
9452
|
+
stalled (a report or a heartbeat after more than `SHELL_STALL_MS` of silence, or a report that
|
|
9453
|
+
says such a gap), and a press told within `SHELL_AFTER_STALL_MS` (500 ms) of that is no one's.
|
|
9454
|
+
7. **What the page says next follows the press.** A call made in the press's own handler (a tap's
|
|
9455
|
+
click, a key's click) leaves the page a moment after the press does, on another channel, and
|
|
9456
|
+
could arrive first. After it tells a press, the runtime holds what it posts to its host until
|
|
9457
|
+
the shell answers on the port, which the shell does only after it has told the host; 250 ms
|
|
9458
|
+
without an answer and it holds nothing back. Content that posts past the runtime orders its
|
|
9459
|
+
own messages, at its own cost.
|
|
9460
|
+
8. **A load that isn't a new document.** WebKit fires the frame's `load` for a navigation within
|
|
9461
|
+
the document (P142). The shell then sends a second port to a runtime that takes only one, and
|
|
9462
|
+
would hear the first no more. That runtime answers the second port on the first (`1`: this
|
|
9463
|
+
document is still here), which only it can, and the shell goes back to the first and shuts the
|
|
9464
|
+
new one. A new document's runtime never has the port before.
|
|
9465
|
+
9. **Nested pages only** (`plan.press`, from `nested: true`). A served, opaque or proxied page's
|
|
9466
|
+
runtime carries the code and installs none of it; their plans are as before.
|
|
9467
|
+
|
|
9468
|
+
**Why the rejected alternative holds now.** What P111 feared was the content speaking as the
|
|
9469
|
+
runtime. It can't post on a port it never holds (2), and can't make the runtime post for an event
|
|
9470
|
+
it made up (4: `isTrusted` is an own, unforgeable property of each event; nothing else it could
|
|
9471
|
+
shape decides, since the tag, type, key, repeat, pointer type, target and form are read through
|
|
9472
|
+
getters taken before it ran). The runtime's word here stands where its other walls do (the
|
|
9473
|
+
navigation guard, P129, P130): its code runs first and calls only what it kept.
|
|
9474
|
+
|
|
9475
|
+
**What it does not say.** Which element was pressed, or that the press was meant for the call
|
|
9476
|
+
that follows. That is the activation rule's own limit. Content can put the focus on its own
|
|
9477
|
+
button and wait for the person's Enter meant for something else: with the shell's activation off
|
|
9478
|
+
that already passed for a gesture (P111, P120's residual); now it does within 5 s of the last
|
|
9479
|
+
gesture too, under the same rules of item 5.
|
|
9480
|
+
|
|
9481
|
+
**Threat.** One message more from the shell to the page (a port, nothing in it), two content-free
|
|
9482
|
+
values on that port, and two numbers more in the shell's state. No secret is in any of them. The
|
|
9483
|
+
gate P111 keeps shut for 5 s after any gesture now opens for a second after a real press in the
|
|
9484
|
+
page: the case P111's "Threat it re-opens" (4) accepted as a loss is the one given back. A page
|
|
9485
|
+
that could take the port could tell presses that never were, and with the person active on the
|
|
9486
|
+
host's page within 5 s open a comment composer or keep the keyboard: items 2 and 4 are what
|
|
9487
|
+
stands in the way, each with a control that takes it out.
|
|
9488
|
+
|
|
9489
|
+
**Residual.** A key on a control that isn't native (a `div` with `role="button"`, a custom
|
|
9490
|
+
element) tells nothing: the 5 s of P111 stay for it. So they do on an engine where the runtime
|
|
9491
|
+
can't install all of this (one without `PointerEvent`, say): nothing is told there. A press within 500 ms
|
|
9492
|
+
of a stall of the shell is dropped, a slow page's own included. The shell's stamp is when it
|
|
9493
|
+
heard the press, a message's time after it was made: a press on the host's page within that time
|
|
9494
|
+
of a press in the page reads as before it.
|
|
9495
|
+
|
|
9496
|
+
**Tested.** `test/nested.test.ts` (the shell's script in a stub page): one port per load; a press
|
|
9497
|
+
is told to the host before it is answered; anything else on the port is none; a new load's port
|
|
9498
|
+
replaces the last and forgets its press; "still here" restores the port before; the plan asks
|
|
9499
|
+
only a nested page; `shellPress`, `shellSaw` and `personMoved` on a press told.
|
|
9500
|
+
`leak/served/nested-press.spec.ts`, real input only, on full Chromium, the headless shell, WebKit
|
|
9501
|
+
and Firefox: a second and a third press after presses on the host's page open `comments` (refused
|
|
9502
|
+
before this decision on full Chromium and Firefox); Enter on the page's button, its call made in the key's
|
|
9503
|
+
own click, is allowed (not Firefox, where a page's own `focus()` puts no key on its button); a
|
|
9504
|
+
page's `focus()` 700 ms after a second press, the person back in the host's composer, is taken
|
|
9505
|
+
back; every event a page can dispatch tells nothing; typing in a text field, one with
|
|
9506
|
+
`role="button"`, one in a custom element with that role, and an editable button tells nothing; a
|
|
9507
|
+
held key is one press; Enter typed in a field tells none though the page moves the focus to its
|
|
9508
|
+
button as the key goes down, and none though a form clicks its button for it; a
|
|
9509
|
+
finger that scrolls tells none and a tap one (Chromium, the only engine a test can drag a finger
|
|
9510
|
+
on); content's first listener hears no port; a port message content sends itself first is not
|
|
9511
|
+
taken and takes no place (Firefox makes no such event); a page can't open its document again,
|
|
9512
|
+
at a later moment or as soon as it runs; a press after a link within the document is heard; the
|
|
9513
|
+
host's rule on a press told after a stall.
|
|
9514
|
+
Negative controls, each failing its probe on every engine it names: `press-untrusted`,
|
|
9515
|
+
`press-role`, `press-editable`, `press-repeat`, `press-key-click`, `press-submit` (behind
|
|
9516
|
+
`press-key-click`: it fails its probe with both out), `press-touch-down` (Chromium),
|
|
9517
|
+
`press-port-heard`, `press-port-forged` (Chromium, WebKit), `press-open-lock`,
|
|
9518
|
+
`press-still-here` (WebKit), `press-host-input`, and `shell-stall` (now this rule's too). No
|
|
9519
|
+
control for item 7 (an order between two channels: with the hold out it is lost only sometimes),
|
|
9520
|
+
nor for "only the last load's port" (nothing of a document outlives it to speak on the port it
|
|
9521
|
+
held: a second wall behind item 2, held by the unit test).
|
|
9522
|
+
|
|
9523
|
+
**Revisit when** an engine shows the host's page a press in an out-of-process frame (P111's own
|
|
9524
|
+
condition: this and the activation rule could then both go); a host reports the residual for
|
|
9525
|
+
controls that aren't native (then a rule for `role` that typing can't satisfy); or the 500 ms
|
|
9526
|
+
after a stall drops presses people notice.
|
package/docs/DESIGN.md
CHANGED
|
@@ -574,8 +574,9 @@ the system store for WebKit; Playwright's Firefox reads neither, so its project
|
|
|
574
574
|
certificate errors). The suite (`packages/porthole/prod-shape`) runs the whole runner over https,
|
|
575
575
|
then the sibling cases: Porthole's cookies host-only and `__Host-`; a sibling label (an app's
|
|
576
576
|
preview) can't plant a cookie that opens content, or frame it; another site can't frame it; the
|
|
577
|
-
clash. CI (`.github/workflows/ci.yml`) runs
|
|
578
|
-
each engine, and the
|
|
577
|
+
clash. CI (`.github/workflows/ci.yml`) runs the checks, the examples and the loopback suites on
|
|
578
|
+
Chromium on every push, and the loopback suites on each engine, the negative controls and the
|
|
579
|
+
prod-shape profile when started by hand, which a release requires on its commit (P146).
|
|
579
580
|
|
|
580
581
|
**Compatibility.** Every 0.1.x export stays as it was; the kit wraps `createServer`. The npm
|
|
581
582
|
package carries these docs (`docs/`), and `/server` exports the types an app's callbacks take
|
|
@@ -1008,6 +1009,7 @@ for that to lapse and click with raw input.
|
|
|
1008
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) |
|
|
1009
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) |
|
|
1010
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` |
|
|
1011
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` |
|
|
1012
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) |
|
|
1013
1015
|
| 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`) |
|
|
@@ -1636,7 +1638,20 @@ control the tables above name to the registry):
|
|
|
1636
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`) |
|
|
1637
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)` | — | — |
|
|
1638
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) |
|
|
1639
|
-
| `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
|
|
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)` | — | — |
|
|
1640
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` | — | — |
|
|
1641
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)` | — | — |
|
|
1642
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)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.15.
|
|
8
|
+
**Status.** This describes Porthole 0.15.3 (2026-11-11). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -69,6 +69,23 @@ P144: their "byte for byte" is said as it holds (above); the host kit refuses an
|
|
|
69
69
|
with `embed`, so a reader's issue endpoint never mints an embed session (S4); an embed page learns
|
|
70
70
|
where it is embedded (S4); and a host origin's or `framedBy`'s port is 1 to 65535, without a
|
|
71
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.
|
|
72
89
|
|
|
73
90
|
## 1. Two layers
|
|
74
91
|
|
|
@@ -147,8 +164,9 @@ viewer and any declaration.
|
|
|
147
164
|
The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
|
|
148
165
|
WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
|
|
149
166
|
its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs every negative
|
|
150
|
-
control on all three engines
|
|
151
|
-
|
|
167
|
+
control on all three engines on the commit of every release (P146: the release's gate requires
|
|
168
|
+
that run; a pull request's CI runs the suite on Chromium, with no control), and a control passes
|
|
169
|
+
only when its marked probes failed by their own assertion (P096).
|
|
152
170
|
|
|
153
171
|
## 5. Out of scope
|
|
154
172
|
|
|
@@ -1171,11 +1189,24 @@ unposted words beside the frame and tell the page when.
|
|
|
1171
1189
|
blur), and its `comments.open` on a key it got reaches no handler on Firefox and full Chromium
|
|
1172
1190
|
(on Chromium with frames in process it can: below); what a page says in the shell's name, to its
|
|
1173
1191
|
parent or to the host's window, moves nothing (negative controls `shell-namespace`,
|
|
1174
|
-
`shell-host-input`, `pointer-rule`, `nested-fight`).
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1192
|
+
`shell-host-input`, `pointer-rule`, `nested-fight`). A press in the page within 5 s of the last
|
|
1193
|
+
gesture turns no activation on; the page's runtime tells the shell each real press instead
|
|
1194
|
+
(P148), over a port no content holds, and the host takes a press told as it takes an activation
|
|
1195
|
+
turning on: for a second, with no press or key on the host's page since, not in a fight, not
|
|
1196
|
+
within 250 ms of the person's key, not within 500 ms of a stall of the shell. A press is the
|
|
1197
|
+
browser's own event alone (a mouse down; a finger or pen up, so a scroll is none; Enter or Space,
|
|
1198
|
+
not held, on a native control that isn't editable, by its tag and never its `role`; a click on
|
|
1199
|
+
one, but none while a key is down, nor a form's own for Enter in a field); nothing a page
|
|
1200
|
+
dispatches is one, and
|
|
1201
|
+
nothing a page does gets it the port (`leak/served/nested-press.spec.ts`; negative controls
|
|
1202
|
+
`press-untrusted`, `press-role`, `press-editable`, `press-repeat`, `press-key-click`,
|
|
1203
|
+
`press-submit`,
|
|
1204
|
+
`press-touch-down`, `press-port-heard`, `press-port-forged`, `press-open-lock`,
|
|
1205
|
+
`press-still-here`, `press-host-input`). *What doesn't*: a key on a control that isn't native
|
|
1206
|
+
(a `div` with `role="button"`) tells nothing, so a move into the page by it within 5 s of the
|
|
1207
|
+
last gesture is still taken back, until they Tab in; so is any press where the runtime couldn't
|
|
1208
|
+
install its part; the page gets the keys typed while a move waits for the shell's word, or
|
|
1209
|
+
before focus is back. No press of the person's comes within 250 ms of a key they typed on the host's page (a
|
|
1179
1210
|
hand goes from the keys to the pointer first): a move into the frame, or the shell's activation
|
|
1180
1211
|
turning on, that soon is their next key landing in the page, and is taken back, on every engine
|
|
1181
1212
|
(P122, after CI saw full Chromium let such a page keep the keyboard: its key outran the shell's
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.15.
|
|
3
|
+
"version": "0.15.3",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/isolation/served.ts
CHANGED
|
@@ -63,8 +63,17 @@ export function isExactOrigin(origin: unknown): origin is string {
|
|
|
63
63
|
const HOST_ORIGIN =
|
|
64
64
|
/^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*|\[[0-9a-f:.]+\])(:\d{1,5})?$/u;
|
|
65
65
|
|
|
66
|
+
/** Whether `origin` is written as an origin is (`HOST_ORIGIN`), whatever a browser makes of it. */
|
|
67
|
+
const shapedAsOrigin = (origin: unknown): origin is string =>
|
|
68
|
+
typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Whether `origin` can be a host origin: written as one, and one a browser serializes as it is
|
|
72
|
+
* written (`serializable`: never `:0`, a port past 65535 or with a leading zero, a host the URL
|
|
73
|
+
* parser would rewrite). `hostOriginProblem` says why not.
|
|
74
|
+
*/
|
|
66
75
|
export function isHostOrigin(origin: unknown): origin is string {
|
|
67
|
-
return
|
|
76
|
+
return shapedAsOrigin(origin) && serializable(origin);
|
|
68
77
|
}
|
|
69
78
|
|
|
70
79
|
/**
|
|
@@ -94,7 +103,7 @@ function serializable(origin: string): boolean {
|
|
|
94
103
|
|
|
95
104
|
/** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
|
|
96
105
|
export function hostOriginProblem(origin: unknown): string | null {
|
|
97
|
-
if (
|
|
106
|
+
if (shapedAsOrigin(origin)) {
|
|
98
107
|
return serializable(origin)
|
|
99
108
|
? null
|
|
100
109
|
: `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
|
|
@@ -142,7 +151,7 @@ const LOOPBACK_HOST = (host: string): boolean =>
|
|
|
142
151
|
* in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
|
|
143
152
|
*/
|
|
144
153
|
export function framedByProblem(origin: unknown): string | null {
|
|
145
|
-
const parsed =
|
|
154
|
+
const parsed = shapedAsOrigin(origin) ? parseOrigin(origin) : null;
|
|
146
155
|
if (
|
|
147
156
|
parsed === null ||
|
|
148
157
|
!(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))
|
package/src/isolation/types.ts
CHANGED
|
@@ -107,6 +107,13 @@ export const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
|
107
107
|
*/
|
|
108
108
|
export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
109
109
|
|
|
110
|
+
/**
|
|
111
|
+
* A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
|
|
112
|
+
* of the page's frame, over which the runtime tells the shell each real press in the page. The
|
|
113
|
+
* runtime takes the first one alone, before any content runs, and no content ever holds it.
|
|
114
|
+
*/
|
|
115
|
+
export const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
|
|
116
|
+
|
|
110
117
|
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
111
118
|
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
112
119
|
|