@botiverse/porthole 0.14.3 → 0.14.5

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.
Files changed (45) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/conformance/harness-source.js +1 -1
  4. package/dist/host/create-host.js +2 -0
  5. package/dist/host/locate.d.ts +1 -1
  6. package/dist/host/locate.js +2 -2
  7. package/dist/host/outcome.d.ts +4 -0
  8. package/dist/host/outcome.js +43 -0
  9. package/dist/host/types.d.ts +12 -4
  10. package/dist/isolation/served.d.ts +17 -1
  11. package/dist/isolation/served.js +24 -1
  12. package/dist/isolation/types.d.ts +5 -0
  13. package/dist/isolation/types.js +5 -0
  14. package/dist/platform/focus-guard.d.ts +40 -0
  15. package/dist/platform/focus-guard.js +176 -32
  16. package/dist/platform/web.js +24 -9
  17. package/dist/react/frame.d.ts +2 -1
  18. package/dist/server/files.js +7 -7
  19. package/dist/server/index.d.ts +1 -1
  20. package/dist/server/index.js +1 -1
  21. package/dist/server/nested.d.ts +13 -7
  22. package/dist/server/nested.js +31 -9
  23. package/dist/server/server.js +5 -2
  24. package/dist/shell/frame.d.ts +5 -2
  25. package/dist/shell/frame.js +41 -18
  26. package/docs/ADOPTING.md +37 -14
  27. package/docs/ARCHITECTURE.md +5 -1
  28. package/docs/DECISIONS.md +404 -2
  29. package/docs/DESIGN.md +11 -4
  30. package/docs/THREAT_MODEL.md +116 -32
  31. package/package.json +1 -1
  32. package/src/host/create-host.ts +2 -0
  33. package/src/host/locate.ts +2 -2
  34. package/src/host/outcome.ts +49 -0
  35. package/src/host/types.ts +12 -4
  36. package/src/isolation/served.ts +29 -0
  37. package/src/isolation/types.ts +6 -0
  38. package/src/platform/focus-guard.ts +218 -34
  39. package/src/platform/web.ts +29 -12
  40. package/src/react/frame.tsx +2 -1
  41. package/src/server/files.ts +5 -6
  42. package/src/server/index.ts +1 -0
  43. package/src/server/nested.ts +44 -12
  44. package/src/server/server.ts +5 -4
  45. package/src/shell/frame.ts +43 -18
@@ -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.3 (2026-10-29). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.5 (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
@@ -81,7 +81,10 @@ the agent, but it is not a wall.
81
81
  - everything beyond drawing is a host function the config declares, behind gates: a user
82
82
  gesture, a person's confirmation, consent, a rate;
83
83
  - the host draws its confirmations and consent outside the frame, where content can't draw over
84
- them.
84
+ them;
85
+ - the host's fallback for a frame that showed nothing ("open this in a new tab to sign in",
86
+ "you no longer have access", with a link) is drawn from Porthole's pages' word only, never
87
+ from what the content says (P124; a url-mode app aside, S6).
85
88
 
86
89
  The app runtime adds a third: **the host's API is the wall for its data.** The bridge refuses a
87
90
  call the page didn't declare (`undeclared`), or that the viewer's level doesn't allow, before any
@@ -121,6 +124,14 @@ Porthole does not protect against these.
121
124
  - **Deceptive content.** Content may draw anything in its frame, a fake sign-in form included.
122
125
  Porthole limits where what is typed into it can go and keeps the host's approvals outside the
123
126
  frame; it doesn't judge what content shows.
127
+ - **A display taking the keyboard** (accepted risk, P123). Content can move focus into its frame
128
+ (`focus()` and the like) while the person types in the host's page, and receive the keys typed
129
+ after it. Porthole's guard takes the keyboard back and stops a display that keeps taking it, but
130
+ only as best effort (§7 "The keyboard"): on a nested page it doesn't cover typing slower than one
131
+ key per 250 ms, which is most people, phones included. Browsers give a host no way to prevent it,
132
+ and the person sees their text stop appearing. The walls that hold regardless: content can't read
133
+ the host's page, its storage or another display, and a nested page's sealed address stays in a
134
+ shell no content shares.
124
135
  - **Wrong results.** A chart can plot the wrong numbers, and a report can say false things.
125
136
  - **Malicious prompts.** A gated `sendPrompt` hands the host's confirm function the whole text (the
126
137
  default dialog shows all of it); whether that text is hostile is not Porthole's call. Nor is text
@@ -156,10 +167,16 @@ Whatever the use:
156
167
  host's own UI. A copy notice of its own shows what went on the clipboard (S1).
157
168
  - Show the text content reports (its errors, a blocked navigation's address, an annotation's
158
169
  quoted text) only as text, never as HTML.
170
+ - Draw a frame's fallback (what `frameFallback` words, or your own) from its `outcome` alone, never
171
+ from a message of your own reading off the frame's window: a `blocked` outcome is the word of a
172
+ page of Porthole's server, a gateway or your own pages, never of an opaque frame or of content in
173
+ a frame that speaks (P124). Hear the `frame-status` host error as a display trying to speak as
174
+ Porthole: log it, and show nothing for it. A url-mode app can still say any outcome (S6).
159
175
  - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
160
176
  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
177
+ - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
178
+ `tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
179
+ at will, up to 60 times a second). The content chooses when it appears and where, so it can bring it
163
180
  under a press the person meant for the content (a double click on the content's own button whose
164
181
  second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
165
182
  appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
@@ -349,6 +366,11 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
349
366
  shell's label with a one-time ticket); no host's naming makes a `porthole-` label. So no
350
367
  content, of any scope, can read the shell's realm (its word to the host, the page's sealed
351
368
  address) or drive it (`leak/served/nested-siblings.spec.ts`, negative control `shell-label`).
369
+ Porthole holds the shell to that label outside `/server` too (P121), for a content Worker of a
370
+ host's own: the host's mount refuses a nested page located on any other label before a frame
371
+ is made (a host error, `locate`; negative control `nested-host-label`), the shell frames
372
+ nothing and says nothing on any other origin, and `nestedShellResponse` and `frameShellScript`
373
+ refuse one. What else such a Worker serves on that label is its own (below).
352
374
  The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
353
375
  static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
354
376
  opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
@@ -387,7 +409,8 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
387
409
  - With nested pages, route the shell's label (`porthole-<…>.<domain>`) to the content server as
388
410
  every content label is (a wildcard needs nothing; a pattern of the host's own, `a-*`, must add
389
411
  it). A content Worker of the host's own serves nested pages on that label alone, and nothing
390
- else there (P114).
412
+ else there (P114): Porthole refuses the shell anywhere else (P121), but can't see what else a
413
+ Worker of the host's own answers on it. Its page's and files' CSPs come from `nestedFileCsp`.
391
414
 
392
415
  **Not guaranteed**
393
416
 
@@ -560,6 +583,11 @@ the attacker (c), and its readers are strangers.
560
583
  **Not guaranteed**
561
584
 
562
585
  - The app's network is its own.
586
+ - The app's word about how it loaded is its own: it shares its origin with Porthole's entry page
587
+ and status pages and has no shell to speak first, so it can make the display's `outcome` any
588
+ `blocked`, with any code, and the host show its fallback ("open this in a new tab to sign in")
589
+ with a link out of the page (P124). A host that previews code it doesn't trust words that
590
+ fallback as its own, not as Porthole's or the person's sign-in.
563
591
  - A page on another origin can still open the app by a navigation (a link, a frame of its own),
564
592
  which reaches the app's GET routes as any link does.
565
593
  - A request with neither `Origin` nor `Sec-Fetch-Site` goes on: in browsers without fetch
@@ -608,6 +636,21 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
608
636
  **The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
609
637
  effects are its own), and group displays by page (S7).
610
638
 
639
+ **The host's fallback** (P040, P124). A display's `outcome` says how its frame loaded, and a host
640
+ draws its own UI on a `blocked` one, in Porthole's wording (`frameFallback`: "Open this in a new
641
+ tab to sign in", "You can't open this anymore") with a link out of the page: UI the person takes
642
+ for the host's and Porthole's, which content must not be able to summon. A `blocked` comes from a
643
+ frame status (`porthole/notifications/frame-status`), and nothing in that message says who sent
644
+ it: Porthole's status pages are documents of the frame's own window and origin, as content is. So
645
+ the host takes one only where content can't have said it: never from an opaque frame (no page of
646
+ Porthole's loads there), and in a frame that speaks (a served shell, a view through the sandbox
647
+ proxy, a nested page's shell) only before anything else is heard from it in the run, since
648
+ Porthole's own word opens every document that holds content, before the content runs, and a status
649
+ page says nothing else. What it drops is no outcome and no code; the host hears a `frame-status`
650
+ host error, once a run (control `frame-status`). What follows: in a display with files, a page of
651
+ the set answered by a status page (access revoked) shows the server's words in the frame, and the
652
+ host isn't told until the next mount. Not covered: a url-mode app (S6).
653
+
611
654
  **Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
612
655
  its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
613
656
  own frame, below the shell, P111), so:
@@ -699,9 +742,15 @@ own frame, below the shell, P111), so:
699
742
  `clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
700
743
  told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
701
744
  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 nothing new: a page can clear or
703
- select its own text at any time, and can select the words again right after a clear (the host
704
- hears that as any selection, while it asked for text).
745
+ that posts it to its own window is dropped). It gives the page no power it lacks: a page can
746
+ clear or select its own text at any time, and can select the words again right after a clear
747
+ (the host hears that as any selection, while it asked for text). But the page sees the clear
748
+ (the message, and a `selectionchange` with no press of its own) and so learns when the person
749
+ was done with its selection (P121, after the audit of P115). A host that clears only when a
750
+ draft is added tells the page that a draft exists on its words, and when: clear when the
751
+ composer opens, or on every close, kept or dismissed, or leave it to the person's next click,
752
+ never only on a draft, above all for a page `mayPassOn` says to keep drafts from (ADOPTING.md
753
+ § Annotations).
705
754
  - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
706
755
  layer's style, lay elements over it, or transform the page it sits in), change its words so a
707
756
  mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
@@ -766,29 +815,61 @@ unposted words beside the frame and tell the page when.
766
815
  into its field is taken back every time there (the display stopped at the third), and
767
816
  `comments.open` from a real click is refused within 5 s of any input on the host's page
768
817
  (porthole#53). Nest it.
769
- - *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
770
- frame, whose transient activation turns on only from a press or key in the page (activation goes
771
- up, never down). A move into the frame is the person's if the shell's activation turned on within
772
- the last second and the host's page had no trusted press or key since; or a Tab, the host's own
773
- move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
774
- frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
775
- frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
776
- and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
777
- keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
778
- click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
779
- they pressed it and went back to the composer is taken back; what a page says in the shell's
780
- name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
781
- `shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
782
- activation on, so a second move into it after the person went back to the host's page is taken
783
- back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
784
- typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
818
+ - *A nested page* (P111, P120, P122): the guard asks the page's shell, a realm the page can't
819
+ reach above its frame, whose transient activation turns on only from a press or key in the page
820
+ (activation goes up, never down). A move into the frame is the person's if the shell's
821
+ activation turned on within the last second and the host's page had no trusted press or key
822
+ since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
823
+ else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
824
+ hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
825
+ `porthole/shell/look`), then is taken back. A key the person types into the page turns its
826
+ activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
827
+ host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
828
+ their process, once the pointer has been over one), an activation while the pointer isn't over
829
+ the frame, within a second of the person typing on the host's page, is no press; and in a fight
830
+ over a text field (a take-back, or the person leaving a frame that took focus itself), a frame
831
+ that takes focus again is judged as any frame is, its shell not asked: taken back at once and
832
+ counted, and an activation it reports then is no one's gesture until it lapses, for
833
+ `comments.open` too. Measured on full Chromium, the headless shell, WebKit and Firefox
834
+ (`leak/served/nested.spec.ts`): a real click into the page's field keeps the keyboard; the
835
+ page's `focus()` as it loads, on a timer while the person types, right after a click on the
836
+ host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after they pressed it
837
+ and went back to the composer is taken back; a page that holds the keyboard from its load, or
838
+ takes it while the person types, and takes it back on its own blur gets at most two keys of a
839
+ sentence on Firefox and is stopped (none on Chromium, where a page can't take focus back on its
840
+ blur), and its `comments.open` on a key it got reaches no handler on Firefox and full Chromium
841
+ (on Chromium with frames in process it can: below); what a page says in the shell's name, to its
842
+ parent or to the host's window, moves nothing (negative controls `shell-namespace`,
843
+ `shell-host-input`, `pointer-rule`, `nested-fight`). *What doesn't*: a press in the page within
844
+ 5 s of the last one turns no activation on, so a second move into it after the person went back
845
+ to the host's page is taken back until 5 s after their last press or key in the page, or they
846
+ Tab in; the page gets the keys typed while a move waits for the shell's word, or before focus is
847
+ back. No press of the person's comes within 250 ms of a key they typed on the host's page (a
848
+ hand goes from the keys to the pointer first): a move into the frame, or the shell's activation
849
+ turning on, that soon is their next key landing in the page, and is taken back, on every engine
850
+ (P122, after CI saw full Chromium let such a page keep the keyboard: its key outran the shell's
851
+ answer; negative control `key-press`). So a page that takes the keyboard while the person types
852
+ is taken back whatever the timing. *Still*: on full Chromium, where neither the host's page nor
853
+ the shell sees the pointer over the page, a key typed more than 250 ms after the person's last
854
+ one that reaches the page before the shell answers the host's ask (the time a message takes
855
+ between processes) is taken for a press, and the page keeps the keyboard and its `comments.open`
856
+ opens; and so, more often, where Chromium keeps the page's frames in the host's process (the
857
+ headless shell; a person's Chrome without full site isolation, Chrome on Android) until the
858
+ host's page has seen the pointer over one of the page's frames, since the page's input runs
859
+ before the ask there (measured in P122's review on the headless shell: a person typing one key
860
+ 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
861
+ is the case left, and only a key that lands within that message's time of the page's move
862
+ (P122); a press back into the page within 300 ms of a fight putting focus in the host's field is
863
+ taken back on full Chromium; where the pointer is seen, an assistive technology's activation in
864
+ the page within a second of typing on the host's page with the pointer elsewhere is taken back
865
+ (a Tab, or one a second later, keeps it); a shell without `navigator.userActivation` leaves
785
866
  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 sees
787
- its activation past the person's next keys on the host's page: so the shell looks and beats every
788
- 50 ms and says how long it went without a look, and an activation it reports after a stall of over
789
- 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
790
- negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
791
- the person's real click taken for uncertain until it is idle.
867
+ where the frames share a process) from its own click handler would push the moment the shell
868
+ sees its activation past the person's next keys on the host's page: so the shell looks and beats
869
+ every 50 ms and says how long it went without a look, and an activation it reports after a stall
870
+ of over 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its
871
+ review; negative control `shell-stall`). The cost: in those engines a page that keeps its thread
872
+ busy has the person's real click taken for uncertain until it is idle.
792
873
 
793
874
  ### The app runtime
794
875
 
@@ -828,7 +909,9 @@ section.
828
909
  person's gesture within the last second, with no press or key on the host's page since: a real
829
910
  click on the page's button a moment after typing in the host's composer opens it, on full
830
911
  Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
831
- name. A draft it gives (P108) is at most 2,000 characters of text a person can
912
+ name, and so is one on a key of the person's that reached the page while it fought for the
913
+ keyboard, or, where the host's page sees the pointer, while the pointer was elsewhere (P120). A
914
+ draft it gives (P108) is at most 2,000 characters of text a person can
832
915
  see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
833
916
  new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
834
917
  Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
@@ -898,7 +981,8 @@ The decisions below come from the 2026-10-19 review, and all of them have merged
898
981
  what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
899
982
  are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
900
983
  of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0), P114 (a nested page's shell on a label of
901
- its own, after porthole#56; in 0.14.1).
984
+ its own, after porthole#56; in 0.14.1), P124 (a frame status is the word of Porthole's pages, after
985
+ the audit raft-security-audit#16; in 0.14.5: §4, §6, §7, S6).
902
986
 
903
987
  | Decision | State | What it closes | Sections |
904
988
  | --- | --- | --- | --- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.3",
3
+ "version": "0.14.5",
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": {
@@ -589,6 +589,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
589
589
  speaks,
590
590
  timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
591
591
  onOutcome: (outcome) => emit("outcome", outcome),
592
+ // A frame status from the content (P124): never shown, the host's to hear.
593
+ refused: (message) => hostError(message, "frame-status"),
592
594
  });
593
595
  outcomeWatch = watch;
594
596
  if (!speaks) {
@@ -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);
@@ -15,6 +15,27 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
15
15
  * - an app from a host's own gateway is loaded on its first load, unless its page says it is
16
16
  * blocked (the gateway may send the same message);
17
17
  * - nothing settled in `timeoutMs`: a timeout.
18
+ *
19
+ * Who may say how loading went (P124). A frame status is taken only from a document of Porthole's
20
+ * server, a host's gateway or the host's own pages, never from content: its words draw the host's
21
+ * fallback, in Porthole's wording, with a link. Nothing in a message tells who sent it (a page
22
+ * that shares the frame's window and origin can send the same bytes), so the host goes by what
23
+ * content can't change: where the frame's documents come from, and in what order they speak.
24
+ *
25
+ * - An opaque frame's only document is the host's own shell, with the content in it: no page of
26
+ * Porthole's server ever loads there, so its every frame status is the content's.
27
+ * - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
28
+ * says Porthole's own word first in every document that holds content, before any of the
29
+ * content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
30
+ * reaches the host before anything its page says, through its shell). A status page says
31
+ * nothing but its frame status. So a frame status is taken only before anything else was heard
32
+ * from the frame in this run: from its first document, which then was a page of Porthole's.
33
+ * After that, it came from the content (or from a later document, which in a display without
34
+ * files starts the display again, whose first document then says how it went).
35
+ * - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
36
+ * status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
37
+ *
38
+ * A frame status not taken is dropped, and told once a run to the host (`refused`).
18
39
  */
19
40
 
20
41
  /** How long after a load the frame's word may still arrive. */
@@ -77,6 +98,16 @@ export function parseFrameStatus(data: unknown): FrameStatus | null {
77
98
  };
78
99
  }
79
100
 
101
+ /** Whether a message names the frame-status method, well formed or not. */
102
+ const namesFrameStatus = (data: unknown): boolean =>
103
+ data !== null &&
104
+ typeof data === "object" &&
105
+ (data as { method?: unknown }).method === FRAME_STATUS_METHOD;
106
+
107
+ /** What the host is told of a frame status it didn't take (P124). */
108
+ export const UNTRUSTED_FRAME_STATUS =
109
+ "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
110
+
80
111
  export interface OutcomeWatch {
81
112
  /** The frame finished its handshake. */
82
113
  initialized(): void;
@@ -90,12 +121,17 @@ export function watchOutcome(options: {
90
121
  readonly speaks: boolean;
91
122
  readonly timeoutMs: number;
92
123
  readonly onOutcome: (outcome: FrameOutcome) => void;
124
+ /** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
125
+ readonly refused?: (message: string) => void;
93
126
  }): OutcomeWatch {
94
127
  const { surface, source, speaks } = options;
95
128
  const reports = source.kind === "url" && source.reports === true;
96
129
  // The first outcome; after a load, only a later block (a status page, access revoked) is told.
97
130
  let decided: FrameOutcome["state"] | null = null;
98
131
  let heard = false;
132
+ // Whether the frame said anything but a frame status in this run (P124).
133
+ let spoke = false;
134
+ let told = false;
99
135
  let entering = false;
100
136
  let loads = 0;
101
137
  const timers = new Set<ReturnType<typeof setTimeout>>();
@@ -127,8 +163,21 @@ export function watchOutcome(options: {
127
163
  options.onOutcome(outcome);
128
164
  }
129
165
  };
166
+ // Whether a frame status may be the word of a page of Porthole's (P124, above).
167
+ const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
130
168
  const unlisten = surface.transport.listen((data) => {
131
169
  heard = true;
170
+ if (!namesFrameStatus(data)) {
171
+ spoke = true;
172
+ return;
173
+ }
174
+ if (!mayBePorthole()) {
175
+ if (!told) {
176
+ told = true;
177
+ options.refused?.(UNTRUSTED_FRAME_STATUS);
178
+ }
179
+ return;
180
+ }
132
181
  const status = parseFrameStatus(data);
133
182
  if (status?.state === "entering") {
134
183
  entering = true;
package/src/host/types.ts CHANGED
@@ -125,7 +125,13 @@ export type HostErrorKind =
125
125
  /** A display couldn't be made (the React binding: a bad config, a missing handler). */
126
126
  | "mount"
127
127
  /** An annotation call was refused (an invalid mark, an unknown id). */
128
- | "annotations";
128
+ | "annotations"
129
+ /**
130
+ * A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
131
+ * from the frame's content, not from a page of Porthole's server (P124): never shown, never an
132
+ * outcome. Told once a run.
133
+ */
134
+ | "frame-status";
129
135
 
130
136
  /** What a display reports, by event name. */
131
137
  /** Why a display's frame showed nothing of its content (`FrameOutcome`). */
@@ -150,9 +156,11 @@ export type FrameBlock =
150
156
  /**
151
157
  * How a display's document went: it loaded (a shell or view finished its handshake; a url-mode
152
158
  * app's document loaded), it was blocked (and why), or nothing settled in
153
- * `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if the frame shows a status page
154
- * after it loaded (access revoked mid-session). A host shows its own fallback ("Open in a new
155
- * tab") on anything but loaded.
159
+ * `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if a url-mode app's frame shows a
160
+ * status page after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
161
+ * a new tab") on anything but loaded. A `blocked` is the word of a page of Porthole's server (or a
162
+ * host's gateway, or its own pages), never of a frame's content, except a url-mode app's (P124):
163
+ * in a frame that speaks, only its run's first document says it; an opaque frame never does.
156
164
  */
157
165
  export type FrameOutcome =
158
166
  | { readonly state: "loaded" }
@@ -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