@botiverse/porthole 0.14.18 → 0.15.1
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 +82 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +11 -1
- package/dist/isolation/served.js +56 -2
- package/dist/server/host.d.ts +16 -1
- package/dist/server/host.js +6 -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 +12 -6
- package/docs/ADOPTING.md +25 -4
- package/docs/DECISIONS.md +300 -2
- package/docs/DESIGN.md +4 -0
- package/docs/THREAT_MODEL.md +52 -2
- package/package.json +1 -1
- package/src/isolation/served.ts +58 -2
- package/src/server/host.ts +26 -1
- 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 +12 -6
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.
|
|
@@ -1599,9 +1604,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1599
1604
|
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
|
|
1600
1605
|
};
|
|
1601
1606
|
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
1602
|
-
// 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).
|
|
1603
1608
|
const post = (message) => {
|
|
1604
|
-
if (window.parent !== window) {
|
|
1609
|
+
if (window.parent !== window && !hostless) {
|
|
1605
1610
|
window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
|
|
1606
1611
|
}
|
|
1607
1612
|
};
|
|
@@ -2279,7 +2284,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
2279
2284
|
|
|
2280
2285
|
// The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
|
|
2281
2286
|
// after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
|
|
2282
|
-
// 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
|
|
2283
2289
|
// document's root element (data-porthole-host: "answered", or "none" where no host answered), for
|
|
2284
2290
|
// a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
|
|
2285
2291
|
// which a whole document's render takes out with the body it replaces, while the root stays (the
|
|
@@ -2293,7 +2299,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
2293
2299
|
};
|
|
2294
2300
|
const handshake = ${HANDSHAKE};
|
|
2295
2301
|
handshake(
|
|
2296
|
-
window.top === window,
|
|
2302
|
+
window.top === window || hostless,
|
|
2297
2303
|
() =>
|
|
2298
2304
|
request("ui/initialize", {
|
|
2299
2305
|
protocolVersion: plan.protocolVersion,
|
package/docs/ADOPTING.md
CHANGED
|
@@ -753,7 +753,28 @@ 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): `host.server.issue(instance, { anonymous: true, embed: true })`. Never answer
|
|
765
|
+
`embed` from `access`: it answers your readers, and the kit refuses it there (409 from the issue
|
|
766
|
+
endpoint and a clean address's resolve, its 409 page at a clean address's tab; P145). That
|
|
767
|
+
session's answers say `frame-ancestors *`, and nothing else's do. It has no
|
|
768
|
+
host: frame it from an outer page of your own that listens to nothing (its `frame-src` the one
|
|
769
|
+
label), which any site may frame; the shell asks no host and says nothing to any parent, links out
|
|
770
|
+
of the page go nowhere (give the outer page your own "Open" link), and there is no door.
|
|
771
|
+
`authorize.check` gets `embed: true` for it, so your check can hold an embed subject to embed
|
|
772
|
+
sessions. A content Worker of your own answers its refusals before a session exists with
|
|
773
|
+
`statusPage({ embed: true, … })` or `doorStatusResponse({ embed: true, … })`. The page learns
|
|
774
|
+
where it is embedded: its request's `Referer` and `document.referrer` name your outer page, and
|
|
775
|
+
`location.ancestorOrigins` names every ancestor, the embedding site included (Chromium, Firefox
|
|
776
|
+
and WebKit), so a page with any egress can report where it is shown
|
|
777
|
+
([THREAT_MODEL.md S4](THREAT_MODEL.md#s4-public-links-and-pages-that-are-apps)).
|
|
757
778
|
- **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
|
|
758
779
|
`""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
|
|
759
780
|
`{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
|
|
@@ -929,10 +950,10 @@ no frame), `nestedShellResponse` throws for another origin, and the shell runs n
|
|
|
929
950
|
| Request | Answer |
|
|
930
951
|
| --- | --- |
|
|
931
952
|
| `<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. |
|
|
953
|
+
| `<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`). |
|
|
954
|
+
| `<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
955
|
| `<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). |
|
|
956
|
+
| 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
957
|
|
|
937
958
|
### The capability runtime: pages that are apps
|
|
938
959
|
|
package/docs/DECISIONS.md
CHANGED
|
@@ -8656,7 +8656,7 @@ it fails at the second pick.
|
|
|
8656
8656
|
highlight from `selected`), or a host is seen confused by `orphaned` after an upgrade.
|
|
8657
8657
|
|
|
8658
8658
|
|
|
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
|
|
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
|
|
8660
8660
|
|
|
8661
8661
|
From Raft (task #botiverse-raft-deployment:#245, Tenny): Deck (`https://deck.raft.build`, and
|
|
8662
8662
|
`https://deck-aws-dev.raft.build` on staging) frames the Raft app (`app.raft.build`) in an iframe.
|
|
@@ -8822,7 +8822,10 @@ gets no events. A served frame can navigate itself to another content origin (`f
|
|
|
8822
8822
|
in), and a page on a tab can navigate itself away, or to a `blob:` document of its own. Every
|
|
8823
8823
|
other navigation without the API is as before. Another path of its origin, a file that isn't a
|
|
8824
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
|
|
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
|
|
8826
8829
|
its notices), and every display that isn't an artifact with files, still starts again at a load
|
|
8827
8830
|
after the first. On WebKit that includes the first link within the page. A frame can't tell the host
|
|
8828
8831
|
a load is no new document without a version to name, and none of those waits for a notice
|
|
@@ -8859,3 +8862,298 @@ cases, whose second page is opened by a link.
|
|
|
8859
8862
|
**Revisit when** an engine stops firing a frame's load for a navigation within its document
|
|
8860
8863
|
(the `same` notice then has no load to explain), single-document served artifacts need it (give
|
|
8861
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; amended by P145
|
|
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; amended by P145
|
|
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.
|
|
9051
|
+
|
|
9052
|
+
## P145 · 2026-11-10 · After the audit of 0.15.0: "byte for byte" said as it holds, embeds never from `access`, what an embed page learns, origins' ports · Accepted
|
|
9053
|
+
|
|
9054
|
+
Amends P143 (its decision 3's "as before, byte for byte", and its host duties) and P144 (its
|
|
9055
|
+
decision 1's "every response is 0.14.16's again", and its decision 3's "P141's exact forms"). From
|
|
9056
|
+
Ferryman's audit of 0.15.0 (P143, P144): no P0, no escape, no new egress, and no way found for an
|
|
9057
|
+
embed session's `*` to reach another session; one P1 (by the rule that any default-path byte change
|
|
9058
|
+
is at least P1; P3 on its own) and three P3s, all fixed here.
|
|
9059
|
+
|
|
9060
|
+
**Context.**
|
|
9061
|
+
1. *(P1 by rule, P3 on its own) "Byte for byte".* P144 #1 ended "without `framedBy` every response
|
|
9062
|
+
is 0.14.16's again, byte for byte"; 0.15.0's CHANGELOG said "the default path is 0.14.16's
|
|
9063
|
+
again", and P143 #3 and its CHANGELOG line "every other session's answers are as before, byte
|
|
9064
|
+
for byte". Every header held (every CSP, `frame-ancestors`, `script-src` hash, cookie and cache
|
|
9065
|
+
header) and so did the four scripts P144 pinned. The bodies of the documents that inline the
|
|
9066
|
+
shell runtime did not: a served shell, an artifact page, a file set's pages, the MCP Apps proxy
|
|
9067
|
+
and the nested page carry P142's changes (0.14.18) and P143's `hostless` branches (0.15.0). Those
|
|
9068
|
+
branches are inert where a plan names a host (`createServer` refuses empty `hostOrigins`), and no
|
|
9069
|
+
hash covers the runtime (`'unsafe-inline'`), so nothing a browser does changed; the claim did.
|
|
9070
|
+
P143's bound test compares with a 0.15.0 server without `embeds`, which carries the same runtime,
|
|
9071
|
+
so it could not see this.
|
|
9072
|
+
2. *(P3) The kit's `embeds` said "whether `access` may answer an embed grant".* `access` answers
|
|
9073
|
+
the kit's reader issue endpoint and a clean address's resolve, which ADOPTING and THREAT_MODEL
|
|
9074
|
+
say must never mint `embed`, and the kit's test minted it there. A host that followed the kit's
|
|
9075
|
+
doc made signed-out readers' frames hostless and frameable by any site (nothing signed-in rode
|
|
9076
|
+
along: `checkGrant` refuses a viewer, level or user with `embed`).
|
|
9077
|
+
3. *(P3) An embed page learns where it is embedded*, which P143 didn't say beside "the embedding
|
|
9078
|
+
site sees the page load".
|
|
9079
|
+
4. *(P3) Ports.* `framedByProblem` (and `hostOriginProblem`) took `:0`, `:99999` and `:0443`, and a
|
|
9080
|
+
host the URL parser rewrites (`https://0x7f.0.0.1` is `https://127.0.0.1`). Each failed closed (a
|
|
9081
|
+
source that matches nothing, or a stricter page), but P144 said inputs are held to exact forms.
|
|
9082
|
+
5. *(P3) A control's probe failed at an unmarked step.* Under `embed-origins`, `[embed.unheard]`
|
|
9083
|
+
once failed at "the embedded page shows" instead of its verdict (Chromium, a loaded box), so the
|
|
9084
|
+
runner counted it as not failing by its probe. The cause: the shell draws one document
|
|
9085
|
+
(`render` runs once), and the hostile outer page says a document every 100 ms. A weakened shell
|
|
9086
|
+
that hears that word before its own document has loaded draws the word instead of the page
|
|
9087
|
+
(`#taken`, no `#content`), and the step before the verdict waited 5 s for `#content`. Reproduced
|
|
9088
|
+
on Chromium and Firefox by delivering the document in two parts: both failed "unmarked: Error:
|
|
9089
|
+
the embedded page shows".
|
|
9090
|
+
|
|
9091
|
+
**Decision.**
|
|
9092
|
+
1. **Said as it holds.** Without `framedBy` and an embed, every header and the status, entry and
|
|
9093
|
+
door pages' scripts and the nested page's shell are 0.14.16's, byte for byte; the shell runtime
|
|
9094
|
+
that served documents inline is 0.15.0's: P142's changes and P143's `hostless` branches, inert
|
|
9095
|
+
where a plan names a host. Every other session's answers are, byte for byte, what the same server
|
|
9096
|
+
without `embeds` answers. THREAT_MODEL's status line, S4 and 0.15.0's CHANGELOG lines say so.
|
|
9097
|
+
The runtime is not moved again: splicing `hostless` into embed documents alone (as P144 did for
|
|
9098
|
+
`strict`) would make the claim true against 0.14.18 only, not 0.14.16, for a third runtime
|
|
9099
|
+
variant. Instead **its bytes are pinned** (`SHELL_RUNTIME`, `ANNOTATE_RUNTIME`, `FIND_RUNTIME`,
|
|
9100
|
+
`USE_RUNTIME`, `LEGACY_GLOBALS_RUNTIME` by sha256): a change to them fails a test, so the next
|
|
9101
|
+
release says it rather than asserting it away.
|
|
9102
|
+
2. **Embeds never from `access`.** The host kit refuses an `access` answer that carries `embed`,
|
|
9103
|
+
whatever `embeds` says: 409 `refused` from its issue endpoint and a clean address's resolve, and
|
|
9104
|
+
a clean address's tab gets the kit's 409 page (`enterBy` refuses it, as before). A host mints an
|
|
9105
|
+
embed session from a route of its own with `host.server.issue(instance, { anonymous: true,
|
|
9106
|
+
embed: true })`, which needs `embeds: true`. `ContentHostOptions.embeds` and `access` say so.
|
|
9107
|
+
3. **What an embed page learns, said** (THREAT_MODEL S4, ADOPTING `embeds`). Measured in Chromium,
|
|
9108
|
+
Firefox (155) and WebKit: the content document's request carries the outer page's address as
|
|
9109
|
+
`Referer` (its origin, under the default referrer policy; Firefox 155 also sends it as `Origin`, Chromium
|
|
9110
|
+
and WebKit send no `Origin`; Ferryman's recheck of #129),
|
|
9111
|
+
`document.referrer` is the same, and `location.ancestorOrigins` lists the outer page and the
|
|
9112
|
+
embedding site. A page with any egress can send that out. Porthole's served documents send no
|
|
9113
|
+
`Referer` of their own (`no-referrer`), which doesn't hide what the page reads.
|
|
9114
|
+
4. **A port is 1 to 65535, in plain decimal; an `http`/`https` host is as the URL parser gives
|
|
9115
|
+
it.** `hostOriginProblem` and `framedByProblem` refuse `:0`, `:00`, `:65536`, `:99999`, `:0443`,
|
|
9116
|
+
and a host like `0x7f.0.0.1`, `0177.0.0.1` or `127.1`; so `createServer`, the host kit and every
|
|
9117
|
+
helper that takes host origins or `framedBy` throw on them. A default port (`:443`) is still
|
|
9118
|
+
taken: browsers drop it and P144 compares it so; refusing it in a patch release would break a
|
|
9119
|
+
working config.
|
|
9120
|
+
5. **The probe judges, not the step before it.** `[embed.unheard]` waits for the page to have
|
|
9121
|
+
loaded, its own `#content` or a word's `#taken`, and leaves which one to its verdict. Its
|
|
9122
|
+
documents now arrive in two parts (the shell's script, then the rest 1.5 s later), so the words
|
|
9123
|
+
reach the shell before its document loads every time, not only on a loaded box: the probe covers
|
|
9124
|
+
the early words too, and `embed-origins` fails it with the page taken over (`taken: true`,
|
|
9125
|
+
`content: false`), on every engine.
|
|
9126
|
+
|
|
9127
|
+
**Rejected.**
|
|
9128
|
+
- *Requiring `new URL(origin).origin === origin`* (the audit's suggestion): it refuses `:443` too,
|
|
9129
|
+
which 0.15.0 takes for host origins and `framedBy` alike (P144's tests); a patch should not break
|
|
9130
|
+
a working config. The rule above refuses everything else it would.
|
|
9131
|
+
- *The kit dropping `embed` from an `access` answer and issuing a public session*: a host that
|
|
9132
|
+
meant an embed would get a reader's frame without a word; a refusal says it.
|
|
9133
|
+
- *Running `embed.spec` on Firefox and WebKit through a workflow change*: CI's `loopback` job runs
|
|
9134
|
+
every spec (`testMatch: **/*.spec.ts`) on `chromium`, `chromium-oopif`, `webkit` and `firefox`,
|
|
9135
|
+
and `controls-shard` runs every control on `chromium`, `webkit` and `firefox`; 0.15.0's CI ran
|
|
9136
|
+
`embed.spec` on all three. Only P143's local run was Chromium alone.
|
|
9137
|
+
|
|
9138
|
+
**Tested.** `test/framed-by.test.ts`: the served shell runtime's five parts pinned to 0.15.0's
|
|
9139
|
+
sha256, three of them shown not 0.14.16's (and `use`, `legacy` the same), and on a server without
|
|
9140
|
+
`framedBy` or `embeds` an artifact page carries the `hostless` line with a plan naming its host
|
|
9141
|
+
origins; Ferryman's edges probe: thirteen origins (`:0`, `:00`, `:65536`, `:99999`, `:0443`,
|
|
9142
|
+
`:08443`, a host origin with `:0443`, `http://localhost:0`, `http://127.0.0.1:65536`,
|
|
9143
|
+
`0x7f.0.0.1`, `0177.0.0.1`, `127.1`, `203.0.113.07`) refused by `createServer`, the host kit,
|
|
9144
|
+
`statusPage`, `doorResponse`, `doorStatusResponse`, `nestedShellCsp` and `frameShellScript`; the
|
|
9145
|
+
audit's refused forms (a host origin with or without `:443`, a trailing dot, userinfo, Unicode, case,
|
|
9146
|
+
a path, `http:` off loopback, `ferry://App`) still refused; ports 1, 8443, 65535, a default port, an
|
|
9147
|
+
IPv4 address and loopback http taken; a host origin's port held the same; `embeds: "true"` throws.
|
|
9148
|
+
`test/origins.test.ts`: `hostOriginProblem` on the same ports and hosts, custom schemes included.
|
|
9149
|
+
`test/embed.test.ts`: the kit refuses `access` answering `embed` at its issue endpoint, a clean
|
|
9150
|
+
address's resolve (409 `refused`) and its tab (409, no redirect), with `embeds` absent, false and
|
|
9151
|
+
true, and issues a public grant from the same routes; `host.server.issue` mints the embed only with
|
|
9152
|
+
`embeds: true`. Taking the kit's check out fails the refusal test. `leak/served/embed.spec.ts`
|
|
9153
|
+
passes on Chromium, Firefox and WebKit, and `embed-ancestors`, `embed-handshake` and `embed-origins`
|
|
9154
|
+
each fail exactly their probe on all three. The old spec with its document in two parts failed
|
|
9155
|
+
`embed-origins` unmarked on Chromium and Firefox; this one fails it by the probe.
|
|
9156
|
+
|
|
9157
|
+
**Revisit when** the runtime pin changes (say what changed), a host needs `embed` from a reader's
|
|
9158
|
+
route (then it needs its own entry, never `access`), or a browser stops exposing
|
|
9159
|
+
`ancestorOrigins` to a framed page.
|
package/docs/DESIGN.md
CHANGED
|
@@ -1012,6 +1012,7 @@ for that to lapse and click with raw input.
|
|
|
1012
1012
|
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
|
|
1013
1013
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
1014
1014
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
1015
|
+
| An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page that isn't nested; signed into the session as `m` and into the sealed address) → `frame-ancestors *` for that session's answers alone (its document, a file set's pages and files and own frames, assets, renewals, its status and ended-access pages); an embed session's cookie has a name of its own (`e-<key>`) and never stands in for another session; the plan names no host (`origins: []`): the shell asks no host, ends its handshake at once (`"none"`), says nothing to any parent (no `*` notices, no annotation or find report) and hears no one; no door; `statusPage` and `doorStatusResponse` take `embed` (`*`, `data-porthole-hosts="[]"`); the host kit refuses an `access` answer with `embed` (P145: minted through `host.server.issue` alone) | `test/embed.test.ts` (refused without `embeds`, with a viewer, a level or a user, for url mode, a nested display, a served shell or the proxy, at a clean address and at the door; the host kit refuses it from `access` at its issue endpoint, a clean address's resolve and its tab, with `embeds` or without; the flag can't be added or stripped, nor a session moved to the other name; **the bound**: 23 kinds of answer under an embed session say `*` and name no host, and the same under a public and a viewer's session are byte for byte what a server without `embeds` answers, on the same server while an embed session of the same artifact exists, and with both cookies sent; the host's check is told `embed`; cookies host-only, never `Domain=`); `test/shell.test.ts` (P143's handshake); `leak/served/embed.spec.ts`: `[embed.loads]`, `[embed.unheard]` (the words before the document loads too, P145), `[embed.untold]`, `[embed.no-escape]`, `[embed.reader-unframeable]` | `embed-ancestors` → `[embed.reader-unframeable]`; `embed-handshake` → `[embed.untold]`; `embed-origins` → `[embed.unheard]` (all three) |
|
|
1015
1016
|
|
|
1016
1017
|
### The clipboard, and copy buttons
|
|
1017
1018
|
|
|
@@ -1624,6 +1625,9 @@ control the tables above name to the registry):
|
|
|
1624
1625
|
| `door-status` | `served/siblings-status.spec.ts` | `[sibling-inject]`, `[sibling-reload]`, `[proxy]` | — | WebKit: `[sibling-inject]`, `[sibling-reload]`, `[sibling-wipe]`, `[proxy]` may skip instead, measured (their attack lands only sometimes there) |
|
|
1625
1626
|
| `door-silence` | `served/siblings-status.spec.ts` | `[sibling-wipe]` | — | WebKit: `[sibling-inject]`, `[sibling-reload]`, `[sibling-wipe]`, `[proxy]` may skip instead, measured (their attack lands only sometimes there) |
|
|
1626
1627
|
| `door-opaque` | `served/siblings-status.spec.ts` | `[door-reach]` | — | — |
|
|
1628
|
+
| `embed-ancestors` | `served/embed.spec.ts` | `[embed.reader-unframeable]` | — | — |
|
|
1629
|
+
| `embed-handshake` | `served/embed.spec.ts` | `[embed.untold]` | — | — |
|
|
1630
|
+
| `embed-origins` | `served/embed.spec.ts` | `[embed.unheard]` | — | — |
|
|
1627
1631
|
| `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
|
|
1628
1632
|
| `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` | — | — |
|
|
1629
1633
|
| `shell-focus-held` | `served/nested.spec.ts` | `the host's move takes no keyboard from where the host's page went on to in the same task (P136)`, `a second host's move into a page it just handed the focus to leaves it there: no blur, and its field keeps the keyboard (P136)` | — | — |
|