@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/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 on every push: the checks, the loopback suites on
578
- each engine, and the prod-shape profile.
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)` | — | — |
@@ -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.1 (2026-11-10). A review on 2026-10-19 found gaps, and every decision it led to
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, and a control passes only when its marked probes failed by their own
151
- assertion (P096).
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`). *What doesn't*: a press in the page within
1175
- 5 s of the last one turns no activation on, so a second move into it after the person went back
1176
- to the host's page is taken back until 5 s after their last press or key in the page, or they
1177
- Tab in; the page gets the keys typed while a move waits for the shell's word, or before focus is
1178
- back. No press of the person's comes within 250 ms of a key they typed on the host's page (a
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.1",
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": {
@@ -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 typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
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 (isHostOrigin(origin)) {
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 = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
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)))
@@ -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