@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.
@@ -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) {
@@ -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 {};
@@ -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;
@@ -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 the frame shows a status page
142
- * after it loaded (access revoked mid-session). A host shows its own fallback ("Open in a new
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";
@@ -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`). Never the agent's.
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 even after `loaded` | `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) |
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]` | — | — |
@@ -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.4 (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
@@ -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.4",
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) {
@@ -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" }
@@ -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`). Never the agent's.
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;