@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.
@@ -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. */
@@ -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
- export const FRAME_SHELL_RUNTIME = String.raw `(() => {
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). Where
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.includes(origin)) {
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
- return FRAME_SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
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
- ...((options.framedBy ?? []).length === 0 ? {} : { strictParent: true }),
314
+ ...(strict ? { strictParent: true } : {}),
303
315
  page: page.href,
304
316
  sandbox: PAGE_SANDBOX_TOKENS.join(" "),
305
317
  ...(options.title === undefined ? {} : { title: options.title }),
@@ -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) there is no host to ask: `none()`
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,
@@ -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) there is no host to ask: `none()`
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. How it ended goes on the
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 single-document served artifact (no files, so no version in
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)` | — | — |
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.14.18 (2026-11-09). A review on 2026-10-19 found gaps, and every decision it led to
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.14.18",
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": {
@@ -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