@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.
- package/CHANGELOG.md +77 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -0
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +4 -0
- package/dist/host/outcome.js +43 -0
- package/dist/host/types.d.ts +12 -4
- 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/react/frame.d.ts +2 -1
- 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 +37 -14
- package/docs/ARCHITECTURE.md +5 -1
- package/docs/DECISIONS.md +404 -2
- package/docs/DESIGN.md +11 -4
- package/docs/THREAT_MODEL.md +116 -32
- package/package.json +1 -1
- package/src/host/create-host.ts +2 -0
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +49 -0
- package/src/host/types.ts +12 -4
- 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/react/frame.tsx +2 -1
- 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/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.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
|
|
162
|
-
comment's bubble, a composer
|
|
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
|
|
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).
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
|
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
|
+
"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": {
|
package/src/host/create-host.ts
CHANGED
|
@@ -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) {
|
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);
|
package/src/host/outcome.ts
CHANGED
|
@@ -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
|
|
154
|
-
* after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
|
|
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" }
|
package/src/isolation/served.ts
CHANGED
|
@@ -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(
|
package/src/isolation/types.ts
CHANGED
|
@@ -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
|
|