@botiverse/porthole 0.14.4 → 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 +18 -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/outcome.d.ts +4 -0
- package/dist/host/outcome.js +43 -0
- package/dist/host/types.d.ts +12 -4
- package/dist/react/frame.d.ts +2 -1
- package/docs/ADOPTING.md +5 -0
- package/docs/DECISIONS.md +92 -0
- package/docs/DESIGN.md +3 -1
- package/docs/THREAT_MODEL.md +32 -3
- package/package.json +1 -1
- package/src/host/create-host.ts +2 -0
- package/src/host/outcome.ts +49 -0
- package/src/host/types.ts +12 -4
- package/src/react/frame.tsx +2 -1
package/dist/host/create-host.js
CHANGED
|
@@ -514,6 +514,8 @@ export function createHost(config, options = {}) {
|
|
|
514
514
|
speaks,
|
|
515
515
|
timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
|
|
516
516
|
onOutcome: (outcome) => emit("outcome", outcome),
|
|
517
|
+
// A frame status from the content (P124): never shown, the host's to hear.
|
|
518
|
+
refused: (message) => hostError(message, "frame-status"),
|
|
517
519
|
});
|
|
518
520
|
outcomeWatch = watch;
|
|
519
521
|
if (!speaks) {
|
package/dist/host/outcome.d.ts
CHANGED
|
@@ -9,6 +9,8 @@ interface FrameStatus {
|
|
|
9
9
|
}
|
|
10
10
|
/** A frame-status message, or null for anything else. */
|
|
11
11
|
export declare function parseFrameStatus(data: unknown): FrameStatus | null;
|
|
12
|
+
/** What the host is told of a frame status it didn't take (P124). */
|
|
13
|
+
export declare const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
|
|
12
14
|
export interface OutcomeWatch {
|
|
13
15
|
/** The frame finished its handshake. */
|
|
14
16
|
initialized(): void;
|
|
@@ -21,5 +23,7 @@ export declare function watchOutcome(options: {
|
|
|
21
23
|
readonly speaks: boolean;
|
|
22
24
|
readonly timeoutMs: number;
|
|
23
25
|
readonly onOutcome: (outcome: FrameOutcome) => void;
|
|
26
|
+
/** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
|
|
27
|
+
readonly refused?: (message: string) => void;
|
|
24
28
|
}): OutcomeWatch;
|
|
25
29
|
export {};
|
package/dist/host/outcome.js
CHANGED
|
@@ -12,6 +12,27 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
12
12
|
* - an app from a host's own gateway is loaded on its first load, unless its page says it is
|
|
13
13
|
* blocked (the gateway may send the same message);
|
|
14
14
|
* - nothing settled in `timeoutMs`: a timeout.
|
|
15
|
+
*
|
|
16
|
+
* Who may say how loading went (P124). A frame status is taken only from a document of Porthole's
|
|
17
|
+
* server, a host's gateway or the host's own pages, never from content: its words draw the host's
|
|
18
|
+
* fallback, in Porthole's wording, with a link. Nothing in a message tells who sent it (a page
|
|
19
|
+
* that shares the frame's window and origin can send the same bytes), so the host goes by what
|
|
20
|
+
* content can't change: where the frame's documents come from, and in what order they speak.
|
|
21
|
+
*
|
|
22
|
+
* - An opaque frame's only document is the host's own shell, with the content in it: no page of
|
|
23
|
+
* Porthole's server ever loads there, so its every frame status is the content's.
|
|
24
|
+
* - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
|
|
25
|
+
* says Porthole's own word first in every document that holds content, before any of the
|
|
26
|
+
* content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
|
|
27
|
+
* reaches the host before anything its page says, through its shell). A status page says
|
|
28
|
+
* nothing but its frame status. So a frame status is taken only before anything else was heard
|
|
29
|
+
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
30
|
+
* After that, it came from the content (or from a later document, which in a display without
|
|
31
|
+
* files starts the display again, whose first document then says how it went).
|
|
32
|
+
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
33
|
+
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
34
|
+
*
|
|
35
|
+
* A frame status not taken is dropped, and told once a run to the host (`refused`).
|
|
15
36
|
*/
|
|
16
37
|
/** How long after a load the frame's word may still arrive. */
|
|
17
38
|
const SETTLE_MS = 400;
|
|
@@ -58,12 +79,21 @@ export function parseFrameStatus(data) {
|
|
|
58
79
|
: {}),
|
|
59
80
|
};
|
|
60
81
|
}
|
|
82
|
+
/** Whether a message names the frame-status method, well formed or not. */
|
|
83
|
+
const namesFrameStatus = (data) => data !== null &&
|
|
84
|
+
typeof data === "object" &&
|
|
85
|
+
data.method === FRAME_STATUS_METHOD;
|
|
86
|
+
/** What the host is told of a frame status it didn't take (P124). */
|
|
87
|
+
export const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
|
|
61
88
|
export function watchOutcome(options) {
|
|
62
89
|
const { surface, source, speaks } = options;
|
|
63
90
|
const reports = source.kind === "url" && source.reports === true;
|
|
64
91
|
// The first outcome; after a load, only a later block (a status page, access revoked) is told.
|
|
65
92
|
let decided = null;
|
|
66
93
|
let heard = false;
|
|
94
|
+
// Whether the frame said anything but a frame status in this run (P124).
|
|
95
|
+
let spoke = false;
|
|
96
|
+
let told = false;
|
|
67
97
|
let entering = false;
|
|
68
98
|
let loads = 0;
|
|
69
99
|
const timers = new Set();
|
|
@@ -96,8 +126,21 @@ export function watchOutcome(options) {
|
|
|
96
126
|
options.onOutcome(outcome);
|
|
97
127
|
}
|
|
98
128
|
};
|
|
129
|
+
// Whether a frame status may be the word of a page of Porthole's (P124, above).
|
|
130
|
+
const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
|
|
99
131
|
const unlisten = surface.transport.listen((data) => {
|
|
100
132
|
heard = true;
|
|
133
|
+
if (!namesFrameStatus(data)) {
|
|
134
|
+
spoke = true;
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
if (!mayBePorthole()) {
|
|
138
|
+
if (!told) {
|
|
139
|
+
told = true;
|
|
140
|
+
options.refused?.(UNTRUSTED_FRAME_STATUS);
|
|
141
|
+
}
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
101
144
|
const status = parseFrameStatus(data);
|
|
102
145
|
if (status?.state === "entering") {
|
|
103
146
|
entering = true;
|
package/dist/host/types.d.ts
CHANGED
|
@@ -117,7 +117,13 @@ export type HostErrorKind =
|
|
|
117
117
|
/** A display couldn't be made (the React binding: a bad config, a missing handler). */
|
|
118
118
|
| "mount"
|
|
119
119
|
/** An annotation call was refused (an invalid mark, an unknown id). */
|
|
120
|
-
| "annotations"
|
|
120
|
+
| "annotations"
|
|
121
|
+
/**
|
|
122
|
+
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
123
|
+
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
124
|
+
* outcome. Told once a run.
|
|
125
|
+
*/
|
|
126
|
+
| "frame-status";
|
|
121
127
|
/** What a display reports, by event name. */
|
|
122
128
|
/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
|
|
123
129
|
export type FrameBlock =
|
|
@@ -138,9 +144,11 @@ export type FrameBlock =
|
|
|
138
144
|
/**
|
|
139
145
|
* How a display's document went: it loaded (a shell or view finished its handshake; a url-mode
|
|
140
146
|
* app's document loaded), it was blocked (and why), or nothing settled in
|
|
141
|
-
* `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if
|
|
142
|
-
* after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
|
|
143
|
-
* tab") on anything but loaded.
|
|
147
|
+
* `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if a url-mode app's frame shows a
|
|
148
|
+
* status page after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
|
|
149
|
+
* a new tab") on anything but loaded. A `blocked` is the word of a page of Porthole's server (or a
|
|
150
|
+
* host's gateway, or its own pages), never of a frame's content, except a url-mode app's (P124):
|
|
151
|
+
* in a frame that speaks, only its run's first document says it; an opaque frame never does.
|
|
144
152
|
*/
|
|
145
153
|
export type FrameOutcome = {
|
|
146
154
|
readonly state: "loaded";
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -223,7 +223,8 @@ export interface PortholeFrameProps {
|
|
|
223
223
|
readonly onContentError?: (message: string) => void;
|
|
224
224
|
/**
|
|
225
225
|
* What failed on the host's side: its locator (`locate`), a display that couldn't be made
|
|
226
|
-
* (`mount`), an annotation call refused (`annotations`)
|
|
226
|
+
* (`mount`), an annotation call refused (`annotations`), a frame status the content forged and
|
|
227
|
+
* the host didn't take (`frame-status`, P124). Never the agent's.
|
|
227
228
|
*/
|
|
228
229
|
readonly onHostError?: (error: {
|
|
229
230
|
readonly message: string;
|
package/docs/ADOPTING.md
CHANGED
|
@@ -816,6 +816,11 @@ display.on("outcome", (outcome) => {
|
|
|
816
816
|
openButton.onclick = () => porthole.openInTab(instance); // the clean address
|
|
817
817
|
```
|
|
818
818
|
|
|
819
|
+
A `blocked` outcome is the word of Porthole's own pages, never of the content (P124): an opaque
|
|
820
|
+
frame's frame status is never taken, nor one a frame says after its first word; the host hears
|
|
821
|
+
those as a `hostError` of kind `"frame-status"` (log it, show nothing for it). Draw the fallback
|
|
822
|
+
from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL S6).
|
|
823
|
+
|
|
819
824
|
`porthole.config(kind)` is the served config while frames are served, the opaque one while they
|
|
820
825
|
aren't, and null until the meta is known, so a frame never starts opaque and then restarts
|
|
821
826
|
served. The client's functions take no `this`: pass them bare
|
package/docs/DECISIONS.md
CHANGED
|
@@ -6682,3 +6682,95 @@ looser reading of the typing before an activation.
|
|
|
6682
6682
|
**Revisit when** a browser gives a frame's parent a way to keep focus or to know what turned
|
|
6683
6683
|
activation on, or a host reports a real loss the person didn't notice.
|
|
6684
6684
|
|
|
6685
|
+
|
|
6686
|
+
## P124 · 2026-10-29 · A frame status is the word of Porthole's pages: never an opaque frame's, and in a frame that speaks, only its run's first document's · Accepted
|
|
6687
|
+
|
|
6688
|
+
Amends P040 and P050. **Context.** The audit raft-security-audit#16 (Cato, medium) found that any
|
|
6689
|
+
frame could send `porthole/notifications/frame-status`: an opaque widget, a served page, an MCP
|
|
6690
|
+
Apps view, or a nested page through its shell. The host took it as P040's word of Porthole's
|
|
6691
|
+
server: the display's `outcome` became `blocked` with the content's reason and code
|
|
6692
|
+
(`host/outcome.ts`), and a host drew its own fallback in Porthole's wording (`frameFallback`, the
|
|
6693
|
+
default of `PortholeView`: "Open this in a new tab to sign in", "You can't open this anymore") with a
|
|
6694
|
+
link out of the page. Content could speak as the host and as Porthole, push the person to a sign-in
|
|
6695
|
+
somewhere else, and hand the host's `onOutcome` any code it liked.
|
|
6696
|
+
|
|
6697
|
+
**Why the message can't say who sent it.** The pages that say it (`statusPage`, `enterPage`,
|
|
6698
|
+
`appStatusPage`, `statusPageOf`, a host's gateway's) are documents of the frame's own window and,
|
|
6699
|
+
but for a redirect entry's (P068, the host's own origin), of the content's own origin: the
|
|
6700
|
+
transport's checks (the frame's window, its origin) let content's message through as they let
|
|
6701
|
+
theirs. A secret for them to echo would have to reach a status page and no content of the same
|
|
6702
|
+
origin and window (a fragment, a cookie, the window's name: content reads each), and a channel the
|
|
6703
|
+
shell hands the host (a `MessagePort`) is no wall where the shell shares the content's realm
|
|
6704
|
+
(ARCHITECTURE, boundary 4), nor is the shell who says it. What content can't change is where a
|
|
6705
|
+
frame's documents come from and which word each says first.
|
|
6706
|
+
|
|
6707
|
+
**Decision.** The host takes a frame status only where content can't have said it (`watchOutcome`):
|
|
6708
|
+
1. **An opaque frame: never.** Its only document is the host's shell, the content inside it: no page
|
|
6709
|
+
of Porthole's server loads in a `srcdoc` frame.
|
|
6710
|
+
2. **A frame that speaks** (a served shell, an MCP Apps view through the sandbox proxy, a nested
|
|
6711
|
+
page's shell): **only before anything else was heard from it in the run.** Every document
|
|
6712
|
+
Porthole serves with content in it says Porthole's word first, before any of the content's code
|
|
6713
|
+
runs: the shell's `ui/initialize` (a served shell carries its page as data and runs it once its
|
|
6714
|
+
own document has loaded), the sandbox proxy's `sandbox-proxy-ready` (before its host sends the
|
|
6715
|
+
view), and through a nested page's shell the page's own runtime's hello (the shell's
|
|
6716
|
+
`porthole/shell/` words go to the focus guard, never to the display). A status page says
|
|
6717
|
+
nothing but its status. Messages from one document to one window arrive in order, so a frame
|
|
6718
|
+
status before any other word is the run's first document's, a page of Porthole's (or a
|
|
6719
|
+
gateway's, or the host's own, P068): taken, as before. One after any other word is dropped.
|
|
6720
|
+
3. **A url-mode app: as before.** It has no shell to speak first, shares its origin with the entry
|
|
6721
|
+
page and the status pages, and its scripts run before the host sees its load: its frame status
|
|
6722
|
+
is its own word (THREAT_MODEL S6: preview only code you trust).
|
|
6723
|
+
|
|
6724
|
+
A frame status the host doesn't take is dropped: no outcome, nothing for a fallback, no code to
|
|
6725
|
+
`onOutcome`. The host hears a `hostError` of a new kind, `frame-status`, once a run (a flood is one
|
|
6726
|
+
event), never a content error: it is a display trying to speak as Porthole, the host's to log or act
|
|
6727
|
+
on, and nothing the agent can fix.
|
|
6728
|
+
|
|
6729
|
+
**What it changes.** A frame that speaks no longer tells a later block itself (P050's "even after
|
|
6730
|
+
`loaded`" now holds for url mode only):
|
|
6731
|
+
- A display without files starts again on any later load (P031), and its new run's first document
|
|
6732
|
+
tells the outcome; P050's framed page case already counted on that ("each mounting tells its own
|
|
6733
|
+
outcome"). The old run may hear the status page's word before its load: dropped, and one
|
|
6734
|
+
`frame-status` host error, a false alarm in that race.
|
|
6735
|
+
- A display with files (P084) whose next page of the set is answered by a status page (access
|
|
6736
|
+
revoked mid-session) shows that page in its frame, the server's own words there, and the host
|
|
6737
|
+
isn't told `blocked`: it hears the host error, and the next mount tells.
|
|
6738
|
+
|
|
6739
|
+
**Threat it re-opens.** None: it narrows what a frame can make the host show. What stays open:
|
|
6740
|
+
- url mode (above), where the app can still make the host show any fallback, with any code.
|
|
6741
|
+
- A frame that speaks whose shell never runs: the content can't run either (it is the shell's to
|
|
6742
|
+
run), so nothing speaks and the outcome is `framing` or a timeout, as before.
|
|
6743
|
+
|
|
6744
|
+
**The invariant this rests on.** Every document a frame that speaks can hold is one Porthole
|
|
6745
|
+
wrote first: a served page, a set's HTML page and a nested page reach the frame only carried inside
|
|
6746
|
+
`shellDocument` (as `scriptJson`, rendered after the shell's synchronous `initialize()`), and an MCP
|
|
6747
|
+
view only after the proxy's `sandbox-proxy-ready`. A frame status arriving after the shell's hello in
|
|
6748
|
+
a run is therefore never a status page's. Whoever changes how `shellDocument` carries a page, or adds
|
|
6749
|
+
a path that serves stored HTML as a frame's document by itself, breaks this rule and must revisit it
|
|
6750
|
+
(raft-security-audit#16 review of this decision, Cato).
|
|
6751
|
+
|
|
6752
|
+
**Tested.** `test/outcome.test.ts` ("who may say how loading went (P124)"): an opaque frame's word
|
|
6753
|
+
dropped before and after its handshake, told once; a served frame's first document that is a status
|
|
6754
|
+
page still decides `blocked`, with its code; a served shell's content after its hello, before and
|
|
6755
|
+
after the handshake, dropped; a nested page's word after its relayed hello, dropped; any other word,
|
|
6756
|
+
malformed too, counts as the frame speaking; a url-mode app's word still taken; and through
|
|
6757
|
+
`createHost`, an inline widget's `sign-in` is no outcome and one `frame-status` host error, no
|
|
6758
|
+
content error. Before the change the first five failed. `leak/served/outcome.spec.ts`, four cases
|
|
6759
|
+
(a served shell's content; a served artifact page as it loads; an opaque widget; a nested page,
|
|
6760
|
+
through its shell and past it to the host's window), each saying `blocked` (`sign-in`, `denied`,
|
|
6761
|
+
a code) and `entering`, at once and again: the outcome stays `loaded`, and the host hears one
|
|
6762
|
+
`frame-status` error. Negative control `frame-status` (the rule out: every frame status taken)
|
|
6763
|
+
fails exactly those four. The outcome, authorize and files suites and the rest of the leak suite
|
|
6764
|
+
pass. Measured here on Chromium only (WebKit's and Firefox's libraries are missing on this box):
|
|
6765
|
+
CI runs all three engines.
|
|
6766
|
+
|
|
6767
|
+
**Rejected.** A per-run secret for status pages to echo, or a `MessagePort` from the shell (above).
|
|
6768
|
+
Having a nested page's shell also drop its page's frame status, as it drops its namespace: the
|
|
6769
|
+
host's rule drops it already (the page's hello comes first), and a second wall no probe can see is
|
|
6770
|
+
one PRINCIPLE 5 can't prove. Starting a display again on a dropped status, so the new run hears the
|
|
6771
|
+
server: content could make a display start again at will (bounded by P031's count, as navigating
|
|
6772
|
+
away is), for a block the frame already shows.
|
|
6773
|
+
|
|
6774
|
+
**Revisit when** a host needs a later block told in a display with files (then: start it again on a
|
|
6775
|
+
dropped status, its next run's first document says it), or url mode gets a shell of Porthole's on
|
|
6776
|
+
the app's origin.
|
package/docs/DESIGN.md
CHANGED
|
@@ -978,7 +978,8 @@ for that to lapse and click with raw input.
|
|
|
978
978
|
|
|
979
979
|
| What | Mechanism | Tests (all three engines unless noted) | Negative control → fails |
|
|
980
980
|
|------|-----------|-------|------------------|
|
|
981
|
-
| The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so
|
|
981
|
+
| The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so (after `loaded` too in url mode; a frame that speaks is told by its next run's first document, P124) | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load; an app and a page in a tab | `authorize` → every case but WebKit's framed page (`session` either way) |
|
|
982
|
+
| Who may say how loading went (P124) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it: never from an opaque frame (no page of Porthole's server loads there); in a frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell), only before anything else is heard from it in the run, since Porthole's word (the shell's hello, the proxy's ready) opens every document that holds content, before content runs, and a status page says nothing but its status; a url-mode app's, as before (S6). One not taken is dropped, and the host hears a `hostError` of kind `frame-status`, once a run | `test/outcome.test.ts` ("who may say how loading went (P124)", and through `createHost`); `leak/served/outcome.spec.ts`: a served shell's content, a served page as it loads, an opaque widget and a nested page (through its shell and past it) each say `blocked` (`sign-in`, `denied`, a code) at once and again: the outcome stays `loaded`, the host hears one `frame-status` error | `frame-status` → those four cases (all three) |
|
|
982
983
|
| Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
|
|
983
984
|
| Siblings on the content domain (P101) | over https only `__Host-porthole-` names are read (a sibling sets any other name for the whole domain, never a `__Host-` one), names trimmed of spaces and tabs only; the entered mark is its label's and path's, read from a nonce cookie only; a url-mode app's request rides its cookie only from its own origin (`Origin`; `Sec-Fetch-Site` `same-origin` or `none`) or as a GET/HEAD navigation, else a 403 before the upstream and the host's check; a socket (`access`, `nodeHost`'s `appSocket`, a Worker's upgrade path) from its own origin only | `test/siblings.test.ts` (planted names, the mark on another label, every kind of request and socket, `nodeHost` over a real socket); `test/workers.test.ts` (workerd: a sibling's POST and socket refused, the app's own open); `served.url.siblings`: another app's frame (Chromium, Firefox: WebKit keeps no framed cookie, P025) or tab loading the app's script is refused, its own loads; `leak/kit.spec.ts`: the app's own WebSocket opens through `nodeHost`, a same-site sibling's doesn't; prod shape: a session copied under an unprefixed name and planted with `Domain=` opens nothing, and the socket case over wss | `url-origin` → `served.url.siblings` on the reference serving (Chromium, Firefox; its labels are cross-site on `*.localhost`, so only the framed half rides a cookie) |
|
|
984
985
|
| Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
|
|
@@ -1488,6 +1489,7 @@ control the tables above name to the registry):
|
|
|
1488
1489
|
| `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
|
|
1489
1490
|
| `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
|
|
1490
1491
|
| `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
|
|
1492
|
+
| `frame-status` | `served/outcome.spec.ts` | `a served shell's content that says it is blocked is told nothing and shown nothing (P124)`, `a served artifact page that says it is blocked as it loads is told nothing and shown nothing (P124)`, `an opaque widget that says it is blocked is told nothing and shown nothing (P124)`, `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
|
|
1491
1493
|
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1492
1494
|
| `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
|
|
1493
1495
|
| `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
|
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
|
|
@@ -164,6 +167,11 @@ Whatever the use:
|
|
|
164
167
|
host's own UI. A copy notice of its own shows what went on the clipboard (S1).
|
|
165
168
|
- Show the text content reports (its errors, a blocked navigation's address, an annotation's
|
|
166
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).
|
|
167
175
|
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
168
176
|
as permissions, and put nothing in a mark the page may not know (§7).
|
|
169
177
|
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
|
|
@@ -575,6 +583,11 @@ the attacker (c), and its readers are strangers.
|
|
|
575
583
|
**Not guaranteed**
|
|
576
584
|
|
|
577
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.
|
|
578
591
|
- A page on another origin can still open the app by a navigation (a link, a frame of its own),
|
|
579
592
|
which reaches the app's GET routes as any link does.
|
|
580
593
|
- A request with neither `Origin` nor `Sec-Fetch-Site` goes on: in browsers without fetch
|
|
@@ -623,6 +636,21 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
|
|
|
623
636
|
**The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
|
|
624
637
|
effects are its own), and group displays by page (S7).
|
|
625
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
|
+
|
|
626
654
|
**Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
|
|
627
655
|
its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
|
|
628
656
|
own frame, below the shell, P111), so:
|
|
@@ -953,7 +981,8 @@ The decisions below come from the 2026-10-19 review, and all of them have merged
|
|
|
953
981
|
what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
|
|
954
982
|
are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
|
|
955
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
|
|
956
|
-
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).
|
|
957
986
|
|
|
958
987
|
| Decision | State | What it closes | Sections |
|
|
959
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/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/react/frame.tsx
CHANGED
|
@@ -563,7 +563,8 @@ export interface PortholeFrameProps {
|
|
|
563
563
|
readonly onContentError?: (message: string) => void;
|
|
564
564
|
/**
|
|
565
565
|
* What failed on the host's side: its locator (`locate`), a display that couldn't be made
|
|
566
|
-
* (`mount`), an annotation call refused (`annotations`)
|
|
566
|
+
* (`mount`), an annotation call refused (`annotations`), a frame status the content forged and
|
|
567
|
+
* the host didn't take (`frame-status`, P124). Never the agent's.
|
|
567
568
|
*/
|
|
568
569
|
readonly onHostError?: (error: {
|
|
569
570
|
readonly message: string;
|