@botiverse/porthole 0.14.2 → 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.
@@ -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.2 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
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`: a
162
- comment's bubble, a composer). The content chooses when it appears and where, so it can bring it
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
 
@@ -679,7 +694,12 @@ own frame, below the shell, P111), so:
679
694
  `marker-prevent`), so content can't act on it or cancel it; nor can it read or reach inside the
680
695
  shell's layer (a closed shadow root). Content can still tell that a marker was pressed, and
681
696
  roughly where: the pointer leaving its own element names the layer, the layer matches `:hover`
682
- and `:active`, and the frame gets user activation.
697
+ and `:active`, and the frame gets user activation. On touch (P119), a marker is also the
698
+ 44 by 44 px box around its bubble, drawn in that same layer: a tap there is a press on the
699
+ marker, with the same checks (a trusted click, the main button, on the layer), so the content
700
+ loses a tap within 13 px of a bubble (a few px of its words above and below it), as it loses
701
+ one on the bubble. Which pointer is used is read from trusted pointer events only; a page that
702
+ makes its own up changes nothing, and a real `activated` still needs a real click.
683
703
  - *What doesn't hold against content that does.* The shell shares the content's realm. It reads
684
704
  and stops a marker's press through the platform's own functions and getters, kept before
685
705
  content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
@@ -694,9 +714,15 @@ own frame, below the shell, P111), so:
694
714
  `clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
695
715
  told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
696
716
  takes no such message from a frame, and the shell takes it only from its frame's parent (a page
697
- that posts it to its own window is dropped). It gives the page nothing new: a page can clear or
698
- select its own text at any time, and can select the words again right after a clear (the host
699
- 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).
700
726
  - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
701
727
  layer's style, lay elements over it, or transform the page it sits in), change its words so a
702
728
  mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
@@ -761,29 +787,61 @@ unposted words beside the frame and tell the page when.
761
787
  into its field is taken back every time there (the display stopped at the third), and
762
788
  `comments.open` from a real click is refused within 5 s of any input on the host's page
763
789
  (porthole#53). Nest it.
764
- - *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
765
- frame, whose transient activation turns on only from a press or key in the page (activation goes
766
- up, never down). A move into the frame is the person's if the shell's activation turned on within
767
- the last second and the host's page had no trusted press or key since; or a Tab, the host's own
768
- move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
769
- frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
770
- frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
771
- and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
772
- keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
773
- click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
774
- they pressed it and went back to the composer is taken back; what a page says in the shell's
775
- name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
776
- `shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
777
- activation on, so a second move into it after the person went back to the host's page is taken
778
- back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
779
- typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
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
780
838
  0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
781
- where the frames share a process) from its own click handler would push the moment the shell sees
782
- its activation past the person's next keys on the host's page: so the shell looks and beats every
783
- 50 ms and says how long it went without a look, and an activation it reports after a stall of over
784
- 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
785
- negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
786
- 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.
787
845
 
788
846
  ### The app runtime
789
847
 
@@ -823,7 +881,9 @@ section.
823
881
  person's gesture within the last second, with no press or key on the host's page since: a real
824
882
  click on the page's button a moment after typing in the host's composer opens it, on full
825
883
  Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
826
- name. A draft it gives (P108) is at most 2,000 characters of text a person can
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
827
887
  see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
828
888
  new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
829
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.2",
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": {
@@ -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);
@@ -27,6 +27,28 @@ export function parseOrigin(origin: string): ParsedOrigin | null {
27
27
  return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
28
28
  }
29
29
 
30
+ /**
31
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
32
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
33
+ */
34
+ export const PORTHOLE_LABEL_PREFIX = "porthole-";
35
+
36
+ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
37
+
38
+ /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
39
+ export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
40
+
41
+ /**
42
+ * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
43
+ * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
44
+ * each refuse any other origin, so a content Worker of a host's own can't put it beside other
45
+ * content by mistake.
46
+ */
47
+ export function onNestedLabel(origin: string): boolean {
48
+ const parsed = parseOrigin(origin);
49
+ return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
50
+ }
51
+
30
52
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
31
53
  export function isExactOrigin(origin: unknown): origin is string {
32
54
  return typeof origin === "string" && parseOrigin(origin) !== null;
@@ -124,6 +146,8 @@ export function checkFrameLocation(
124
146
  location: FrameLocation,
125
147
  contentOrigins: readonly string[],
126
148
  hostOrigin: string,
149
+ /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
150
+ nested = false,
127
151
  ): void {
128
152
  const origin = parseOrigin(location.origin);
129
153
  let url: URL;
@@ -143,6 +167,11 @@ export function checkFrameLocation(
143
167
  `The located origin ${location.origin} is not one of the config's content origins`,
144
168
  );
145
169
  }
170
+ if (nested && !onNestedLabel(location.origin)) {
171
+ throw new TypeError(
172
+ `The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`,
173
+ );
174
+ }
146
175
  const host = parseOrigin(hostOrigin);
147
176
  if (host !== null && maybeSameSite(origin.host, host.host)) {
148
177
  throw new TypeError(
@@ -80,6 +80,12 @@ export const SHELL_STATE_METHOD = "porthole/shell/state";
80
80
  /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
81
81
  export const SHELL_BEAT_METHOD = "porthole/shell/beat";
82
82
 
83
+ /**
84
+ * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
85
+ * that names the ask (`asked`). The host asks as it hears focus move into the frame.
86
+ */
87
+ export const SHELL_LOOK_METHOD = "porthole/shell/look";
88
+
83
89
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
84
90
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
85
91