@botiverse/porthole 0.14.17 → 0.15.0
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 +55 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/pages-of-set.d.ts +3 -1
- package/dist/host/pages-of-set.js +17 -3
- package/dist/isolation/served.d.ts +9 -0
- package/dist/isolation/served.js +23 -0
- package/dist/protocol/mcp-apps.d.ts +5 -3
- package/dist/protocol/mcp-apps.js +5 -3
- package/dist/protocol/shell-adapter.js +5 -0
- package/dist/server/host.d.ts +7 -0
- package/dist/server/host.js +1 -0
- package/dist/server/pages.d.ts +39 -12
- package/dist/server/pages.js +85 -37
- package/dist/server/server.js +168 -40
- package/dist/server/types.d.ts +30 -0
- package/dist/shell/annotate.js +3 -2
- package/dist/shell/find.js +2 -1
- package/dist/shell/frame.d.ts +3 -34
- package/dist/shell/frame.js +26 -14
- package/dist/shell/runtime.d.ts +3 -2
- package/dist/shell/runtime.js +25 -9
- package/docs/ADOPTING.md +18 -4
- package/docs/DECISIONS.md +288 -5
- package/docs/DESIGN.md +6 -1
- package/docs/THREAT_MODEL.md +38 -2
- package/package.json +1 -1
- package/src/host/pages-of-set.ts +18 -3
- package/src/isolation/served.ts +25 -0
- package/src/protocol/mcp-apps.ts +5 -3
- package/src/protocol/shell-adapter.ts +5 -0
- package/src/server/host.ts +8 -0
- package/src/server/pages.ts +129 -56
- package/src/server/server.ts +237 -40
- package/src/server/types.ts +30 -0
- package/src/shell/annotate.ts +3 -2
- package/src/shell/find.ts +2 -1
- package/src/shell/frame.ts +33 -14
- package/src/shell/runtime.ts +25 -9
package/dist/shell/frame.d.ts
CHANGED
|
@@ -1,38 +1,7 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Porthole's shell for a nested page (P111): the whole document at the address the host frames,
|
|
3
|
-
* with no content in it. It frames the page (the same origin's sealed files' address) in a child
|
|
4
|
-
* sandboxed without `allow-same-origin`, so the page's origin is opaque and nothing of the shell's
|
|
5
|
-
* realm is reachable from it: not its DOM, its globals, its storage, or the window the host hears.
|
|
6
|
-
*
|
|
7
|
-
* The shell:
|
|
8
|
-
* - passes every message between the host (its parent, from the host origins) and the page (its
|
|
9
|
-
* child's window, by `event.source` alone: the page's origin is "null") unchanged, and drops any
|
|
10
|
-
* the page sends in the shell's own namespace (`porthole/shell/`), so the shell's words to the
|
|
11
|
-
* host are only its own;
|
|
12
|
-
* - tells the host its own state (`porthole/shell/state`): whether its transient activation is on,
|
|
13
|
-
* and since when, and whether the page's focus is in it. A gesture in the page activates the
|
|
14
|
-
* page and its ancestors, the shell among them, and nothing on the host's page activates the
|
|
15
|
-
* shell (activation goes up, never down), so the shell's activation turning on is a press or
|
|
16
|
-
* key of the person's in this page. It is read at every animation frame, on its window's focus
|
|
17
|
-
* and blur, and before each message of the page's is passed on (a call made in a click's handler
|
|
18
|
-
* arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
|
|
19
|
-
* P120: the host heard focus move into the frame, and a key the person types into the page
|
|
20
|
-
* before the shell's next frame would turn its activation on as a press does). What it can't
|
|
21
|
-
* see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
|
|
22
|
-
* on;
|
|
23
|
-
* - renews the page's sealed files' address before it ends, and gives the page the new one
|
|
24
|
-
* (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
|
|
25
|
-
* are), so only the shell, on that origin, may renew it (P083);
|
|
26
|
-
* - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
|
|
27
|
-
* `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
|
|
28
|
-
* it doesn't: a frame's move inside the focus event that made it the focused frame sets the
|
|
29
|
-
* shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
|
|
30
|
-
* the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
|
|
31
|
-
* goes through on all of them, the frame blurred first as the failed one left it active.
|
|
32
|
-
*
|
|
33
|
-
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
|
|
34
|
-
*/
|
|
1
|
+
/** The nested page's shell's runtime: 0.14.16's, byte for byte. */
|
|
35
2
|
export declare const FRAME_SHELL_RUNTIME: string;
|
|
3
|
+
/** A strict shell's runtime (P141): its parent may be an outer page. */
|
|
4
|
+
export declare const STRICT_FRAME_SHELL_RUNTIME: string;
|
|
36
5
|
export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
|
|
37
6
|
export interface FrameShellOptions {
|
|
38
7
|
/** The host origins: the shell takes messages from its parent only from these. */
|
package/dist/shell/frame.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { PAGE_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
2
|
-
import { framedByProblem, hostOriginProblem, onNestedLabel } from "../isolation/served.js";
|
|
2
|
+
import { framedByProblem, hostOriginProblem, includesOrigin, onNestedLabel, } from "../isolation/served.js";
|
|
3
3
|
/**
|
|
4
4
|
* Porthole's shell for a nested page (P111): the whole document at the address the host frames,
|
|
5
5
|
* with no content in it. It frames the page (the same origin's sealed files' address) in a child
|
|
@@ -32,9 +32,12 @@ import { framedByProblem, hostOriginProblem, onNestedLabel } from "../isolation/
|
|
|
32
32
|
* the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
|
|
33
33
|
* goes through on all of them, the frame blurred first as the failed one left it active.
|
|
34
34
|
*
|
|
35
|
-
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
|
|
35
|
+
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan. A shell
|
|
36
|
+
* whose parent may be an outer page (a host's `framedBy`, P141) runs the strict runtime, which
|
|
37
|
+
* checks that parent before it says `*`; every other shell runs 0.14.16's, byte for byte, so its
|
|
38
|
+
* hash is too (P144).
|
|
36
39
|
*/
|
|
37
|
-
|
|
40
|
+
const frameShellRuntime = (strict) => String.raw `(() => {
|
|
38
41
|
"use strict";
|
|
39
42
|
const plan = __PLAN__;
|
|
40
43
|
const PREFIX = "porthole/shell/";
|
|
@@ -80,9 +83,7 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
80
83
|
const web = plan.origins.filter((origin) => origin.indexOf("https://") === 0 || origin.indexOf("http://") === 0);
|
|
81
84
|
// To the host: each web host origin (only the parent's is delivered); a desktop app's own scheme
|
|
82
85
|
// is no target a browser takes, so where one is listed and the parent isn't a known web origin,
|
|
83
|
-
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret)
|
|
84
|
-
// it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
|
|
85
|
-
// may be the outer page: "*" then goes only to a parent the engine names as a host origin.
|
|
86
|
+
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret).${strict ? STRICT_NOTE : ""}
|
|
86
87
|
const toHost = (message) => {
|
|
87
88
|
if (!framed) {
|
|
88
89
|
return;
|
|
@@ -93,11 +94,7 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
93
94
|
} catch (_) {}
|
|
94
95
|
}
|
|
95
96
|
const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
|
|
96
|
-
if (
|
|
97
|
-
web.length < plan.origins.length &&
|
|
98
|
-
(parent === null || web.indexOf(parent) === -1) &&
|
|
99
|
-
(plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
|
|
100
|
-
) {
|
|
97
|
+
if (${strict ? STRICT_CONDITION : "web.length < plan.origins.length && (parent === null || web.indexOf(parent) === -1)"}) {
|
|
101
98
|
try {
|
|
102
99
|
window.parent.postMessage(message, "*");
|
|
103
100
|
} catch (_) {}
|
|
@@ -263,6 +260,20 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
263
260
|
setTimeout(renew, renewIn(plan.renew.expires));
|
|
264
261
|
}
|
|
265
262
|
})();`;
|
|
263
|
+
/** What a strict shell says of its `*` (P141), after the default's note. */
|
|
264
|
+
const STRICT_NOTE = ` Where
|
|
265
|
+
// it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
|
|
266
|
+
// may be the outer page: "*" then goes only to a parent the engine names as a host origin.`;
|
|
267
|
+
/** When a strict shell says `*` (P141): as 0.14.16's, and only to a parent named as a host origin. */
|
|
268
|
+
const STRICT_CONDITION = `
|
|
269
|
+
web.length < plan.origins.length &&
|
|
270
|
+
(parent === null || web.indexOf(parent) === -1) &&
|
|
271
|
+
(plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
|
|
272
|
+
`;
|
|
273
|
+
/** The nested page's shell's runtime: 0.14.16's, byte for byte. */
|
|
274
|
+
export const FRAME_SHELL_RUNTIME = frameShellRuntime(false);
|
|
275
|
+
/** A strict shell's runtime (P141): its parent may be an outer page. */
|
|
276
|
+
export const STRICT_FRAME_SHELL_RUNTIME = frameShellRuntime(true);
|
|
266
277
|
export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.js";
|
|
267
278
|
/** JSON that is safe inside a `<script>`. */
|
|
268
279
|
const scriptJson = (value) => JSON.stringify(value)
|
|
@@ -279,7 +290,7 @@ export function frameShellScript(options) {
|
|
|
279
290
|
}
|
|
280
291
|
for (const origin of options.framedBy ?? []) {
|
|
281
292
|
const problem = framedByProblem(origin);
|
|
282
|
-
if (problem !== null || options.origins
|
|
293
|
+
if (problem !== null || includesOrigin(options.origins, origin)) {
|
|
283
294
|
throw new TypeError(`frameShellScript: framedBy: ${problem ?? `${origin} is a host origin`}`);
|
|
284
295
|
}
|
|
285
296
|
}
|
|
@@ -297,9 +308,10 @@ export function frameShellScript(options) {
|
|
|
297
308
|
if (!onNestedLabel(page.origin)) {
|
|
298
309
|
throw new TypeError("frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)");
|
|
299
310
|
}
|
|
300
|
-
|
|
311
|
+
const strict = (options.framedBy ?? []).length > 0;
|
|
312
|
+
return (strict ? STRICT_FRAME_SHELL_RUNTIME : FRAME_SHELL_RUNTIME).replace("__PLAN__", () => scriptJson({
|
|
301
313
|
origins: options.origins,
|
|
302
|
-
...(
|
|
314
|
+
...(strict ? { strictParent: true } : {}),
|
|
303
315
|
page: page.href,
|
|
304
316
|
sandbox: PAGE_SANDBOX_TOKENS.join(" "),
|
|
305
317
|
...(options.title === undefined ? {} : { title: options.title }),
|
package/dist/shell/runtime.d.ts
CHANGED
|
@@ -30,9 +30,10 @@ export declare const PASSES_AS_IS: string;
|
|
|
30
30
|
*/
|
|
31
31
|
export declare const ONCE: string;
|
|
32
32
|
/**
|
|
33
|
-
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
33
|
+
* The shell's handshake with its host (P085, P139, P143), spliced into the runtime as
|
|
34
34
|
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
35
|
-
* its own top, so its parent is itself and no host can hear it)
|
|
35
|
+
* its own top, so its parent is itself and no host can hear it), and under a plan that names no
|
|
36
|
+
* host (P143: the runtime passes `topLevel` true for it too), there is no host to ask: `none()`
|
|
36
37
|
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
37
38
|
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
38
39
|
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
package/dist/shell/runtime.js
CHANGED
|
@@ -89,9 +89,10 @@ export const ONCE = String.raw `(passesAsIs, toText) => (value) => {
|
|
|
89
89
|
return text;
|
|
90
90
|
}`;
|
|
91
91
|
/**
|
|
92
|
-
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
92
|
+
* The shell's handshake with its host (P085, P139, P143), spliced into the runtime as
|
|
93
93
|
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
94
|
-
* its own top, so its parent is itself and no host can hear it)
|
|
94
|
+
* its own top, so its parent is itself and no host can hear it), and under a plan that names no
|
|
95
|
+
* host (P143: the runtime passes `topLevel` true for it too), there is no host to ask: `none()`
|
|
95
96
|
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
96
97
|
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
97
98
|
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
@@ -166,6 +167,10 @@ export const HANDSHAKE = String.raw `(topLevel, ask, answered, none, later) => {
|
|
|
166
167
|
export const SHELL_RUNTIME = String.raw `(() => {
|
|
167
168
|
"use strict";
|
|
168
169
|
const plan = __PLAN__;
|
|
170
|
+
// A plan that names no host (P143: an embedded document, framed below a page that is no host):
|
|
171
|
+
// the shell asks no host and ends its handshake at once, as on a tab (P139), and says nothing to
|
|
172
|
+
// any parent, not even its own notices to "*" (P053). No origin is a host's, so it hears no one.
|
|
173
|
+
const hostless = Array.isArray(plan.origins) && plan.origins.length === 0;
|
|
169
174
|
// Every built-in a guard calls is called through callOf, which is Reflect.apply itself, kept
|
|
170
175
|
// now, before any content runs: a direct call of it never reads Function.prototype's call,
|
|
171
176
|
// apply or bind, so nothing content later puts there sees what the shell calls or with what.
|
|
@@ -318,10 +323,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
318
323
|
// A page of a set that a navigation opened (not its ticket's answer) says so as it arrives
|
|
319
324
|
// (P098), below, once the shell can speak: the notice its last page sent as it left can reach
|
|
320
325
|
// the host after this page's load, or never (Chromium forwards a cross-process message from a
|
|
321
|
-
// task of the sending document's, which a navigation that commits first drops).
|
|
322
|
-
|
|
326
|
+
// task of the sending document's, which a navigation that commits first drops). With or without
|
|
327
|
+
// the Navigation API (P142): where there is none, the leaving page sends nothing, and this is the
|
|
328
|
+
// page's only word.
|
|
329
|
+
const arrived = filesBase !== null && typeof plan.files.address !== "string";
|
|
323
330
|
if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
|
|
324
|
-
arrived = filesBase !== null && typeof plan.files.address !== "string";
|
|
325
331
|
navigationApi.addEventListener("navigate", (event) => {
|
|
326
332
|
const destination = applyOf(destinationOf, event, []);
|
|
327
333
|
if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
|
|
@@ -1598,9 +1604,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1598
1604
|
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
|
|
1599
1605
|
};
|
|
1600
1606
|
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
1601
|
-
// content's word, which the host gates before it acts on it.
|
|
1607
|
+
// content's word, which the host gates before it acts on it. A hostless plan says nothing (P143).
|
|
1602
1608
|
const post = (message) => {
|
|
1603
|
-
if (window.parent !== window) {
|
|
1609
|
+
if (window.parent !== window && !hostless) {
|
|
1604
1610
|
window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
|
|
1605
1611
|
}
|
|
1606
1612
|
};
|
|
@@ -1632,6 +1638,15 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1632
1638
|
if (arrived) {
|
|
1633
1639
|
notice(location.href, { arrived: true });
|
|
1634
1640
|
}
|
|
1641
|
+
// A navigation within the document (a fragment, history between its entries) says the page
|
|
1642
|
+
// stayed (P142): WebKit fires the frame's load for one (measured, 18.2 and 26.6: a link to
|
|
1643
|
+
// #bottom, the first in a document), which the host would otherwise take for content that left.
|
|
1644
|
+
// Listened for now, before any content runs; each is the content's word, as every notice is.
|
|
1645
|
+
if (filesSet !== null && filesBase !== null) {
|
|
1646
|
+
const stayed = () => notice(location.href, { same: true });
|
|
1647
|
+
window.addEventListener("popstate", stayed, true);
|
|
1648
|
+
window.addEventListener("hashchange", stayed, true);
|
|
1649
|
+
}
|
|
1635
1650
|
// A sealed files' address opens the page's files on its own for a while (P083): renewed before
|
|
1636
1651
|
// it ends, the page moved to the new one in place (the same page, the same history entry). Its
|
|
1637
1652
|
// modules keep the address they loaded from; the server serves their own loads till the session
|
|
@@ -2269,7 +2284,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
2269
2284
|
|
|
2270
2285
|
// The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
|
|
2271
2286
|
// after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
|
|
2272
|
-
// hears it, and the runtime has nothing to offer from the start.
|
|
2287
|
+
// hears it, and the runtime has nothing to offer from the start. Nor under a plan that names no
|
|
2288
|
+
// host (P143): no parent is one. How it ended goes on the
|
|
2273
2289
|
// document's root element (data-porthole-host: "answered", or "none" where no host answered), for
|
|
2274
2290
|
// a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
|
|
2275
2291
|
// which a whole document's render takes out with the body it replaces, while the root stays (the
|
|
@@ -2283,7 +2299,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
2283
2299
|
};
|
|
2284
2300
|
const handshake = ${HANDSHAKE};
|
|
2285
2301
|
handshake(
|
|
2286
|
-
window.top === window,
|
|
2302
|
+
window.top === window || hostless,
|
|
2287
2303
|
() =>
|
|
2288
2304
|
request("ui/initialize", {
|
|
2289
2305
|
protocolVersion: plan.protocolVersion,
|
package/docs/ADOPTING.md
CHANGED
|
@@ -753,7 +753,21 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
|
|
|
753
753
|
`appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
|
|
754
754
|
page between them is still the frame's parent, and its `frame-ancestors` is yours to set. A
|
|
755
755
|
content Worker of your own passes the same list to `statusPage`, `doorResponse`,
|
|
756
|
-
`doorStatusResponse` and `nestedShellResponse` (`framedBy`)
|
|
756
|
+
`doorStatusResponse` and `nestedShellResponse` (`framedBy`), and puts it in the nested page's
|
|
757
|
+
rows below (`<framedBy>`). The outer page is then an ancestor of content: a content page can
|
|
758
|
+
`postMessage` it and every frame in its tree, and learn its origin, so the outer page's authors
|
|
759
|
+
must check `event.source` and `event.origin` in every message listener
|
|
760
|
+
([THREAT_MODEL.md §6 "What every host must do"](THREAT_MODEL.md#what-every-host-must-do)).
|
|
761
|
+
- **`embeds`** (P143): to let any site embed a public artifact page, set `embeds: true` and, from
|
|
762
|
+
one route of your own that decides the page is public (never your reader's issue endpoint),
|
|
763
|
+
issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page that
|
|
764
|
+
isn't nested). That session's answers say `frame-ancestors *`, and nothing else's do. It has no
|
|
765
|
+
host: frame it from an outer page of your own that listens to nothing (its `frame-src` the one
|
|
766
|
+
label), which any site may frame; the shell asks no host and says nothing to any parent, links out
|
|
767
|
+
of the page go nowhere (give the outer page your own "Open" link), and there is no door.
|
|
768
|
+
`authorize.check` gets `embed: true` for it, so your check can hold an embed subject to embed
|
|
769
|
+
sessions. A content Worker of your own answers its refusals before a session exists with
|
|
770
|
+
`statusPage({ embed: true, … })` or `doorStatusResponse({ embed: true, … })`.
|
|
757
771
|
- **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
|
|
758
772
|
`""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
|
|
759
773
|
`{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
|
|
@@ -929,10 +943,10 @@ no frame), `nestedShellResponse` throws for another origin, and the shell runs n
|
|
|
929
943
|
| Request | Answer |
|
|
930
944
|
| --- | --- |
|
|
931
945
|
| `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, framedBy, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins> <framedBy>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
|
|
932
|
-
| `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
|
|
933
|
-
| `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
|
|
946
|
+
| `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins> <framedBy>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
|
|
947
|
+
| `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above, `<origin> <host origins> <framedBy>`): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
|
|
934
948
|
| `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
|
|
935
|
-
| A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins>`: it tells the shell, which tells your page (`outcome` blocked). |
|
|
949
|
+
| A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins> <framedBy>`: it tells the shell, which tells your page (`outcome` blocked). |
|
|
936
950
|
|
|
937
951
|
### The capability runtime: pages that are apps
|
|
938
952
|
|
package/docs/DECISIONS.md
CHANGED
|
@@ -2703,7 +2703,7 @@ moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKi
|
|
|
2703
2703
|
**Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
|
|
2704
2704
|
the shared cache), or hosts need a version's files cached across sessions (a seal per day).
|
|
2705
2705
|
|
|
2706
|
-
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098
|
|
2706
|
+
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098, P142
|
|
2707
2707
|
|
|
2708
2708
|
**Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
|
|
2709
2709
|
started again) for served pages with files. The shell's plan names the version's files' address
|
|
@@ -2738,7 +2738,7 @@ subscriptions a page left keep running until the display ends.
|
|
|
2738
2738
|
artifact's display, not one sent eleven seconds before the load, and never for a widget's).
|
|
2739
2739
|
**Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
|
|
2740
2740
|
Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
|
|
2741
|
-
the display).
|
|
2741
|
+
the display; since P142 they don't: the arriving page's word is sent without the API).
|
|
2742
2742
|
|
|
2743
2743
|
## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091, P139
|
|
2744
2744
|
|
|
@@ -4061,7 +4061,7 @@ origin check stays, for frames on one host page); when an engine stops sending `
|
|
|
4061
4061
|
metadata where this relies on them; or when a previewed app needs a write from another site (an
|
|
4062
4062
|
opt-in per display, with its test).
|
|
4063
4063
|
|
|
4064
|
-
## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted
|
|
4064
|
+
## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted; amended by P142
|
|
4065
4065
|
|
|
4066
4066
|
The 2026-10-19 audit's flaky tests (baseline 264b12fa), which a release that waits for all of CI
|
|
4067
4067
|
(P097) can no longer shrug off. Amends P084 (the notice) and P025 (how the suite knows which
|
|
@@ -4084,7 +4084,8 @@ browsers keep a framed cookie).
|
|
|
4084
4084
|
the access the page is served for; not secret);
|
|
4085
4085
|
- the shell of a page a navigation opened (a page of files that is not its ticket's answer)
|
|
4086
4086
|
says `porthole/navigating` with `arrived: true` as it starts. Set inside the guard's own
|
|
4087
|
-
block, so `navigate-guard` (the guard taken out) removes it with every other notice
|
|
4087
|
+
block, so `navigate-guard` (the guard taken out) removes it with every other notice (since
|
|
4088
|
+
P142 set outside it, with or without the Navigation API; `navigate-guard` still removes it);
|
|
4088
4089
|
- which loads are the set's own pages is decided by `pagesOfSet` (`host/pages-of-set.ts`) on
|
|
4089
4090
|
the frame's surface, before anything the frame says reaches the display. The leaving page's
|
|
4090
4091
|
notice is taken for the next load within ten seconds, as before; the arriving page's too (the
|
|
@@ -8655,7 +8656,7 @@ it fails at the second pick.
|
|
|
8655
8656
|
highlight from `selected`), or a host is seen confused by `orphaned` after an upgrade.
|
|
8656
8657
|
|
|
8657
8658
|
|
|
8658
|
-
## P141 · 2026-11-09 · An app framed by another: its outer page may be an ancestor of its frames, never their host (`framedBy`) · Accepted
|
|
8659
|
+
## P141 · 2026-11-09 · An app framed by another: its outer page may be an ancestor of its frames, never their host (`framedBy`) · Accepted; amended by P144
|
|
8659
8660
|
|
|
8660
8661
|
From Raft (task #botiverse-raft-deployment:#245, Tenny): Deck (`https://deck.raft.build`, and
|
|
8661
8662
|
`https://deck-aws-dev.raft.build` on staging) frames the Raft app (`app.raft.build`) in an iframe.
|
|
@@ -8765,3 +8766,285 @@ control, run as mutations.
|
|
|
8765
8766
|
**Revisit when** an outer page needs to speak to a frame (then it is a host, and needs
|
|
8766
8767
|
`appOrigins`), browsers give a policy for the parent alone, or a host wants an outer page to frame
|
|
8767
8768
|
content without its own page between them.
|
|
8769
|
+
|
|
8770
|
+
## P142 · 2026-11-09 · A set's pages without the Navigation API, and a page that stays at a link within it · Accepted
|
|
8771
|
+
|
|
8772
|
+
From Raft (task #proj-workspace:#251, InNOut): on staging, in a multi-page served artifact, WebKit
|
|
8773
|
+
18.2 (Playwright 1.49.1, Safari 18's engine, no Navigation API) started the display again at its
|
|
8774
|
+
entry on every link to another page of the set, and on a link to `#bottom` in the same page. Then
|
|
8775
|
+
on WebKit 26.6 (Playwright 1.63, with the API): pages fine, `#bottom` started it again about 2.5 s
|
|
8776
|
+
after the click. Chromium: both fine. Amends P084 and P098 (its "Revisit when": an engine without
|
|
8777
|
+
the Navigation API).
|
|
8778
|
+
|
|
8779
|
+
**Measured** (the leak harness; WebKit r2104 = 18.2 run with Playwright 1.49.1 and Ubuntu 24.04's
|
|
8780
|
+
libraries, WebKit 26.6, Chromium and Firefox 155 with Playwright 1.63; "without the API" is the
|
|
8781
|
+
frame with `navigation` and every `Navigat*` interface deleted before the shell runs, and WebKit
|
|
8782
|
+
18.2 itself):
|
|
8783
|
+
- *A link to another page, without the API.* The shell said nothing. The leaving page's notice
|
|
8784
|
+
comes from the guard's `navigate` listener (P084), and the arriving page's `arrived: true` was
|
|
8785
|
+
set inside the guard's own block (P098, so `navigate-guard` would take it out). Neither exists
|
|
8786
|
+
without the API. The frame's click handler still opens the page (`location.assign`). The new
|
|
8787
|
+
page's load reached `pagesOfSet` with no notice, and its `ui/initialize` ended the wait at once
|
|
8788
|
+
("a hello before any notice"): started again at once (failed on Chromium without the API and on
|
|
8789
|
+
WebKit 18.2).
|
|
8790
|
+
- *A link to `#bottom`.* Not a navigate event the shell announces: the guard passes a
|
|
8791
|
+
same-document navigation without a word, and the frame's click handler leaves a `#` link to the
|
|
8792
|
+
browser. Not the shell treating `hashchange` as navigation: nothing listened for it. It is a
|
|
8793
|
+
`load`. **WebKit fires the `<iframe>` element's `load` for the first navigation within the
|
|
8794
|
+
frame's document**: a listener on the host page's iframe saw it, no request reached the server,
|
|
8795
|
+
and the document stayed (its globals, its scroll, `location.hash`). On 18.2 the load comes before
|
|
8796
|
+
the frame's `popstate` and `hashchange`; on 26.6 after them. Chromium and Firefox fire none. The
|
|
8797
|
+
web platform takes any load after the first as the content navigating away (P031), and
|
|
8798
|
+
`pagesOfSet` waited `LATE_NOTICE_MS` (2 s) for a notice. None came, so the display started
|
|
8799
|
+
again: the 2.5 s InNOut saw. With the API or without it.
|
|
8800
|
+
|
|
8801
|
+
**Decision.**
|
|
8802
|
+
1. **A set's page that a navigation opened says `arrived: true` as it starts, with or without the
|
|
8803
|
+
Navigation API.** `arrived` is set outside the guard's block, from the plan alone (files, and
|
|
8804
|
+
no ticket's address). Without the API it is the page's only word, and P098 already takes it on
|
|
8805
|
+
either side of the load. No click fallback for the leaving notice: P098 takes the arriving
|
|
8806
|
+
page's word without one, and a click handler would cover links only, not `location`. So
|
|
8807
|
+
`arrived` alone covers it, and the tests show it does. `navigate-guard` (P079's control) also
|
|
8808
|
+
takes `arrived` out, so it still takes out every notice of a set's pages.
|
|
8809
|
+
2. **A navigation within a page's document says the page stayed**: `porthole/navigating
|
|
8810
|
+
{ url, same: true, set }` on each `popstate` and `hashchange` (window listeners the shell adds
|
|
8811
|
+
before content runs), in a set's page (files and their version), with or without the API. It is
|
|
8812
|
+
never a page change. `pagesOfSet` takes it for the load it came after, or for the next one within
|
|
8813
|
+
`LATE_NOTICE_MS` only (not P084's ten seconds: it is no page to come). It never shortens a
|
|
8814
|
+
page's notice already given, and is taken however often the same address comes again. Like
|
|
8815
|
+
`arrived`, it must name the mounted version: another version's, or none, ends a wait at once,
|
|
8816
|
+
started again. The shell adapter forgets nothing for it (the page's watches and subscriptions go
|
|
8817
|
+
on). A display whose pages never come with files is as before: every load after the first starts
|
|
8818
|
+
it again at once.
|
|
8819
|
+
|
|
8820
|
+
**What stays the accepted limit** (P079, P099, unchanged). Without the Navigation API the guard
|
|
8821
|
+
gets no events. A served frame can navigate itself to another content origin (`frame-src` lets it
|
|
8822
|
+
in), and a page on a tab can navigate itself away, or to a `blob:` document of its own. Every
|
|
8823
|
+
other navigation without the API is as before. Another path of its origin, a file that isn't a
|
|
8824
|
+
page, an outside site (`frame-src` stops it): the display starts again (or, on Firefox, an outside
|
|
8825
|
+
site leaves the document as it was). A link to a page the version doesn't have is one of these:
|
|
8826
|
+
the content service's 404 carries no shell, so no notice comes, and the 404 shows until
|
|
8827
|
+
`LATE_NOTICE_MS` runs out, then the display starts again at the entry (measured on WebKit 18.2,
|
|
8828
|
+
0.14.18: about 2.4 seconds). A single-document served artifact (no files, so no version in
|
|
8829
|
+
its notices), and every display that isn't an artifact with files, still starts again at a load
|
|
8830
|
+
after the first. On WebKit that includes the first link within the page. A frame can't tell the host
|
|
8831
|
+
a load is no new document without a version to name, and none of those waits for a notice
|
|
8832
|
+
(P031).
|
|
8833
|
+
|
|
8834
|
+
**Threat (PRINCIPLE 1): nothing loosened.** No CSP, sandbox, guard rule, gate or origin changed;
|
|
8835
|
+
the guard stops what it stopped, where it has events. The host takes a notice as before: only for
|
|
8836
|
+
a display whose pages may come with files, from the frame's window and origin, naming the mounted
|
|
8837
|
+
version, within its window. Both notices are the content's word. Content could always send
|
|
8838
|
+
`porthole/navigating` itself (P084: it only spares a restart, which P031 says is no wall).
|
|
8839
|
+
`arrived` without the API, or `same` from a listener, gives it nothing it lacked. A `same`
|
|
8840
|
+
notice's grant is shorter than the one content could already ask for. The wall against a
|
|
8841
|
+
navigated document running is the embedding page's `frame-src`, as P031 has it.
|
|
8842
|
+
|
|
8843
|
+
**Tested.** `leak/served/files.spec.ts`:
|
|
8844
|
+
- with the API: a link down the entry page and down a page a link opened. The page scrolls, the
|
|
8845
|
+
document stays, the display goes on, the frame announces no page change (only `same`), and the
|
|
8846
|
+
host blocks nothing.
|
|
8847
|
+
- without the API: a link to another page and back (one outcome, nothing blocked), and the link
|
|
8848
|
+
down the page as above.
|
|
8849
|
+
- the negative controls: a file that isn't a page and another path of the origin still start the
|
|
8850
|
+
display again at its entry, and an outside site hears nothing.
|
|
8851
|
+
|
|
8852
|
+
All pass on Chromium, WebKit 26.6 and Firefox 155, and on WebKit 18.2 itself. Before the fix, the
|
|
8853
|
+
page link failed on Chromium without the API and on WebKit 18.2, and the link down the page failed
|
|
8854
|
+
on WebKit 18.2 and 26.6 (started again). `test/pages-of-set.test.ts`: `same` before or after its
|
|
8855
|
+
load; again at the same address; no grant past `LATE_NOTICE_MS`; a page's grant kept; another
|
|
8856
|
+
version, or none, ends the wait; nothing for displays without files. `test/runtime-review.test.ts`:
|
|
8857
|
+
a `same` notice ends no watch (it failed before). Controls: `same-document-notice` (the listeners
|
|
8858
|
+
out) fails both link-down cases on all three engines (the frame says nothing; on WebKit the display
|
|
8859
|
+
starts again too). `navigate-guard` now also fails the page link without the API and both link-down
|
|
8860
|
+
cases, whose second page is opened by a link.
|
|
8861
|
+
|
|
8862
|
+
**Revisit when** an engine stops firing a frame's load for a navigation within its document
|
|
8863
|
+
(the `same` notice then has no load to explain), single-document served artifacts need it (give
|
|
8864
|
+
their notices the version), or hosts need Safari before 26 on a tab (P099's limit stands).
|
|
8865
|
+
|
|
8866
|
+
## P143 · 2026-11-10 · An embedded document: a public grant with no host, framed by any page (`embed`) · Accepted
|
|
8867
|
+
|
|
8868
|
+
From Raft (Tenny): public artifacts embedded on any site, as a video is. The host's own outer page
|
|
8869
|
+
(its code, no author code, and no host: it hears and tells nothing) frames the content frame, and
|
|
8870
|
+
any site frames that page.
|
|
8871
|
+
|
|
8872
|
+
**Context.** `frame-ancestors` names every ancestor (P141), so a frame below an unknown site needs
|
|
8873
|
+
`*`: "the outer page only" can't be said. P141 rejected a wildcard for `framedBy` because an outer
|
|
8874
|
+
page there is one product's and sits above a host, whose frames carry a viewer, a level and host
|
|
8875
|
+
functions. Here no host exists, and the page is public: it has no viewer to take anything from.
|
|
8876
|
+
The risk is the other way: a bug that lets `*` reach a reader's session makes signed-in content
|
|
8877
|
+
frameable anywhere. So `*` hangs on a flag the host mints on purpose, signed, and every other
|
|
8878
|
+
session is held to be unchanged.
|
|
8879
|
+
|
|
8880
|
+
**Decision.**
|
|
8881
|
+
|
|
8882
|
+
1. **`Grant.embed: true`**, taken only where the server opted in (`createServer({ embeds: true })`,
|
|
8883
|
+
`createContentHost({ embeds: true })`; default off, two switches), only with `anonymous: true`
|
|
8884
|
+
and no `level` or `user`, and only for an **artifact's page that isn't nested**: never a url-mode
|
|
8885
|
+
app, a served shell or the sandbox proxy (each needs a host to send it content or to relay; the
|
|
8886
|
+
proxy speaks to its parent itself), never a nested display. Anything else throws at `issue`, as
|
|
8887
|
+
does `embed` that isn't `true`; `enterBy` (a clean address is a tab's, P125) and `doorAnswer`
|
|
8888
|
+
refuse it too. `embeds` that isn't a boolean throws at `createServer`.
|
|
8889
|
+
2. **Signed into the session.** The session carries `m: 1` (not `e`: a sealed address's `e` is its
|
|
8890
|
+
session's end, and a redirect entry's state is marked `e`), and so does the frame's sealed files'
|
|
8891
|
+
address (P083), so it is never added to a session or taken from one without breaking the MAC or
|
|
8892
|
+
the seal. The ticket's record carries `embed`. An embed session's cookie has a name of its own,
|
|
8893
|
+
`__Host-porthole-e-<key>`, read only with `m: 1` (and the instance's own name only without it):
|
|
8894
|
+
where a browser partitions no cookies and holds both for one instance, the other session is the
|
|
8895
|
+
one served, never replaced or changed by the embed's. With `embeds` off, an embed ticket, cookie
|
|
8896
|
+
or sealed address opens nothing (it is refused, not read as another session): turning it off is
|
|
8897
|
+
a kill switch.
|
|
8898
|
+
3. **Any ancestor, for that session only.** Every answer of an embed session says `frame-ancestors
|
|
8899
|
+
*` instead of the server's list: its document (a ticket's, a cookie's reload), a file set's
|
|
8900
|
+
pages and files (its own frames: `*` already covers its origin), assets, renewals, and its status
|
|
8901
|
+
pages: the host's refusal, a version gone, a missing page, and its ended access (a sealed address
|
|
8902
|
+
this server sealed with `m`, once it no longer opens). Without `embed`, every answer is as
|
|
8903
|
+
before, byte for byte. Answers before any session exists (a used ticket, a request with no
|
|
8904
|
+
cookie) can't know of one and are as before.
|
|
8905
|
+
4. **No host at all.** The plan's `origins` are `[]`; a status page's `data-porthole-hosts="[]"`
|
|
8906
|
+
(and so `data-porthole-strict-parent`, P141). The shell reads its plan's hosts first
|
|
8907
|
+
(`hostless`): it asks no host and ends its handshake at once, as on a tab (P139: `HANDSHAKE` is
|
|
8908
|
+
given "no host"), `data-porthole-host="none"`, no `ui/initialize`, no timer, `porthole.use`
|
|
8909
|
+
null; and it says nothing to any parent: its one `post` (requests, answers, its own `*`
|
|
8910
|
+
notices of P053: sizes, errors, navigation, storage) and the annotation and find runtimes'
|
|
8911
|
+
reports are held. No origin is in an empty list, so it hears no one. `issue` answers
|
|
8912
|
+
`reports: false` and no viewer.
|
|
8913
|
+
5. **No door** is minted: a door tells a host how loading went, and there is none.
|
|
8914
|
+
6. **`authorize.check` is told `embed: true`** for an embed session (absent for every other), and
|
|
8915
|
+
its cached answers are an embed session's own: a host holds its embed subject to embed sessions.
|
|
8916
|
+
7. **`statusPage` and `doorStatusResponse` take `embed: true`** (then no `hostOrigins`,
|
|
8917
|
+
`framedBy` or `frameAncestors`): `*`, told to no one, for a content Worker's own answer before an
|
|
8918
|
+
embed session exists (not public, rate-limited), shown where the embed is.
|
|
8919
|
+
|
|
8920
|
+
**What it re-opens (PRINCIPLE 1).** Any site may frame an embed session's documents.
|
|
8921
|
+
- *Clickjacking*: with nothing to click. The session has no viewer and no level; there is no host,
|
|
8922
|
+
so no capability, no runtime host function, no `comments`, `copyText` or `openLink`, and the
|
|
8923
|
+
bridge never runs. A link out of the page goes nowhere (the guard stops it, P079; the frame's
|
|
8924
|
+
sandbox has no popups and no top navigation): the host's outer page is the way out.
|
|
8925
|
+
- *An outer page framing content directly*: a site can if it has an address. The host's route that
|
|
8926
|
+
mints embed sessions bounds that (the host's to say: same-site entry only, say); if one does, it
|
|
8927
|
+
gets what the outer page gets, no channel. Author script can still `postMessage` to its parent or
|
|
8928
|
+
`top`, as any framed page can: the author's own word, about a public page, which the embedding
|
|
8929
|
+
site must treat as untrusted.
|
|
8930
|
+
- *Partitioned cookies*: keyed to the embedding site (CHIPS), shared with nothing; `HttpOnly`,
|
|
8931
|
+
`__Host-` (host-only: never `Domain=`, so never the outer page's or a sibling label's, P101).
|
|
8932
|
+
- *Signed-in content made frameable*: the risk this entry is built against. `*` follows only the
|
|
8933
|
+
signed flag, which only `issue` given `embed` mints, where the host opted in; every other session
|
|
8934
|
+
is pinned unchanged by test, on the same server, while an embed session of the same artifact
|
|
8935
|
+
exists. The host must keep its other routes from minting `embed`.
|
|
8936
|
+
|
|
8937
|
+
**Rejected.**
|
|
8938
|
+
- *`framedBy: ["*"]`*: it widens every session, readers' included.
|
|
8939
|
+
- *The outer page as a host origin (`appOrigins`)*: a message channel to audit, and nothing to
|
|
8940
|
+
offer that needs one now.
|
|
8941
|
+
- *Refusing a parent that isn't the outer page by `ancestorOrigins`*: Firefox masks it (P141).
|
|
8942
|
+
- *Every document kind*: a served shell waits for its host to send content and the proxy says
|
|
8943
|
+
`ready` to its parent; neither has anything to show with no host.
|
|
8944
|
+
|
|
8945
|
+
**Tested.** `test/embed.test.ts`: `embed` refused without `embeds` (or with `embeds: false`), with a
|
|
8946
|
+
viewer, a level or a user, unless `true`, for url mode, a nested display, a served shell and the
|
|
8947
|
+
proxy, at a clean address and at the door; issue mints no door and says `reports: false`; the host
|
|
8948
|
+
kit takes it only where it opted in. The flag can't be stripped from an embed session or added to a
|
|
8949
|
+
public one (401, the server's list), a good session under the other name opens nothing, a changed
|
|
8950
|
+
sealed address opens nothing, and with `embeds` off an embed session's cookie and address open
|
|
8951
|
+
nothing. **The bound**: 23 kinds of answer (a page's ticket and cookie reload; two file sets', one
|
|
8952
|
+
with its own frames: ticket, page at its base, script, file, missing file, renewal, renewal from
|
|
8953
|
+
elsewhere, asset, missing asset; the host's refusal; a version gone; ended access) under an embed
|
|
8954
|
+
session say `*` and name no host (`"origins":[]`, `data-porthole-hosts="[]"`), and the host's check
|
|
8955
|
+
is told `embed` every time; the same under a public session and a viewer's session never say `*`
|
|
8956
|
+
and are, evened out for sealed addresses and their ends, byte for byte what a server without
|
|
8957
|
+
`embeds` answers; a member's session answers the same before an embed session of the same artifact
|
|
8958
|
+
exists and after, interleaved; with both cookies sent the member's session is served. Cookies of
|
|
8959
|
+
both kinds are host-only (`__Host-`, never `Domain=`; none on loopback http either). `statusPage`
|
|
8960
|
+
and `doorStatusResponse` with `embed`: `*`, no host, a script that tells no parent. Taking `*` to
|
|
8961
|
+
every session fails three of these. `test/shell.test.ts`: a hostless plan in a frame asks nothing,
|
|
8962
|
+
sets no timer and ends with no host at once, and its one `post` and the annotation and find reports
|
|
8963
|
+
are held. `leak/served/embed.spec.ts` (a foreign site framing a page that is no host, framing the
|
|
8964
|
+
content; Chromium here, WebKit and Firefox in CI): `[embed.loads]`; `[embed.unheard]` (the outer
|
|
8965
|
+
page's and the site's host words: a document to draw, a theme, answers to the shell's requests, all
|
|
8966
|
+
dropped); `[embed.untold]` (neither hears a Porthole word, and the handshake ended `"none"` at once);
|
|
8967
|
+
`[embed.no-escape]` (no window, no top navigation, no link out, no self-navigation to another
|
|
8968
|
+
label); `[embed.reader-unframeable]` (a public and a viewer's session refused below the site, with or
|
|
8969
|
+
without the outer page; shown below the host). **The negative controls**: `embed-ancestors`
|
|
8970
|
+
(harness: every answer `*`) fails `[embed.reader-unframeable]`; `embed-handshake` (a hostless plan
|
|
8971
|
+
asks and posts) fails `[embed.untold]`; `embed-origins` (the origins check skipped for a hostless
|
|
8972
|
+
plan) fails `[embed.unheard]`; each exactly that probe on Chromium.
|
|
8973
|
+
|
|
8974
|
+
**Revisit when** an embed needs a host function (then the outer page becomes a narrow host, with
|
|
8975
|
+
its own entry), auto-height needs a word to the embedding site, or browsers give a policy for the
|
|
8976
|
+
parent alone.
|
|
8977
|
+
|
|
8978
|
+
## P144 · 2026-11-10 · After the audit of 0.14.17 and 0.14.18: `framedBy`'s default path byte for byte, the nesting it is for, origins compared as browsers serialize them · Accepted
|
|
8979
|
+
|
|
8980
|
+
Amends P141 (its decision 1's "byte for byte", its decision 3 and its "What it re-opens"). From
|
|
8981
|
+
Ferryman's audit of 0.14.17 (P141) and 0.14.18 (P142): no P0 and no new egress; four findings, all
|
|
8982
|
+
fixed here.
|
|
8983
|
+
|
|
8984
|
+
**Context.**
|
|
8985
|
+
1. *(P1) The default path's scripts.* Without `framedBy`, every `frame-ancestors` and every
|
|
8986
|
+
behaviour was 0.14.16's, but the status, entry and door pages' scripts and the nested page's
|
|
8987
|
+
shell carried P141's `strict` branch on every path, unused there, so their bytes and their
|
|
8988
|
+
`script-src` hashes changed. P141's decision 1 and 0.14.17's changelog said every response was
|
|
8989
|
+
as before, byte for byte.
|
|
8990
|
+
2. *(P2) The nesting P141 is for.* P141's "What it re-opens" and THREAT_MODEL described an outer
|
|
8991
|
+
page that frames content directly. In the nesting it was made for (the outer page, then the app's
|
|
8992
|
+
page, then content), content is a descendant of the outer page: it can `postMessage` the outer
|
|
8993
|
+
page and every frame in its tree, and learn the outer page's origin (measured in Chromium and
|
|
8994
|
+
Firefox). No header stops that, as none stops a frame posting the other frames of its page (S7).
|
|
8995
|
+
3. *(P3) The host-origin check compared strings.* `https://app.example.com:443` as `framedBy`
|
|
8996
|
+
beside `https://app.example.com` as a host origin passed (and the reverse): one origin named as
|
|
8997
|
+
both a host and an outer page, which decision 3 refuses. Only narrower in effect (the host's own
|
|
8998
|
+
pages turned strict), but not what was said.
|
|
8999
|
+
4. *(P3) ADOPTING's nested-page rows.* The page's, its files' and an ended token's
|
|
9000
|
+
`frame-ancestors` lacked `<framedBy>`: a content Worker copied from them shows a blank frame below
|
|
9001
|
+
the outer page.
|
|
9002
|
+
|
|
9003
|
+
**Decision.**
|
|
9004
|
+
1. **Without `framedBy` (and without an embed, P143), 0.14.16's scripts, byte for byte.** Each of
|
|
9005
|
+
the four scripts comes in two: 0.14.16's, and a strict one (0.14.17's, unchanged) for a page
|
|
9006
|
+
whose `frame-ancestors` names anyone beyond its host origins (`framedBy`, or an embed's `*`). The
|
|
9007
|
+
status and entry pages load 0.14.16's from `/__porthole/status.js` and `/__porthole/enter.js` as
|
|
9008
|
+
before, and a strict page loads `/__porthole/status-strict.js` or `/__porthole/enter-strict.js`
|
|
9009
|
+
(all four served on every content origin); a door, a door that doesn't open and a relay's status
|
|
9010
|
+
page carry 0.14.16's inline (under its hash as before) or the strict one under its own; a nested
|
|
9011
|
+
page's shell runs 0.14.16's runtime unless it is given `framedBy`. So without `framedBy` every
|
|
9012
|
+
response is 0.14.16's again, byte for byte, as P141 said; with it, 0.14.17's, but for the two
|
|
9013
|
+
strict pages' script address.
|
|
9014
|
+
2. **The nesting, said.** THREAT_MODEL §6 "What every host must do" and S7, P141's entry in it, and
|
|
9015
|
+
ADOPTING's `framedBy`: the outer page's authors must check `event.source` and `event.origin` in
|
|
9016
|
+
every message listener, on the outer page and in each of its frames, taking a message only from
|
|
9017
|
+
the window and origin they expect; and S7's rule (a page's egress is the union of its frames')
|
|
9018
|
+
now covers the outer page's frames: what content was given can be handed to any frame the outer
|
|
9019
|
+
page shows, and that frame's network becomes content's way out. Porthole can hold neither: both
|
|
9020
|
+
are the outer page's.
|
|
9021
|
+
3. **Origins compared as browsers serialize them.** `normalOrigin` (scheme and host lowercase, an
|
|
9022
|
+
`http`/`https` default port dropped) before every comparison of `framedBy` with the host origins
|
|
9023
|
+
(`createServer`, so the host kit; `statusPage`, `doorResponse`, `doorStatusResponse`,
|
|
9024
|
+
`nestedShellCsp` and `nestedShellResponse`; `frameShellScript`), and for an outer page named
|
|
9025
|
+
twice (kept once, as first named). Inputs are still held to P141's exact, lowercase forms: this
|
|
9026
|
+
only catches two spellings of one origin.
|
|
9027
|
+
4. **ADOPTING's three nested-page rows name `<framedBy>`.**
|
|
9028
|
+
|
|
9029
|
+
**Rejected.**
|
|
9030
|
+
- *One script per page that reads its strictness from the page (0.14.17's)*: its bytes, and so
|
|
9031
|
+
its hash, change for every host so that one that names an outer page has the check.
|
|
9032
|
+
- *A strict page's status and entry scripts inline, under their hash*: those pages' policy is
|
|
9033
|
+
`script-src 'self'`; changing it for the strict path is wider than two addresses.
|
|
9034
|
+
|
|
9035
|
+
**Tested.** `test/framed-by.test.ts`: the four scripts pinned to 0.14.16's sha256 (from
|
|
9036
|
+
`git show v0.14.16:…`): `/__porthole/status.js`, `/__porthole/enter.js`, the door's and the inline
|
|
9037
|
+
status script's `script-src`, the nested shell's runtime and its script for a fixed plan, from the
|
|
9038
|
+
helpers and from a server without `framedBy` (its 404 and used ticket load `status.js`, its entry
|
|
9039
|
+
page `enter.js`, its door and nested shell carry 0.14.16's); with `framedBy` the strict pages load
|
|
9040
|
+
the strict addresses, which carry the check, and the old addresses still serve 0.14.16's. P141's
|
|
9041
|
+
negative control now runs the strict script for a strict page and 0.14.16's for its control.
|
|
9042
|
+
Origins: `normalOrigin` and `includesOrigin` (default ports, case, IPv6, another port, a desktop
|
|
9043
|
+
scheme); `createServer` and the host kit refusing a host origin as `framedBy` with or without
|
|
9044
|
+
`:443`, either way round (and `http://localhost` beside `:80`), taking another port; the helpers
|
|
9045
|
+
and `frameShellScript` refusing it; an outer page named with and without `:443` named once.
|
|
9046
|
+
`leak/served/framed-by.spec.ts` and the served suites over the status, entry and door pages and
|
|
9047
|
+
the nested shell pass unchanged on Chromium.
|
|
9048
|
+
|
|
9049
|
+
**Revisit when** a host needs a strict page's script at the old address, or browsers give a policy
|
|
9050
|
+
for the parent alone.
|