@botiverse/porthole 0.14.3 → 0.14.4
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 +59 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/isolation/served.d.ts +17 -1
- package/dist/isolation/served.js +24 -1
- package/dist/isolation/types.d.ts +5 -0
- package/dist/isolation/types.js +5 -0
- package/dist/platform/focus-guard.d.ts +40 -0
- package/dist/platform/focus-guard.js +176 -32
- package/dist/platform/web.js +24 -9
- package/dist/server/files.js +7 -7
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/nested.d.ts +13 -7
- package/dist/server/nested.js +31 -9
- package/dist/server/server.js +5 -2
- package/dist/shell/frame.d.ts +5 -2
- package/dist/shell/frame.js +41 -18
- package/docs/ADOPTING.md +32 -14
- package/docs/ARCHITECTURE.md +5 -1
- package/docs/DECISIONS.md +312 -2
- package/docs/DESIGN.md +8 -3
- package/docs/THREAT_MODEL.md +85 -30
- package/package.json +1 -1
- package/src/host/locate.ts +2 -2
- package/src/isolation/served.ts +29 -0
- package/src/isolation/types.ts +6 -0
- package/src/platform/focus-guard.ts +218 -34
- package/src/platform/web.ts +29 -12
- package/src/server/files.ts +5 -6
- package/src/server/index.ts +1 -0
- package/src/server/nested.ts +44 -12
- package/src/server/server.ts +5 -4
- package/src/shell/frame.ts +43 -18
package/docs/DECISIONS.md
CHANGED
|
@@ -6052,7 +6052,7 @@ takes it only while it asked for it. Each item below landed on its own, with its
|
|
|
6052
6052
|
`comments` (the host's own UI; the composer is the person's, under the host's duties), and `user`
|
|
6053
6053
|
(it only reads). Tested: `test/pass-on.test.ts`, each channel alone.
|
|
6054
6054
|
|
|
6055
|
-
## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted
|
|
6055
|
+
## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted; amended by P121
|
|
6056
6056
|
|
|
6057
6057
|
**Context.** In a comment mode (Raft's web app, Kirby) the person selects words, the host's
|
|
6058
6058
|
composer opens beside them, and they post a comment or add a draft. The selection stays: the
|
|
@@ -6083,7 +6083,8 @@ There is no highlight of Porthole's own to remove: a settled selection is drawn
|
|
|
6083
6083
|
|
|
6084
6084
|
**Trust.** Host to frame only. The host takes no `clearSelection` from a frame (it is no report);
|
|
6085
6085
|
the shell takes it only from its frame's parent and the host's origins, as every host message
|
|
6086
|
-
(a page that posts it to its own window is dropped). It gives the page
|
|
6086
|
+
(a page that posts it to its own window is dropped). It gives the page no power it hasn't (but the
|
|
6087
|
+
page sees the clear, and so when the person was done with its selection: P121): a page
|
|
6087
6088
|
can clear or select its own text at any time, and can select the words again right after (the
|
|
6088
6089
|
host hears that as a selection, while it asked for text). A report the shell posted just before
|
|
6089
6090
|
the clear arrived (a selection that settled in the same moment) still reaches the host after its
|
|
@@ -6372,3 +6373,312 @@ tap); "…two markers' 44 px boxes overlap, a tap is the nearest bubble's"; "a p
|
|
|
6372
6373
|
pinned at the frame's top… takes a mouse click and a tap where it is drawn" (at its drawn
|
|
6373
6374
|
pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
|
|
6374
6375
|
with no touch and on a touch screen after a finger).
|
|
6376
|
+
|
|
6377
|
+
## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Accepted; amended by P122
|
|
6378
|
+
|
|
6379
|
+
Amends P111. **Context.** The audit of P111's guard (2026-10-28, NG-1, P0 on Firefox; porthole#56):
|
|
6380
|
+
a nested page that focuses its field as it loads and focuses it again whenever it loses focus read
|
|
6381
|
+
the person's whole comment as they typed it in the host's composer, and was never stopped. Measured
|
|
6382
|
+
again on aedc412 with the probes below (Firefox, the audit's page; the person clicks the composer
|
|
6383
|
+
and types a 42-character sentence 70 ms a key): every key to the page, one `focusTaken`, not
|
|
6384
|
+
stopped, focus left in the frame, 5 runs of 5. The page started while the person was already
|
|
6385
|
+
typing: the rest of the sentence lost in 3 of 5 runs on Firefox, 2 of 5 on the headless shell and 1
|
|
6386
|
+
of 5 on full Chromium, where the page's `comments.open`, called on the first key it got, reached the
|
|
6387
|
+
handler.
|
|
6388
|
+
|
|
6389
|
+
What ended the guard's fight each time (traces of `src/platform/focus-guard.ts`): after a take-back
|
|
6390
|
+
the page took focus again, the guard waited for the shell's word (P111), and the person's next key,
|
|
6391
|
+
typed into the page, turned the page's and so the shell's activation on. The shell said its
|
|
6392
|
+
activation turned on with no press or key on the host's page since, and the guard took the frame
|
|
6393
|
+
for the person's. On the headless shell the first move itself ended so: the shell's first word, 11
|
|
6394
|
+
ms after the move, said both that focus came in and that its activation was on (the key landed
|
|
6395
|
+
before the shell's next frame). The audit's trace, a wait that gave up when focus left the frame
|
|
6396
|
+
for a moment and so let the frame be, ends the same way. Measured too: the shell gets no event as
|
|
6397
|
+
focus comes into or leaves its child frame (Chromium, Firefox), so it can only look; the host's page
|
|
6398
|
+
sees the pointer over a frame on Firefox and the headless shell (`pointerover` on its element,
|
|
6399
|
+
`:hover`), and on full Chromium nothing past the frame's edge, and the shell sees nothing of the
|
|
6400
|
+
pointer over its child there either. A key and a press look the same in `userActivation`.
|
|
6401
|
+
|
|
6402
|
+
**Decision.**
|
|
6403
|
+
1. **A fight is judged as 0.13 judges it.** A take-back in progress is a fight when it undoes the
|
|
6404
|
+
page's own move: a take-back, `focusField`, a wait from a text field that moved on, or the person
|
|
6405
|
+
leaving a frame that took focus itself for a text field. In a fight, a nested page's frame that
|
|
6406
|
+
takes focus again is the person's only by a Tab, the host's own move, or a press the engine shows
|
|
6407
|
+
(P109's rules); its shell isn't asked. Otherwise it is taken back at once and counted as a
|
|
6408
|
+
take-back that failed (three within 10 s stop the display, whether or not the host's page saw
|
|
6409
|
+
typing). An activation the shell says turned on during a fight against its frame is uncertain
|
|
6410
|
+
(P111's word for a stall's): no one's gesture until it lapses, for `comments.open` too. The person
|
|
6411
|
+
leaving a nested page they moved into for the host's composer is no fight: going back in within
|
|
6412
|
+
300 ms waits for the shell's word, as at first.
|
|
6413
|
+
2. **A wait from a text field doesn't end with the frame let be.** If focus left the frame for
|
|
6414
|
+
nothing or for the field, with no press on the host's page since, it is the page's move still:
|
|
6415
|
+
watched as a take-back is, focus on nothing given back and counted.
|
|
6416
|
+
3. **The host asks the shell to look.** As the guard starts waiting on a move into a nested page's
|
|
6417
|
+
frame it sends the shell `porthole/shell/look` (`{ n }`); the shell looks at once and answers
|
|
6418
|
+
with its state naming the ask (`asked: n`). An answer that says focus is in the frame decides the
|
|
6419
|
+
wait: its activation if a press could have made it, else the page's move, taken back. The shell
|
|
6420
|
+
passes no message of the host's in its own namespace to the page.
|
|
6421
|
+
4. **A key is no press where the host's page sees the pointer.** Where it shows the pointer over its
|
|
6422
|
+
frames (Firefox; Chromium and WebKit where the frame is in their process, learned from a
|
|
6423
|
+
`pointerover` on one of the page's frames; full Chromium never), the shell's activation counts as
|
|
6424
|
+
a press only if the pointer is over the frame and came over it since the person last typed on
|
|
6425
|
+
the host's page, or that typing was more than a second before (`pressPossible`). Otherwise the
|
|
6426
|
+
move is the page's, taken back without waiting, and `comments.open`'s gesture isn't there.
|
|
6427
|
+
|
|
6428
|
+
**Measured** (Firefox 155, Chromium 153 full and headless shell, Playwright 1.63, on a box at load
|
|
6429
|
+
15 to 20; the probes below, 6 runs each): the page from its load, Firefox: at most 2 keys of the
|
|
6430
|
+
sentence to the page and 2 lost, three take-backs, stopped every time; Chromium and full Chromium,
|
|
6431
|
+
no key lost (a page can't take focus back on its own blur there). The page started while the
|
|
6432
|
+
person types: at most 1 key to the page on every engine, Firefox stopped every time, no
|
|
6433
|
+
`comments.open` reaching the handler. Under load (two cores, four workers, 5 runs each), P109's
|
|
6434
|
+
keyboard cases and these: 35 of 35. The ask, measured on its own: full Chromium 24 of 24 with it
|
|
6435
|
+
(with or without the pointer over the page before), 3 of 4 without; the headless shell 12 of 12
|
|
6436
|
+
where the pointer had been over the page, 7 of 12 where it never was.
|
|
6437
|
+
|
|
6438
|
+
**Threat it re-opens.** None: no gate or default loosens; the keyboard rule and `comments.open` are
|
|
6439
|
+
stricter.
|
|
6440
|
+
|
|
6441
|
+
**Cost.** In a fight, a person who presses back into a nested page within 300 ms of focus landing in
|
|
6442
|
+
the host's field has it taken back on full Chromium (elsewhere a press the engine shows counts); a
|
|
6443
|
+
Tab, or a press once the fight is over, gets in. Where the pointer is seen, an assistive
|
|
6444
|
+
technology's activation in the page within a second of typing on the host's page, with the pointer
|
|
6445
|
+
elsewhere, is taken back; a Tab, or one a second later, keeps it. One message each way per wait.
|
|
6446
|
+
|
|
6447
|
+
**Residual.** On full Chromium neither the host's page nor the shell sees the pointer over the
|
|
6448
|
+
page: a key the person types into it before the shell answers the ask (the time a message takes
|
|
6449
|
+
between the processes) is taken for a press, and the page keeps the keyboard and gets
|
|
6450
|
+
`comments.open` (0 of 24 measured). Where Chromium keeps the page's frames in the host's process
|
|
6451
|
+
(the headless shell; a person's Chrome without full site isolation, Chrome on Android), the page's
|
|
6452
|
+
input runs before the ask: there the same holds until the host's page has seen the pointer over one
|
|
6453
|
+
of the page's frames (5 of 12 in the probe's timing, its first key 10 ms after the page's move; the
|
|
6454
|
+
review of P120: a `comments.open` 990 ms after the leaked key reached the handler 2 of 2). 0.13
|
|
6455
|
+
took such a move back (no press shown), so there nested is weaker than 0.13's guard; it has been
|
|
6456
|
+
since P111, and P120 narrows it. The guard is best effort on every engine (Raft, porthole#56): a
|
|
6457
|
+
page gets the keys typed before focus is back.
|
|
6458
|
+
|
|
6459
|
+
**Tested.** `test/nested.test.ts`: `pressPossible` and the rule with it; the shell, run against a
|
|
6460
|
+
stand-in of its window, answers an ask at once naming it and passes none of the host's words in its
|
|
6461
|
+
namespace to the page. `leak/served/nested.spec.ts` on full Chromium, the headless shell and
|
|
6462
|
+
Firefox: "a page that holds the keyboard from its load and takes it back on its own blur gets none
|
|
6463
|
+
of what the person types in the host's composer, and is stopped (P120)" (fails on aedc412 on
|
|
6464
|
+
Firefox, 5 of 5). `leak/served/nested-keyboard.spec.ts`: "a page that starts taking the keyboard
|
|
6465
|
+
back on its own blur while the person types in the host's composer gets none of the rest, opens no
|
|
6466
|
+
composer, and is stopped (P120)": a race (whether a key lands before the shell looks), so it is no
|
|
6467
|
+
control's probe and runs in a file of its own, as P111's stall race does. The nested suites and
|
|
6468
|
+
P109's keyboard cases (`leak/served/runtime.spec.ts`) pass on all three. Negative control
|
|
6469
|
+
`nested-fight` (a nested frame that takes focus back in a fight is let be) fails that probe on
|
|
6470
|
+
Firefox and nothing on Chromium. `shell-host-input` alone now fails nothing where the pointer is
|
|
6471
|
+
seen (the pointer rule holds its probe too); with `pointer-rule` (the rule out) it fails it on
|
|
6472
|
+
Chromium and Firefox, as it did alone before. (After its review, the pointer rule judges the
|
|
6473
|
+
activation as it turns on, a real press there: `shell-host-input` alone fails its probe again, as
|
|
6474
|
+
in P111, and `pointer-rule` is a control of its own, below.) WebKit wasn't run (its libraries are missing on this
|
|
6475
|
+
box); it refuses a cross-origin frame's `focus()` without a gesture of its own (P111, measured).
|
|
6476
|
+
|
|
6477
|
+
**Rejected.** Waiting for the shell in a fight (what failed). Taking every unjudged move back at
|
|
6478
|
+
once and giving focus to the frame if the shell then says it was a press: the page would hear a
|
|
6479
|
+
blur and a focus on every real click (a menu that closes on blur closes). The shell telling a press
|
|
6480
|
+
from a key: it gets no event as focus comes into its child, and `userActivation` doesn't say
|
|
6481
|
+
(measured). The host's pointer as a cue on full Chromium: it stops at the frame's edge, so a
|
|
6482
|
+
real click would be taken back.
|
|
6483
|
+
|
|
6484
|
+
**After its review** (2026-10-29, OK to merge: NG-1 fixed on Firefox, the headless shell and full
|
|
6485
|
+
Chromium, under load too; non-nested frames as in 0.13; the controls fail as they should).
|
|
6486
|
+
- **P120-2 (P3).** `pressPossible` was read when a move or a `comments.open` was judged, not when
|
|
6487
|
+
the activation turned on: one it refused (within a second of typing, the pointer elsewhere) was a
|
|
6488
|
+
gesture once that second was over, while its own second still ran (about a keystroke's time;
|
|
6489
|
+
shown by driving the guard directly). Now judged as it turns on, from the person's typing and the
|
|
6490
|
+
pointer then, and carried on the shell's word (`keyed`) while it stays on. Tested:
|
|
6491
|
+
`leak/served/nested.spec.ts` "an activation that came as the person typed, the pointer elsewhere,
|
|
6492
|
+
is no gesture a second on either (P120, after its review)" (the guard driven in the browser, every
|
|
6493
|
+
engine; it failed before), negative control `pointer-rule` (the rule out) on Chromium and
|
|
6494
|
+
Firefox.
|
|
6495
|
+
- **P120-1 (P2, since P111).** Chromium with the page's frames in the host's process: named in the
|
|
6496
|
+
Residual above and in THREAT_MODEL §7, the engines and when. Not redesigned here: the host can't
|
|
6497
|
+
tell such frames before the pointer has been over one from out-of-process ones, which never show
|
|
6498
|
+
it.
|
|
6499
|
+
- **P120-3 (P3, observed once, not reproduced in about 45 runs).** On Firefox under load, a page
|
|
6500
|
+
calling `focus()` every 520 ms kept the keyboard: a word went nowhere (focus on `<body>`), then
|
|
6501
|
+
the page took it from there, a move from `<body>` that the guard lets be. The same path is in
|
|
6502
|
+
0.13's code. Suggested, not done: judge a move from `<body>` into a frame just after a text field
|
|
6503
|
+
lost focus, with no press since, as a move from that field.
|
|
6504
|
+
- **P120-4 (P3, docs).** THREAT_MODEL §7 said a page's `comments.open` on a key it got reaches no
|
|
6505
|
+
handler; that holds on Firefox and full Chromium, not on Chromium with frames in process. Now
|
|
6506
|
+
said so.
|
|
6507
|
+
|
|
6508
|
+
**Revisit when** an engine shows the host's page or a frame's parent the pointer over an
|
|
6509
|
+
out-of-process frame, says what turned activation on, or tells a frame's parent as focus comes
|
|
6510
|
+
into it; or a host can tell a frame in its own process from one out of it before the pointer has
|
|
6511
|
+
been over one (then a first move into a nested page there is judged as 0.13 judged it, P120-1).
|
|
6512
|
+
|
|
6513
|
+
## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Accepted
|
|
6514
|
+
|
|
6515
|
+
Amends P114 and P115. From the audit of aedc412 (2026-10-29; no P0 or P1): two findings on nested
|
|
6516
|
+
pages (M1, P2; M2, P3) and two on annotations (AN-1, P2; AN-2, P3).
|
|
6517
|
+
|
|
6518
|
+
- **M1.** P114's rule, that a nested page's shell runs on a `porthole-` label of its own where
|
|
6519
|
+
nothing else is served, was held by `/server` alone. A content Worker of a host's own (ADOPTING
|
|
6520
|
+
"Nested pages") had it as a duty, with no check behind it: `nestedShellResponse` took any origin,
|
|
6521
|
+
the shell ran wherever it was served, and `createHost` framed a nested page located on any
|
|
6522
|
+
content origin. A Worker that kept 0.14.0's layout (the shell on its scope's label) rebuilt
|
|
6523
|
+
porthole#56 without an error.
|
|
6524
|
+
- **M2.** A Worker of a host's own had to write a nested page's CSP sandbox (`sandbox
|
|
6525
|
+
allow-scripts`) and its scripts' (`sandbox`) by hand; `/server` built them inside its own code.
|
|
6526
|
+
- **AN-1.** THREAT_MODEL §7 and P115 said the clear gives the page nothing new. It gives the page no
|
|
6527
|
+
power, but the page sees it: the message, and a `selectionchange` to nothing with no press of its
|
|
6528
|
+
own (the audit's probe, Chromium and Firefox). ADOPTING cleared when "the selection was used (a
|
|
6529
|
+
comment posted, a draft added)", so in a comment mode where a draft is added before anything is
|
|
6530
|
+
posted, the clear told the page that a draft exists on its words, and when: what ADOPTING's
|
|
6531
|
+
`mayPassOn` rule keeps from a page that can pass it on.
|
|
6532
|
+
- **AN-2.** `tracked` (P112) moves a host's card at the page's will, up to 60 times a second, but
|
|
6533
|
+
§6's guard (no press for 500 ms after a view appears or moves) didn't name it, and ADOPTING's
|
|
6534
|
+
React example (P118) moved the card without arming it again.
|
|
6535
|
+
|
|
6536
|
+
**Decision.**
|
|
6537
|
+
1. **The shell on its own label, held where Porthole can hold it.** `isNestedLabel` and
|
|
6538
|
+
`PORTHOLE_LABEL_PREFIX` move to `isolation/served.ts` (re-exported from `/server` as before),
|
|
6539
|
+
with `onNestedLabel(origin)`. `createHost` refuses a nested config's location whose host's first
|
|
6540
|
+
label isn't a shell's (`checkFrameLocation(..., nested)`): no frame is made, a host error
|
|
6541
|
+
(`locate`) says why, the outcome is blocked (`locate`). The shell returns at once, framing
|
|
6542
|
+
nothing and saying nothing, on any origin whose first label isn't one. `nestedShellResponse`
|
|
6543
|
+
throws for such an origin, or a page on another origin, and `frameShellScript` for a page on
|
|
6544
|
+
one. What else a Worker of a host's own answers on that label stays its duty (THREAT_MODEL S3):
|
|
6545
|
+
Porthole can't see its routes.
|
|
6546
|
+
2. **`nestedFileCsp(role, directives)`** (`/server`): a page's directives and `sandbox
|
|
6547
|
+
allow-scripts`, a script's and `sandbox`, any other file `default-src 'none'; sandbox`; then
|
|
6548
|
+
`frame-ancestors` (`nestedAncestors`). `/server` uses it for every nested page and file, and
|
|
6549
|
+
ADOPTING's table for a Worker names it.
|
|
6550
|
+
3. **`clearSelection` is said to tell the page when.** THREAT_MODEL §7 and P115 say so. ADOPTING
|
|
6551
|
+
clears on every close of the composer (posted, a draft added, dismissed), or as it opens, or
|
|
6552
|
+
leaves it to the person's next click; never only when a draft is added, above all for a page
|
|
6553
|
+
`mayPassOn` says to keep drafts from.
|
|
6554
|
+
4. **`tracked` is guarded.** §6 names it; ADOPTING arms a card that follows a mark again each time
|
|
6555
|
+
it moves more than a few px (re-arming on every report would let a page that keeps its mark
|
|
6556
|
+
moving keep the card inert, which only costs its own comments).
|
|
6557
|
+
|
|
6558
|
+
**Threat it re-opens.** None. A Worker of a host's own that served the shell on another label
|
|
6559
|
+
than `nestedLabelOf`'s now fails closed (the display is blocked) where it ran before.
|
|
6560
|
+
|
|
6561
|
+
**Tested.** `test/nested.test.ts`: `frameShellScript` and `nestedShellResponse` refuse the scope's
|
|
6562
|
+
origin and a page on another origin; `onNestedLabel` takes `nestedLabelOf`'s form only (not a
|
|
6563
|
+
shorter one, not one below another label); `checkFrameLocation` refuses a nested page's location on
|
|
6564
|
+
the scope's label, as before for a config that doesn't nest; the shell's script, moved to the
|
|
6565
|
+
scope's origin and run against a stand-in of its window, frames nothing and says nothing;
|
|
6566
|
+
`nestedFileCsp` per role, never `allow-same-origin`. `/server`'s nested answers are unchanged
|
|
6567
|
+
(its tests pass as they were). `leak/served/nested-siblings.spec.ts` on full Chromium, the headless
|
|
6568
|
+
shell and Firefox: "[nested-label] a nested page located on its scope's label, not a shell's own, is
|
|
6569
|
+
refused before a frame is made (P121)". Negative controls: `nested-host-label` (the host's check
|
|
6570
|
+
out) fails it on Chromium and Firefox; `nested-shell-origin` (the shell's out) fails nothing alone,
|
|
6571
|
+
the host's check holding first; `shell-label`, which serves the shell on its scope's label, now
|
|
6572
|
+
runs with both (`shell-label,nested-host-label,nested-shell-origin`) and fails `[nested-siblings]`
|
|
6573
|
+
and `[nested-label]` as `shell-label` alone did before. WebKit wasn't run (its libraries are
|
|
6574
|
+
missing on this box). AN-1 and AN-2 are documents only: the audit's probe of the clear is its own.
|
|
6575
|
+
|
|
6576
|
+
**Rejected.** A conformance case in `defineHostConformance` asking a host's content domain for a
|
|
6577
|
+
non-nested address on a shell label (the audit's suggestion): it needs a known scope label and a
|
|
6578
|
+
second display kind from the app under test, and what it would hold (a Worker's own routes) is the
|
|
6579
|
+
host's; left for when a host with its own Worker asks for one. Hiding the clear from the page:
|
|
6580
|
+
the `selectionchange` gives it away whatever the message says.
|
|
6581
|
+
|
|
6582
|
+
## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Accepted
|
|
6583
|
+
|
|
6584
|
+
Amends P120. **Context.** CI on 0.14.4 (run 40822963445, `loopback (chromium-oopif)`): P120's
|
|
6585
|
+
case "a page that starts taking the keyboard back on its own blur while the person types…" failed
|
|
6586
|
+
on full Chromium with nothing taken back: the page read the whole secret, 35 keys. P120 measured 0
|
|
6587
|
+
of 24 on this box. On full Chromium neither the host's page nor the shell sees the pointer over the
|
|
6588
|
+
page, so the first move from a text field waits for the shell's word, and the host asks the shell to
|
|
6589
|
+
look at once (P120); on CI's runner the person's next key reached the page, and its activation the
|
|
6590
|
+
shell, before the ask did, and the guard took the activation for a press. That is the race P120
|
|
6591
|
+
named as residual, and the probe's timing (its first key a few ms after the page's move) sits in
|
|
6592
|
+
it. P120's bar was a frame in 0.13, which took such a move back.
|
|
6593
|
+
|
|
6594
|
+
CI on P120's pull request (run 40820197982) also showed the control `shell-host-input` blind on
|
|
6595
|
+
the headless shell and WebKit. P120 (after its review) judged whether the shell's activation could
|
|
6596
|
+
be a press as it turned on, from the person's typing then, but read that typing when the shell's
|
|
6597
|
+
report arrived: on a fast runner the person's first key in the composer, after their real press in
|
|
6598
|
+
the page, came before the report, and the press was taken for a key. And `navigate-guard` failed
|
|
6599
|
+
there because one of its probes errored ("Frame was detached") where the display it stood on
|
|
6600
|
+
restarted under the control, instead of failing by its verdict.
|
|
6601
|
+
|
|
6602
|
+
**Decision.**
|
|
6603
|
+
1. **No press within `KEY_PRESS_MS` (250 ms) of the person's key** on the host's page: a move into
|
|
6604
|
+
a nested page's frame that soon after the person's last key is the page's (taken back at once,
|
|
6605
|
+
no wait for the shell), and a shell's activation that turned on that soon after a key typed
|
|
6606
|
+
before it is uncertain (no one's gesture until it lapses, `comments.open` included), on every
|
|
6607
|
+
engine. A hand on the keys doesn't reach the pointer and press that fast: the Keystroke-Level
|
|
6608
|
+
Model gives 400 ms to the hand's move from the keys to the mouse alone (Card, Moran and Newell,
|
|
6609
|
+
1980). A page that takes the keyboard while the person types does it within one of their keys,
|
|
6610
|
+
so the race with the shell's answer no longer decides it.
|
|
6611
|
+
2. **The pointer rule reads the typing before the activation.** The guard keeps the last two
|
|
6612
|
+
seconds of the person's typing; whether an activation could be a press (P120's `keyed`), and
|
|
6613
|
+
whether it came within 250 ms of a key, are judged from the last key before it, never one
|
|
6614
|
+
typed after. The shell sees its activation at a look, up to a look's gap (`gap`, at most
|
|
6615
|
+
`SHELL_STALL_MS`) after it turned on: only a key before the look before counts (CI's runner
|
|
6616
|
+
typed in the host's composer within that gap after its press in the page).
|
|
6617
|
+
*What this loosens* (added after the maintainer's review, porthole#81): P120's follow-up judged
|
|
6618
|
+
an activation by the latest key the host's page had seen; this judges it by the last key before
|
|
6619
|
+
it. A key the host's page sees after an activation turned on no longer counts toward calling
|
|
6620
|
+
that activation a keystroke, so fewer activations are marked as one. It has no control of its
|
|
6621
|
+
own; P123 accepts the keyboard as a risk instead of bounding it further.
|
|
6622
|
+
3. **In-set link probes fail by their verdict**: their clicks in the frame are part of the verdict
|
|
6623
|
+
(`clickIn`), so a display that restarts under `navigate-guard` fails them as the wall seen to
|
|
6624
|
+
fail, not as an error.
|
|
6625
|
+
|
|
6626
|
+
**Cost.** A real press into a nested page within 250 ms of typing on the host's page is taken back
|
|
6627
|
+
(the person's next press gets in). The honest cases that type in the host's composer and then press
|
|
6628
|
+
the page now pause 400 ms between, as a hand does: Playwright pressed 45 ms after the last key.
|
|
6629
|
+
|
|
6630
|
+
**Residual.** On full Chromium, a person typing slower than one key in 250 ms: a key that lands
|
|
6631
|
+
in the page within the time a message takes between the processes after the page's move still
|
|
6632
|
+
passes for a press; on Chromium with frames in the host's process, until the pointer has been over
|
|
6633
|
+
one of the page's frames, within the time the page's input runs before the ask.
|
|
6634
|
+
|
|
6635
|
+
**Tested.** `test/nested.test.ts`: a move within `KEY_PRESS_MS` of the last key is the page's, a
|
|
6636
|
+
press the engine shows still counts. `leak/served/nested-key.spec.ts` (the guard driven directly,
|
|
6637
|
+
on a page that never saw the pointer, every engine): an activation 30 ms after the person's key is
|
|
6638
|
+
no gesture; a key typed after the press, before the shell's look saw it, changes nothing (that
|
|
6639
|
+
part failed on the first cut of this decision, as CI's `shell-host-input` showed). Negative control
|
|
6640
|
+
`key-press` (the window out) fails it on Chromium and Firefox; its own file, because the cases that
|
|
6641
|
+
race the shell's answer stand on the rule by chance and are no control's probes. P120's guard test
|
|
6642
|
+
puts its activation 300 ms after the key, so it stays `pointer-rule`'s alone. `shell-host-input`
|
|
6643
|
+
fails its probe again with the typing before the activation read (locally on Chromium and Firefox;
|
|
6644
|
+
CI's runners are the measure). The nested suites, P109's keyboard cases and the in-set link cases
|
|
6645
|
+
pass on full Chromium, the headless shell and Firefox; `navigate-guard`, `pointer-rule`,
|
|
6646
|
+
`nested-fight` fail exactly their probes on Chromium and Firefox. WebKit only in CI.
|
|
6647
|
+
|
|
6648
|
+
**Revisit when** an engine tells a frame's parent what turned activation on, or as focus comes into
|
|
6649
|
+
it (then the press itself can be told from a key, and the window can go).
|
|
6650
|
+
|
|
6651
|
+
|
|
6652
|
+
## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Accepted
|
|
6653
|
+
|
|
6654
|
+
**Context.** P109, P120 and P122 built a guard that gives the keyboard back when a display moves
|
|
6655
|
+
focus into its frame while the person types in the host's page. P122's review (porthole#81) showed
|
|
6656
|
+
what it can't do on a nested page: a person typing slower than one key per 250 ms (most people,
|
|
6657
|
+
phones included) isn't covered, and the page chooses when to take focus, so it can wait out any
|
|
6658
|
+
window. The owner (xxchan) and the maintainer agreed on 2026-10-29 that this class isn't worth more
|
|
6659
|
+
work.
|
|
6660
|
+
|
|
6661
|
+
**Decision.** A display taking the keyboard (`focus()` and the like) is an accepted risk, listed in
|
|
6662
|
+
THREAT_MODEL §5 "Out of scope". The existing guard stays, as best effort: it takes the keyboard back
|
|
6663
|
+
and stops a display that keeps taking it, where it can tell. No new rule is added to cover more
|
|
6664
|
+
typists or timings.
|
|
6665
|
+
|
|
6666
|
+
**Why.**
|
|
6667
|
+
- **Browsers don't let a host prevent it.** Any frame the person can type into can take focus. Other
|
|
6668
|
+
hosts of untrusted pages live with the same property; on Chrome, a claude.ai Artifact that calls
|
|
6669
|
+
`focus()` in a loop takes the keyboard from the message box (Raft's test, porthole#56).
|
|
6670
|
+
- **The person sees it.** Their text stops appearing where they type.
|
|
6671
|
+
- **The walls that matter hold without it.** A page can't reach the host's origin, its storage or
|
|
6672
|
+
another display, and a nested page's sealed address stays in a shell no content shares (P114,
|
|
6673
|
+
P121). Those stay airtight requirements.
|
|
6674
|
+
- **More rules cost real use.** A wider window takes back real clicks: P122's 250 ms rule already
|
|
6675
|
+
takes back a press within 250 ms of a key and leaves `comments.open` refused until the person
|
|
6676
|
+
pauses. Enter and Escape count as keys there too.
|
|
6677
|
+
|
|
6678
|
+
**Known and not fixed** (porthole#81): typists slower than 250 ms per key on a nested page; the
|
|
6679
|
+
probe types at 70 ms per key, so CI doesn't measure them; the usability costs above; P122's
|
|
6680
|
+
looser reading of the typing before an activation.
|
|
6681
|
+
|
|
6682
|
+
**Revisit when** a browser gives a frame's parent a way to keep focus or to know what turned
|
|
6683
|
+
activation on, or a host reports a real loss the person didn't notice.
|
|
6684
|
+
|
package/docs/DESIGN.md
CHANGED
|
@@ -998,8 +998,8 @@ for that to lapse and click with raw input.
|
|
|
998
998
|
| The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
|
|
999
999
|
| 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) |
|
|
1000
1000
|
| 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) |
|
|
1001
|
-
| 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) | `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) |
|
|
1002
|
-
| 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 | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell) 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` (the shell on the scope's label) → `[nested-siblings]` (all three) |
|
|
1001
|
+
| 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) |
|
|
1002
|
+
| 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) |
|
|
1003
1003
|
| 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`) |
|
|
1004
1004
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
1005
1005
|
|
|
@@ -1489,10 +1489,15 @@ control the tables above name to the registry):
|
|
|
1489
1489
|
| `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
|
|
1490
1490
|
| `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
|
|
1491
1491
|
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1492
|
-
| `shell-label` | `served/nested-siblings.spec.ts` | `[nested-siblings]` | — | — |
|
|
1492
|
+
| `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
|
|
1493
|
+
| `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
|
|
1494
|
+
| `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`) |
|
|
1493
1495
|
| `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)` | — | — |
|
|
1496
|
+
| `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) |
|
|
1494
1497
|
| `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)` | — | — |
|
|
1495
1498
|
| `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` | — | — |
|
|
1499
|
+
| `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)` | — | — |
|
|
1500
|
+
| `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)` | — | — |
|
|
1496
1501
|
| `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
|
|
1497
1502
|
| `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
|
|
1498
1503
|
| `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
|
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.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.4 (2026-10-29). 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
|
|
@@ -121,6 +121,14 @@ Porthole does not protect against these.
|
|
|
121
121
|
- **Deceptive content.** Content may draw anything in its frame, a fake sign-in form included.
|
|
122
122
|
Porthole limits where what is typed into it can go and keeps the host's approvals outside the
|
|
123
123
|
frame; it doesn't judge what content shows.
|
|
124
|
+
- **A display taking the keyboard** (accepted risk, P123). Content can move focus into its frame
|
|
125
|
+
(`focus()` and the like) while the person types in the host's page, and receive the keys typed
|
|
126
|
+
after it. Porthole's guard takes the keyboard back and stops a display that keeps taking it, but
|
|
127
|
+
only as best effort (§7 "The keyboard"): on a nested page it doesn't cover typing slower than one
|
|
128
|
+
key per 250 ms, which is most people, phones included. Browsers give a host no way to prevent it,
|
|
129
|
+
and the person sees their text stop appearing. The walls that hold regardless: content can't read
|
|
130
|
+
the host's page, its storage or another display, and a nested page's sealed address stays in a
|
|
131
|
+
shell no content shares.
|
|
124
132
|
- **Wrong results.** A chart can plot the wrong numbers, and a report can say false things.
|
|
125
133
|
- **Malicious prompts.** A gated `sendPrompt` hands the host's confirm function the whole text (the
|
|
126
134
|
default dialog shows all of it); whether that text is hostile is not Porthole's call. Nor is text
|
|
@@ -158,8 +166,9 @@ Whatever the use:
|
|
|
158
166
|
quoted text) only as text, never as HTML.
|
|
159
167
|
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
160
168
|
as permissions, and put nothing in a mark the page may not know (§7).
|
|
161
|
-
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected
|
|
162
|
-
comment's bubble, a composer
|
|
169
|
+
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
|
|
170
|
+
`tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
|
|
171
|
+
at will, up to 60 times a second). The content chooses when it appears and where, so it can bring it
|
|
163
172
|
under a press the person meant for the content (a double click on the content's own button whose
|
|
164
173
|
second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
|
|
165
174
|
appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
|
|
@@ -349,6 +358,11 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
349
358
|
shell's label with a one-time ticket); no host's naming makes a `porthole-` label. So no
|
|
350
359
|
content, of any scope, can read the shell's realm (its word to the host, the page's sealed
|
|
351
360
|
address) or drive it (`leak/served/nested-siblings.spec.ts`, negative control `shell-label`).
|
|
361
|
+
Porthole holds the shell to that label outside `/server` too (P121), for a content Worker of a
|
|
362
|
+
host's own: the host's mount refuses a nested page located on any other label before a frame
|
|
363
|
+
is made (a host error, `locate`; negative control `nested-host-label`), the shell frames
|
|
364
|
+
nothing and says nothing on any other origin, and `nestedShellResponse` and `frameShellScript`
|
|
365
|
+
refuse one. What else such a Worker serves on that label is its own (below).
|
|
352
366
|
The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
|
|
353
367
|
static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
|
|
354
368
|
opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
|
|
@@ -387,7 +401,8 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
387
401
|
- With nested pages, route the shell's label (`porthole-<…>.<domain>`) to the content server as
|
|
388
402
|
every content label is (a wildcard needs nothing; a pattern of the host's own, `a-*`, must add
|
|
389
403
|
it). A content Worker of the host's own serves nested pages on that label alone, and nothing
|
|
390
|
-
else there (P114)
|
|
404
|
+
else there (P114): Porthole refuses the shell anywhere else (P121), but can't see what else a
|
|
405
|
+
Worker of the host's own answers on it. Its page's and files' CSPs come from `nestedFileCsp`.
|
|
391
406
|
|
|
392
407
|
**Not guaranteed**
|
|
393
408
|
|
|
@@ -699,9 +714,15 @@ own frame, below the shell, P111), so:
|
|
|
699
714
|
`clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
|
|
700
715
|
told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
|
|
701
716
|
takes no such message from a frame, and the shell takes it only from its frame's parent (a page
|
|
702
|
-
that posts it to its own window is dropped). It gives the page
|
|
703
|
-
select its own text at any time, and can select the words again right after a clear
|
|
704
|
-
hears that as any selection, while it asked for text).
|
|
717
|
+
that posts it to its own window is dropped). It gives the page no power it lacks: a page can
|
|
718
|
+
clear or select its own text at any time, and can select the words again right after a clear
|
|
719
|
+
(the host hears that as any selection, while it asked for text). But the page sees the clear
|
|
720
|
+
(the message, and a `selectionchange` with no press of its own) and so learns when the person
|
|
721
|
+
was done with its selection (P121, after the audit of P115). A host that clears only when a
|
|
722
|
+
draft is added tells the page that a draft exists on its words, and when: clear when the
|
|
723
|
+
composer opens, or on every close, kept or dismissed, or leave it to the person's next click,
|
|
724
|
+
never only on a draft, above all for a page `mayPassOn` says to keep drafts from (ADOPTING.md
|
|
725
|
+
§ Annotations).
|
|
705
726
|
- *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
|
|
706
727
|
layer's style, lay elements over it, or transform the page it sits in), change its words so a
|
|
707
728
|
mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
|
|
@@ -766,29 +787,61 @@ unposted words beside the frame and tell the page when.
|
|
|
766
787
|
into its field is taken back every time there (the display stopped at the third), and
|
|
767
788
|
`comments.open` from a real click is refused within 5 s of any input on the host's page
|
|
768
789
|
(porthole#53). Nest it.
|
|
769
|
-
- *A nested page* (P111): the guard asks the page's shell, a realm the page can't
|
|
770
|
-
frame, whose transient activation turns on only from a press or key in the page
|
|
771
|
-
up, never down). A move into the frame is the person's if the shell's
|
|
772
|
-
the last second and the host's page had no trusted press or key
|
|
773
|
-
move, or a press the engine shows on the frame element. Nothing
|
|
774
|
-
frame, no host-wide activation. A move the shell
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
790
|
+
- *A nested page* (P111, P120, P122): the guard asks the page's shell, a realm the page can't
|
|
791
|
+
reach above its frame, whose transient activation turns on only from a press or key in the page
|
|
792
|
+
(activation goes up, never down). A move into the frame is the person's if the shell's
|
|
793
|
+
activation turned on within the last second and the host's page had no trusted press or key
|
|
794
|
+
since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
|
|
795
|
+
else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
|
|
796
|
+
hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
|
|
797
|
+
`porthole/shell/look`), then is taken back. A key the person types into the page turns its
|
|
798
|
+
activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
|
|
799
|
+
host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
|
|
800
|
+
their process, once the pointer has been over one), an activation while the pointer isn't over
|
|
801
|
+
the frame, within a second of the person typing on the host's page, is no press; and in a fight
|
|
802
|
+
over a text field (a take-back, or the person leaving a frame that took focus itself), a frame
|
|
803
|
+
that takes focus again is judged as any frame is, its shell not asked: taken back at once and
|
|
804
|
+
counted, and an activation it reports then is no one's gesture until it lapses, for
|
|
805
|
+
`comments.open` too. Measured on full Chromium, the headless shell, WebKit and Firefox
|
|
806
|
+
(`leak/served/nested.spec.ts`): a real click into the page's field keeps the keyboard; the
|
|
807
|
+
page's `focus()` as it loads, on a timer while the person types, right after a click on the
|
|
808
|
+
host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after they pressed it
|
|
809
|
+
and went back to the composer is taken back; a page that holds the keyboard from its load, or
|
|
810
|
+
takes it while the person types, and takes it back on its own blur gets at most two keys of a
|
|
811
|
+
sentence on Firefox and is stopped (none on Chromium, where a page can't take focus back on its
|
|
812
|
+
blur), and its `comments.open` on a key it got reaches no handler on Firefox and full Chromium
|
|
813
|
+
(on Chromium with frames in process it can: below); what a page says in the shell's name, to its
|
|
814
|
+
parent or to the host's window, moves nothing (negative controls `shell-namespace`,
|
|
815
|
+
`shell-host-input`, `pointer-rule`, `nested-fight`). *What doesn't*: a press in the page within
|
|
816
|
+
5 s of the last one turns no activation on, so a second move into it after the person went back
|
|
817
|
+
to the host's page is taken back until 5 s after their last press or key in the page, or they
|
|
818
|
+
Tab in; the page gets the keys typed while a move waits for the shell's word, or before focus is
|
|
819
|
+
back. No press of the person's comes within 250 ms of a key they typed on the host's page (a
|
|
820
|
+
hand goes from the keys to the pointer first): a move into the frame, or the shell's activation
|
|
821
|
+
turning on, that soon is their next key landing in the page, and is taken back, on every engine
|
|
822
|
+
(P122, after CI saw full Chromium let such a page keep the keyboard: its key outran the shell's
|
|
823
|
+
answer; negative control `key-press`). So a page that takes the keyboard while the person types
|
|
824
|
+
is taken back whatever the timing. *Still*: on full Chromium, where neither the host's page nor
|
|
825
|
+
the shell sees the pointer over the page, a key typed more than 250 ms after the person's last
|
|
826
|
+
one that reaches the page before the shell answers the host's ask (the time a message takes
|
|
827
|
+
between processes) is taken for a press, and the page keeps the keyboard and its `comments.open`
|
|
828
|
+
opens; and so, more often, where Chromium keeps the page's frames in the host's process (the
|
|
829
|
+
headless shell; a person's Chrome without full site isolation, Chrome on Android) until the
|
|
830
|
+
host's page has seen the pointer over one of the page's frames, since the page's input runs
|
|
831
|
+
before the ask there (measured in P122's review on the headless shell: a person typing one key
|
|
832
|
+
every 450 ms lost 34 of 36 keys to the page in 1 run of 8, and the page was not stopped). 0.13 took such a move back; a person typing slower than one key in 250 ms
|
|
833
|
+
is the case left, and only a key that lands within that message's time of the page's move
|
|
834
|
+
(P122); a press back into the page within 300 ms of a fight putting focus in the host's field is
|
|
835
|
+
taken back on full Chromium; where the pointer is seen, an assistive technology's activation in
|
|
836
|
+
the page within a second of typing on the host's page with the pointer elsewhere is taken back
|
|
837
|
+
(a Tab, or one a second later, keeps it); a shell without `navigator.userActivation` leaves
|
|
785
838
|
0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
|
|
786
|
-
where the frames share a process) from its own click handler would push the moment the shell
|
|
787
|
-
its activation past the person's next keys on the host's page: so the shell looks and beats
|
|
788
|
-
50 ms and says how long it went without a look, and an activation it reports after a stall
|
|
789
|
-
100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its
|
|
790
|
-
negative control `shell-stall`). The cost: in those engines a page that keeps its thread
|
|
791
|
-
the person's real click taken for uncertain until it is idle.
|
|
839
|
+
where the frames share a process) from its own click handler would push the moment the shell
|
|
840
|
+
sees its activation past the person's next keys on the host's page: so the shell looks and beats
|
|
841
|
+
every 50 ms and says how long it went without a look, and an activation it reports after a stall
|
|
842
|
+
of over 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its
|
|
843
|
+
review; negative control `shell-stall`). The cost: in those engines a page that keeps its thread
|
|
844
|
+
busy has the person's real click taken for uncertain until it is idle.
|
|
792
845
|
|
|
793
846
|
### The app runtime
|
|
794
847
|
|
|
@@ -828,7 +881,9 @@ section.
|
|
|
828
881
|
person's gesture within the last second, with no press or key on the host's page since: a real
|
|
829
882
|
click on the page's button a moment after typing in the host's composer opens it, on full
|
|
830
883
|
Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
|
|
831
|
-
name
|
|
884
|
+
name, and so is one on a key of the person's that reached the page while it fought for the
|
|
885
|
+
keyboard, or, where the host's page sees the pointer, while the pointer was elsewhere (P120). A
|
|
886
|
+
draft it gives (P108) is at most 2,000 characters of text a person can
|
|
832
887
|
see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
|
|
833
888
|
new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
|
|
834
889
|
Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.4",
|
|
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/host/locate.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { parseViewer } from "../runtime/levels.ts";
|
|
|
6
6
|
/**
|
|
7
7
|
* Where a served frame (domain or external isolation) loads from: the host's locator answers, and
|
|
8
8
|
* `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
|
|
9
|
-
* own site) before any frame is made.
|
|
9
|
+
* own site; a nested page's on a shell's own label, P121) before any frame is made.
|
|
10
10
|
*/
|
|
11
11
|
export async function locateServed(
|
|
12
12
|
locator: InstanceLocator,
|
|
@@ -16,7 +16,7 @@ export async function locateServed(
|
|
|
16
16
|
signal?: AbortSignal,
|
|
17
17
|
): Promise<FrameSource> {
|
|
18
18
|
const location = await locator.locate(instance, signal);
|
|
19
|
-
checkFrameLocation(location, config.contentOrigins, hostOrigin);
|
|
19
|
+
checkFrameLocation(location, config.contentOrigins, hostOrigin, config.nested === true);
|
|
20
20
|
// The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
|
|
21
21
|
// error, never no viewer (after the review: a mount's own would take its place).
|
|
22
22
|
const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
|