@botiverse/porthole 0.14.18 → 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 +45 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +9 -0
- package/dist/isolation/served.js +23 -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 +12 -6
- package/docs/ADOPTING.md +18 -4
- package/docs/DECISIONS.md +191 -2
- package/docs/DESIGN.md +4 -0
- package/docs/THREAT_MODEL.md +35 -2
- package/package.json +1 -1
- package/src/isolation/served.ts +25 -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 +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,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
|
@@ -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,189 @@ 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
|
|
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.
|
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="[]"`) | `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 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]`, `[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)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.
|
|
8
|
+
**Status.** This describes Porthole 0.15.0 (2026-11-10). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -50,7 +50,17 @@ host a frame hears or tells, and a page's `*` fallback is held to a parent named
|
|
|
50
50
|
(§6 "What every host must do", S3). 0.14.18: P142 keeps a set's pages and links within a page from
|
|
51
51
|
starting the display again where there is no Navigation API, and where WebKit fires a frame's load
|
|
52
52
|
for a link within its document: the arriving page's notice is sent without the API, and a page
|
|
53
|
-
says it stayed; no wall moves, and the limit without the API is P079's, unchanged.
|
|
53
|
+
says it stayed; no wall moves, and the limit without the API is P079's, unchanged. 0.15.0: P143
|
|
54
|
+
lets a host that opts in (`embeds`) mint an embed grant: a public artifact page's answers say
|
|
55
|
+
`frame-ancestors *` for that session alone, and the page has no host: it hears no one, tells no
|
|
56
|
+
parent anything, and no capability, runtime host function or door is there (S4, §8). P144, after
|
|
57
|
+
Ferryman's audit of 0.14.17 and 0.14.18 (no P0, no new egress), amends P141: without `framedBy`
|
|
58
|
+
the status, entry and door pages' scripts and the nested page's shell are 0.14.16's again, byte for
|
|
59
|
+
byte (0.14.17 had changed their hashes, not what they do); in the nesting P141 is for (the outer
|
|
60
|
+
page, then the app's page, then content), content can message the outer page and every frame in
|
|
61
|
+
its tree and learn its origin, so the outer page must check every message it takes, and S7's
|
|
62
|
+
egress rule covers its frames (§6 "What every host must do", S7); and `framedBy` is compared with
|
|
63
|
+
the host origins as browsers serialize origins (`https://a.example:443` is `https://a.example`).
|
|
54
64
|
|
|
55
65
|
## 1. Two layers
|
|
56
66
|
|
|
@@ -283,6 +293,14 @@ Whatever the use:
|
|
|
283
293
|
can hear is the content's own word to its parent (`*`), which it must treat as untrusted. Your
|
|
284
294
|
app page's own `frame-ancestors` is yours to set; Porthole never sends it. Name exact origins of
|
|
285
295
|
that one product, and drop them when it stops framing you.
|
|
296
|
+
- In the nesting `framedBy` is for (the outer page, then your app's page, then content), content
|
|
297
|
+
is a descendant of the outer page (P144): it can `postMessage` the outer page (`top`) and every
|
|
298
|
+
frame in its tree, and learn the outer page's origin (measured in Chromium and Firefox). No
|
|
299
|
+
header stops that. Tell the outer page's authors: every message listener on the outer page and in
|
|
300
|
+
each of its frames must check `event.source` and `event.origin`, taking a message only from the
|
|
301
|
+
window and origin it expects (your app's page), and treat any other as content's untrusted word.
|
|
302
|
+
S7's rule now covers the outer page's frames: what content was given can be handed to any frame
|
|
303
|
+
the outer page shows, so the widest network among them is content's way out.
|
|
286
304
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
287
305
|
|
|
288
306
|
### S1. Inline widgets in a conversation
|
|
@@ -550,6 +568,12 @@ the attacker (c), and its readers are strangers.
|
|
|
550
568
|
so it is never punycode for another name; pages say `noindex`; a file of a type Porthole
|
|
551
569
|
doesn't know is served as a download.
|
|
552
570
|
- `authorize` is the host's takedown switch.
|
|
571
|
+
- An embedded document (P143, `Grant.embed`, only where the host set `embeds`): its answers say
|
|
572
|
+
`frame-ancestors *` for that session alone, never a reader's; it is anonymous, with no level or
|
|
573
|
+
user, an artifact's page that isn't nested; its plan names no host, so it hears no one, Porthole
|
|
574
|
+
tells no parent anything, no capability or runtime host function runs, and no door is minted. The
|
|
575
|
+
flag is signed into the session and the sealed address. Every other session is unchanged, byte
|
|
576
|
+
for byte, while an embed session of the same artifact exists; cookies stay host-only.
|
|
553
577
|
- A page opened in a tab of its own has its frame's powers and no more (P099): its CSP header
|
|
554
578
|
carries the frame's sandbox (scripts on its own origin; no popups, forms, downloads, browser
|
|
555
579
|
dialogs, or navigation of another window, its opener's included), and its `Permissions-Policy`
|
|
@@ -583,6 +607,10 @@ the attacker (c), and its readers are strangers.
|
|
|
583
607
|
- Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
|
|
584
608
|
- Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
|
|
585
609
|
through any edge or proxy: on a tab they are the page's sandbox.
|
|
610
|
+
- For embeds (P143): mint `embed` from one route of yours alone (never a reader's ticket or door),
|
|
611
|
+
keep that route from widening grants, and blank a takedown within a bound you state (your
|
|
612
|
+
`authorize` answers, cached or not). The embedding site sees the page load and hears what the
|
|
613
|
+
page itself posts to its parent or top.
|
|
586
614
|
- Treat a public link's clean address as a tab's (P125): to show what one names in a frame, resolve
|
|
587
615
|
it through your issue endpoint (`client.resolve`, `<PortholeView address>`). Its refusals (signed
|
|
588
616
|
out, denied, not found) are your backend's word, drawn as the fallback with no frame built: keep
|
|
@@ -724,6 +752,10 @@ can be handed to the display with the widest network.
|
|
|
724
752
|
|
|
725
753
|
- Porthole doesn't enforce this: `defineDisplays` takes any kinds together, and
|
|
726
754
|
`frameSources` is the union of all of theirs. Group displays by page yourself.
|
|
755
|
+
- Where another app frames yours (`framedBy`, P141, P144), the page is the outer page's, and its
|
|
756
|
+
frames are in the union too: content can post to the outer page and to every frame in its tree.
|
|
757
|
+
The outer page's own frames, and their network, are its authors' to group, and its listeners must
|
|
758
|
+
check `event.source` and `event.origin` (§6 "What every host must do").
|
|
727
759
|
- An opaque frame also inherits the page's own CSP, so a strict page narrows its opaque frames
|
|
728
760
|
further (P058). A served frame has only its own policy.
|
|
729
761
|
|
|
@@ -1282,6 +1314,7 @@ found P124 held only for a nested display or one alone in its scope; in 0.14.6:
|
|
|
1282
1314
|
| P101 | Merged | Under https Porthole read unprefixed `porthole-*` cookies a sibling label can plant; the entered mark carried no label; url mode checked neither `Origin` nor `Sec-Fetch-Site`. Now only `__Host-` names are read, the mark names its label, and a url-mode app answers its own origin and navigations. | S3, S6 |
|
|
1283
1315
|
| P102 | Merged | This document. | |
|
|
1284
1316
|
| P103 | Merged | A live widget's capabilities could add origins; bearer-mode assets skipped the code re-check; `callTool` had no rate. Now the preset refuses them and its config is frozen, every load asks the current config (its ETag says which answer), and `callTool` has 30 a minute. | S2, S5, §7 |
|
|
1317
|
+
| P143 | Merged (0.15.0) | Embeds: a public grant's documents framed by any page (`frame-ancestors *`) only for a session the host minted with `embed`, never a reader's. Such a frame has no host: it hears no one, Porthole tells no parent anything, no capability or runtime host function runs, no door. Accepted: the embedding site sees the page load and hears what the page itself posts to its parent or top. The host must keep its embed entry from widening grants, and blank takedowns within its stated bound. | S4 |
|
|
1285
1318
|
|
|
1286
1319
|
Open with no decision yet; until then they are the host's to cover:
|
|
1287
1320
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.0",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/isolation/served.ts
CHANGED
|
@@ -78,6 +78,31 @@ export function hostOriginProblem(origin: unknown): string | null {
|
|
|
78
78
|
return `${JSON.stringify(origin)} is not an exact origin (scheme://host[:port], lowercase, no path)`;
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
+
/**
|
|
82
|
+
* An origin as a browser serializes it, for comparing two (P144):
|
|
83
|
+
* scheme and host lowercase, and for `http`/`https` a default port dropped, so
|
|
84
|
+
* `https://app.example:443` is `https://app.example`. Any other scheme's origin (a desktop app's) is
|
|
85
|
+
* only lowercased.
|
|
86
|
+
*/
|
|
87
|
+
export function normalOrigin(origin: string): string {
|
|
88
|
+
const lower = origin.toLowerCase();
|
|
89
|
+
if (lower.startsWith("https://") || lower.startsWith("http://")) {
|
|
90
|
+
try {
|
|
91
|
+
const serialized = new URL(lower).origin;
|
|
92
|
+
if (serialized !== "null") {
|
|
93
|
+
return serialized;
|
|
94
|
+
}
|
|
95
|
+
} catch {
|
|
96
|
+
// Not a URL: compared as it is, lowercase.
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
return lower;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Whether `origin` is one of `origins`, compared as browsers serialize them (`normalOrigin`). */
|
|
103
|
+
export const includesOrigin = (origins: readonly string[], origin: string): boolean =>
|
|
104
|
+
origins.some((each) => normalOrigin(each) === normalOrigin(origin));
|
|
105
|
+
|
|
81
106
|
const LOOPBACK_HOST = (host: string): boolean =>
|
|
82
107
|
host === "localhost" || host.endsWith(".localhost") || host === "127.0.0.1" || host === "[::1]";
|
|
83
108
|
|