@botiverse/porthole 0.15.0 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -39,7 +39,8 @@ export declare const includesOrigin: (origins: readonly string[], origin: string
39
39
  * ancestor of every frame the host shows, above the host's own page, and never a host origin. An
40
40
  * exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
41
41
  * loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
42
- * desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
42
+ * desktop scheme, `"null"`, a CSP keyword or a list. Its port, where it names one, is 1 to 65535
43
+ * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
43
44
  */
44
45
  export declare function framedByProblem(origin: unknown): string | null;
45
46
  /**
@@ -48,10 +48,37 @@ const HOST_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-
48
48
  export function isHostOrigin(origin) {
49
49
  return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
50
50
  }
51
+ /**
52
+ * Whether an origin that matched `HOST_ORIGIN` is one a browser can serialize as it is written
53
+ * (P145): a port, where it names one, is 1 to 65535 in plain decimal (never `:0`, `:99999` or
54
+ * `:0443`), and an `http`/`https` host is as the URL parser gives it back (never `0x7f.0.0.1` for
55
+ * `127.0.0.1`). A default port (`:443`) is still taken: browsers drop it, and `normalOrigin`
56
+ * compares it so (P144). Such an origin matches no frame and no message, so refusing it only says
57
+ * so early.
58
+ */
59
+ function serializable(origin) {
60
+ const port = /:(\d+)$/u.exec(origin)?.[1];
61
+ if (port !== undefined && !(/^[1-9]\d{0,4}$/u.test(port) && Number(port) <= 65_535)) {
62
+ return false;
63
+ }
64
+ const scheme = origin.slice(0, origin.indexOf(":"));
65
+ if (scheme !== "http" && scheme !== "https") {
66
+ return true;
67
+ }
68
+ try {
69
+ const url = new URL(origin);
70
+ return url.hostname === origin.slice(scheme.length + 3).replace(/:\d+$/u, "");
71
+ }
72
+ catch {
73
+ return false;
74
+ }
75
+ }
51
76
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
52
77
  export function hostOriginProblem(origin) {
53
78
  if (isHostOrigin(origin)) {
54
- return null;
79
+ return serializable(origin)
80
+ ? null
81
+ : `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
55
82
  }
56
83
  if (origin === "null") {
57
84
  return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
@@ -87,7 +114,8 @@ const LOOPBACK_HOST = (host) => host === "localhost" || host.endsWith(".localhos
87
114
  * ancestor of every frame the host shows, above the host's own page, and never a host origin. An
88
115
  * exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
89
116
  * loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
90
- * desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
117
+ * desktop scheme, `"null"`, a CSP keyword or a list. Its port, where it names one, is 1 to 65535
118
+ * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
91
119
  */
92
120
  export function framedByProblem(origin) {
93
121
  const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
@@ -95,6 +123,9 @@ export function framedByProblem(origin) {
95
123
  !(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))) {
96
124
  return `${JSON.stringify(origin)} is not an exact https origin (https://host[:port], lowercase, no path; http only on loopback)`;
97
125
  }
126
+ if (!serializable(origin)) {
127
+ return `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
128
+ }
98
129
  return null;
99
130
  }
100
131
  /**
@@ -88,10 +88,14 @@ export interface ContentHostOptions<V> {
88
88
  */
89
89
  readonly framedBy?: readonly string[];
90
90
  /**
91
- * Whether `access` may answer an embed grant (P143, `Grant.embed`): a public artifact page that
91
+ * Whether `server.issue` takes an embed grant (P143, `Grant.embed`): a public artifact page that
92
92
  * any site may frame, with no host (`ServerOptions.embeds`). Default false: an embed grant is
93
- * refused at issue. Only an embed session's answers say `frame-ancestors *`; every other answer
94
- * is as without it.
93
+ * refused at issue. Mint one from a route of your own that decides the page is public
94
+ * (`host.server.issue(instance, { anonymous: true, embed: true })`), never from `access`: `access`
95
+ * answers your readers (the issue endpoint, a clean address), and the kit refuses an `access`
96
+ * answer with `embed` (409 at the issue endpoint and a clean address's resolve; a clean address's
97
+ * tab gets its 409 page, as `enterBy` refuses it) (P145). Only an embed session's answers say
98
+ * `frame-ancestors *`; every other answer is as without it.
95
99
  */
96
100
  readonly embeds?: boolean;
97
101
  /** At least 32 random bytes (or a string of at least 32 bytes). */
@@ -128,7 +132,11 @@ export interface ContentHostOptions<V> {
128
132
  * version), check its fields, refuse the rest. The client never chooses an origin.
129
133
  */
130
134
  readonly instance: (proposal: InstanceRef, viewer: V | null, request: Request) => Awaitable<InstanceRef | null>;
131
- /** Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). */
135
+ /**
136
+ * Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). It
137
+ * answers readers, so never with `embed` (refused, P145): an embed grant is minted from a route
138
+ * of your own through `host.server.issue`.
139
+ */
132
140
  readonly access: (instance: InstanceRef, viewer: V | null, request: Request) => Awaitable<Grant | null>;
133
141
  /** Policy 3, on every request after (P050): may this cookie still see it. */
134
142
  readonly authorize?: (request: AuthorizeRequest) => Awaitable<AuthorizeAnswer>;
@@ -669,6 +669,11 @@ export function createContentHost(options) {
669
669
  };
670
670
  /** A location issued for what the host's access granted, with its clean address. */
671
671
  async function issuedFor(instance, grant, request, more = {}) {
672
+ // `access` answers readers, here and at a clean address: an embed grant (P143) is never
673
+ // theirs, whatever `embeds` says (P145). A host mints it from a route of its own.
674
+ if (grant.embed !== undefined) {
675
+ return refusal(409, "refused", "access never answers an embed grant: mint it from a route of your own with host.server.issue (P145)");
676
+ }
672
677
  let location;
673
678
  try {
674
679
  location = await server.issue(instance, grant, more.page === undefined ? undefined : { page: more.page });
package/docs/ADOPTING.md CHANGED
@@ -761,13 +761,20 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
761
761
  - **`embeds`** (P143): to let any site embed a public artifact page, set `embeds: true` and, from
762
762
  one route of your own that decides the page is public (never your reader's issue endpoint),
763
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
764
+ isn't nested): `host.server.issue(instance, { anonymous: true, embed: true })`. Never answer
765
+ `embed` from `access`: it answers your readers, and the kit refuses it there (409 from the issue
766
+ endpoint and a clean address's resolve, its 409 page at a clean address's tab; P145). That
767
+ session's answers say `frame-ancestors *`, and nothing else's do. It has no
765
768
  host: frame it from an outer page of your own that listens to nothing (its `frame-src` the one
766
769
  label), which any site may frame; the shell asks no host and says nothing to any parent, links out
767
770
  of the page go nowhere (give the outer page your own "Open" link), and there is no door.
768
771
  `authorize.check` gets `embed: true` for it, so your check can hold an embed subject to embed
769
772
  sessions. A content Worker of your own answers its refusals before a session exists with
770
- `statusPage({ embed: true, … })` or `doorStatusResponse({ embed: true, … })`.
773
+ `statusPage({ embed: true, … })` or `doorStatusResponse({ embed: true, … })`. The page learns
774
+ where it is embedded: its request's `Referer` and `document.referrer` name your outer page, and
775
+ `location.ancestorOrigins` names every ancestor, the embedding site included (Chromium, Firefox
776
+ and WebKit), so a page with any egress can report where it is shown
777
+ ([THREAT_MODEL.md S4](THREAT_MODEL.md#s4-public-links-and-pages-that-are-apps)).
771
778
  - **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
772
779
  `""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
773
780
  `{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
package/docs/DECISIONS.md CHANGED
@@ -8863,7 +8863,7 @@ cases, whose second page is opened by a link.
8863
8863
  (the `same` notice then has no load to explain), single-document served artifacts need it (give
8864
8864
  their notices the version), or hosts need Safari before 26 on a tab (P099's limit stands).
8865
8865
 
8866
- ## P143 · 2026-11-10 · An embedded document: a public grant with no host, framed by any page (`embed`) · Accepted
8866
+ ## P143 · 2026-11-10 · An embedded document: a public grant with no host, framed by any page (`embed`) · Accepted; amended by P145
8867
8867
 
8868
8868
  From Raft (Tenny): public artifacts embedded on any site, as a video is. The host's own outer page
8869
8869
  (its code, no author code, and no host: it hears and tells nothing) frames the content frame, and
@@ -8975,7 +8975,7 @@ plan) fails `[embed.unheard]`; each exactly that probe on Chromium.
8975
8975
  its own entry), auto-height needs a word to the embedding site, or browsers give a policy for the
8976
8976
  parent alone.
8977
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
8978
+ ## P144 · 2026-11-10 · After the audit of 0.14.17 and 0.14.18: `framedBy`'s default path byte for byte, the nesting it is for, origins compared as browsers serialize them · Accepted; amended by P145
8979
8979
 
8980
8980
  Amends P141 (its decision 1's "byte for byte", its decision 3 and its "What it re-opens"). From
8981
8981
  Ferryman's audit of 0.14.17 (P141) and 0.14.18 (P142): no P0 and no new egress; four findings, all
@@ -9048,3 +9048,112 @@ the nested shell pass unchanged on Chromium.
9048
9048
 
9049
9049
  **Revisit when** a host needs a strict page's script at the old address, or browsers give a policy
9050
9050
  for the parent alone.
9051
+
9052
+ ## P145 · 2026-11-10 · After the audit of 0.15.0: "byte for byte" said as it holds, embeds never from `access`, what an embed page learns, origins' ports · Accepted
9053
+
9054
+ Amends P143 (its decision 3's "as before, byte for byte", and its host duties) and P144 (its
9055
+ decision 1's "every response is 0.14.16's again", and its decision 3's "P141's exact forms"). From
9056
+ Ferryman's audit of 0.15.0 (P143, P144): no P0, no escape, no new egress, and no way found for an
9057
+ embed session's `*` to reach another session; one P1 (by the rule that any default-path byte change
9058
+ is at least P1; P3 on its own) and three P3s, all fixed here.
9059
+
9060
+ **Context.**
9061
+ 1. *(P1 by rule, P3 on its own) "Byte for byte".* P144 #1 ended "without `framedBy` every response
9062
+ is 0.14.16's again, byte for byte"; 0.15.0's CHANGELOG said "the default path is 0.14.16's
9063
+ again", and P143 #3 and its CHANGELOG line "every other session's answers are as before, byte
9064
+ for byte". Every header held (every CSP, `frame-ancestors`, `script-src` hash, cookie and cache
9065
+ header) and so did the four scripts P144 pinned. The bodies of the documents that inline the
9066
+ shell runtime did not: a served shell, an artifact page, a file set's pages, the MCP Apps proxy
9067
+ and the nested page carry P142's changes (0.14.18) and P143's `hostless` branches (0.15.0). Those
9068
+ branches are inert where a plan names a host (`createServer` refuses empty `hostOrigins`), and no
9069
+ hash covers the runtime (`'unsafe-inline'`), so nothing a browser does changed; the claim did.
9070
+ P143's bound test compares with a 0.15.0 server without `embeds`, which carries the same runtime,
9071
+ so it could not see this.
9072
+ 2. *(P3) The kit's `embeds` said "whether `access` may answer an embed grant".* `access` answers
9073
+ the kit's reader issue endpoint and a clean address's resolve, which ADOPTING and THREAT_MODEL
9074
+ say must never mint `embed`, and the kit's test minted it there. A host that followed the kit's
9075
+ doc made signed-out readers' frames hostless and frameable by any site (nothing signed-in rode
9076
+ along: `checkGrant` refuses a viewer, level or user with `embed`).
9077
+ 3. *(P3) An embed page learns where it is embedded*, which P143 didn't say beside "the embedding
9078
+ site sees the page load".
9079
+ 4. *(P3) Ports.* `framedByProblem` (and `hostOriginProblem`) took `:0`, `:99999` and `:0443`, and a
9080
+ host the URL parser rewrites (`https://0x7f.0.0.1` is `https://127.0.0.1`). Each failed closed (a
9081
+ source that matches nothing, or a stricter page), but P144 said inputs are held to exact forms.
9082
+ 5. *(P3) A control's probe failed at an unmarked step.* Under `embed-origins`, `[embed.unheard]`
9083
+ once failed at "the embedded page shows" instead of its verdict (Chromium, a loaded box), so the
9084
+ runner counted it as not failing by its probe. The cause: the shell draws one document
9085
+ (`render` runs once), and the hostile outer page says a document every 100 ms. A weakened shell
9086
+ that hears that word before its own document has loaded draws the word instead of the page
9087
+ (`#taken`, no `#content`), and the step before the verdict waited 5 s for `#content`. Reproduced
9088
+ on Chromium and Firefox by delivering the document in two parts: both failed "unmarked: Error:
9089
+ the embedded page shows".
9090
+
9091
+ **Decision.**
9092
+ 1. **Said as it holds.** Without `framedBy` and an embed, every header and the status, entry and
9093
+ door pages' scripts and the nested page's shell are 0.14.16's, byte for byte; the shell runtime
9094
+ that served documents inline is 0.15.0's: P142's changes and P143's `hostless` branches, inert
9095
+ where a plan names a host. Every other session's answers are, byte for byte, what the same server
9096
+ without `embeds` answers. THREAT_MODEL's status line, S4 and 0.15.0's CHANGELOG lines say so.
9097
+ The runtime is not moved again: splicing `hostless` into embed documents alone (as P144 did for
9098
+ `strict`) would make the claim true against 0.14.18 only, not 0.14.16, for a third runtime
9099
+ variant. Instead **its bytes are pinned** (`SHELL_RUNTIME`, `ANNOTATE_RUNTIME`, `FIND_RUNTIME`,
9100
+ `USE_RUNTIME`, `LEGACY_GLOBALS_RUNTIME` by sha256): a change to them fails a test, so the next
9101
+ release says it rather than asserting it away.
9102
+ 2. **Embeds never from `access`.** The host kit refuses an `access` answer that carries `embed`,
9103
+ whatever `embeds` says: 409 `refused` from its issue endpoint and a clean address's resolve, and
9104
+ a clean address's tab gets the kit's 409 page (`enterBy` refuses it, as before). A host mints an
9105
+ embed session from a route of its own with `host.server.issue(instance, { anonymous: true,
9106
+ embed: true })`, which needs `embeds: true`. `ContentHostOptions.embeds` and `access` say so.
9107
+ 3. **What an embed page learns, said** (THREAT_MODEL S4, ADOPTING `embeds`). Measured in Chromium,
9108
+ Firefox (155) and WebKit: the content document's request carries the outer page's address as
9109
+ `Referer` (its origin, under the default referrer policy; Firefox 155 also sends it as `Origin`, Chromium
9110
+ and WebKit send no `Origin`; Ferryman's recheck of #129),
9111
+ `document.referrer` is the same, and `location.ancestorOrigins` lists the outer page and the
9112
+ embedding site. A page with any egress can send that out. Porthole's served documents send no
9113
+ `Referer` of their own (`no-referrer`), which doesn't hide what the page reads.
9114
+ 4. **A port is 1 to 65535, in plain decimal; an `http`/`https` host is as the URL parser gives
9115
+ it.** `hostOriginProblem` and `framedByProblem` refuse `:0`, `:00`, `:65536`, `:99999`, `:0443`,
9116
+ and a host like `0x7f.0.0.1`, `0177.0.0.1` or `127.1`; so `createServer`, the host kit and every
9117
+ helper that takes host origins or `framedBy` throw on them. A default port (`:443`) is still
9118
+ taken: browsers drop it and P144 compares it so; refusing it in a patch release would break a
9119
+ working config.
9120
+ 5. **The probe judges, not the step before it.** `[embed.unheard]` waits for the page to have
9121
+ loaded, its own `#content` or a word's `#taken`, and leaves which one to its verdict. Its
9122
+ documents now arrive in two parts (the shell's script, then the rest 1.5 s later), so the words
9123
+ reach the shell before its document loads every time, not only on a loaded box: the probe covers
9124
+ the early words too, and `embed-origins` fails it with the page taken over (`taken: true`,
9125
+ `content: false`), on every engine.
9126
+
9127
+ **Rejected.**
9128
+ - *Requiring `new URL(origin).origin === origin`* (the audit's suggestion): it refuses `:443` too,
9129
+ which 0.15.0 takes for host origins and `framedBy` alike (P144's tests); a patch should not break
9130
+ a working config. The rule above refuses everything else it would.
9131
+ - *The kit dropping `embed` from an `access` answer and issuing a public session*: a host that
9132
+ meant an embed would get a reader's frame without a word; a refusal says it.
9133
+ - *Running `embed.spec` on Firefox and WebKit through a workflow change*: CI's `loopback` job runs
9134
+ every spec (`testMatch: **/*.spec.ts`) on `chromium`, `chromium-oopif`, `webkit` and `firefox`,
9135
+ and `controls-shard` runs every control on `chromium`, `webkit` and `firefox`; 0.15.0's CI ran
9136
+ `embed.spec` on all three. Only P143's local run was Chromium alone.
9137
+
9138
+ **Tested.** `test/framed-by.test.ts`: the served shell runtime's five parts pinned to 0.15.0's
9139
+ sha256, three of them shown not 0.14.16's (and `use`, `legacy` the same), and on a server without
9140
+ `framedBy` or `embeds` an artifact page carries the `hostless` line with a plan naming its host
9141
+ origins; Ferryman's edges probe: thirteen origins (`:0`, `:00`, `:65536`, `:99999`, `:0443`,
9142
+ `:08443`, a host origin with `:0443`, `http://localhost:0`, `http://127.0.0.1:65536`,
9143
+ `0x7f.0.0.1`, `0177.0.0.1`, `127.1`, `203.0.113.07`) refused by `createServer`, the host kit,
9144
+ `statusPage`, `doorResponse`, `doorStatusResponse`, `nestedShellCsp` and `frameShellScript`; the
9145
+ audit's refused forms (a host origin with or without `:443`, a trailing dot, userinfo, Unicode, case,
9146
+ a path, `http:` off loopback, `ferry://App`) still refused; ports 1, 8443, 65535, a default port, an
9147
+ IPv4 address and loopback http taken; a host origin's port held the same; `embeds: "true"` throws.
9148
+ `test/origins.test.ts`: `hostOriginProblem` on the same ports and hosts, custom schemes included.
9149
+ `test/embed.test.ts`: the kit refuses `access` answering `embed` at its issue endpoint, a clean
9150
+ address's resolve (409 `refused`) and its tab (409, no redirect), with `embeds` absent, false and
9151
+ true, and issues a public grant from the same routes; `host.server.issue` mints the embed only with
9152
+ `embeds: true`. Taking the kit's check out fails the refusal test. `leak/served/embed.spec.ts`
9153
+ passes on Chromium, Firefox and WebKit, and `embed-ancestors`, `embed-handshake` and `embed-origins`
9154
+ each fail exactly their probe on all three. The old spec with its document in two parts failed
9155
+ `embed-origins` unmarked on Chromium and Firefox; this one fails it by the probe.
9156
+
9157
+ **Revisit when** the runtime pin changes (say what changed), a host needs `embed` from a reader's
9158
+ route (then it needs its own entry, never `access`), or a browser stops exposing
9159
+ `ancestorOrigins` to a framed page.
package/docs/DESIGN.md CHANGED
@@ -1012,7 +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
+ | An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page that isn't nested; signed into the session as `m` and into the sealed address) → `frame-ancestors *` for that session's answers alone (its document, a file set's pages and files and own frames, assets, renewals, its status and ended-access pages); an embed session's cookie has a name of its own (`e-<key>`) and never stands in for another session; the plan names no host (`origins: []`): the shell asks no host, ends its handshake at once (`"none"`), says nothing to any parent (no `*` notices, no annotation or find report) and hears no one; no door; `statusPage` and `doorStatusResponse` take `embed` (`*`, `data-porthole-hosts="[]"`); the host kit refuses an `access` answer with `embed` (P145: minted through `host.server.issue` alone) | `test/embed.test.ts` (refused without `embeds`, with a viewer, a level or a user, for url mode, a nested display, a served shell or the proxy, at a clean address and at the door; the host kit refuses it from `access` at its issue endpoint, a clean address's resolve and its tab, with `embeds` or without; the flag can't be added or stripped, nor a session moved to the other name; **the bound**: 23 kinds of answer under an embed session say `*` and name no host, and the same under a public and a viewer's session are byte for byte what a server without `embeds` answers, on the same server while an embed session of the same artifact exists, and with both cookies sent; the host's check is told `embed`; cookies host-only, never `Domain=`); `test/shell.test.ts` (P143's handshake); `leak/served/embed.spec.ts`: `[embed.loads]`, `[embed.unheard]` (the words before the document loads too, P145), `[embed.untold]`, `[embed.no-escape]`, `[embed.reader-unframeable]` | `embed-ancestors` → `[embed.reader-unframeable]`; `embed-handshake` → `[embed.untold]`; `embed-origins` → `[embed.unheard]` (all three) |
1016
1016
 
1017
1017
  ### The clipboard, and copy buttons
1018
1018
 
@@ -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.15.0 (2026-11-10). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.15.1 (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
@@ -55,12 +55,20 @@ lets a host that opts in (`embeds`) mint an embed grant: a public artifact page'
55
55
  `frame-ancestors *` for that session alone, and the page has no host: it hears no one, tells no
56
56
  parent anything, and no capability, runtime host function or door is there (S4, §8). P144, after
57
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`).
58
+ every header (every `frame-ancestors` and `script-src` hash) and the status, entry and door pages'
59
+ scripts and the nested page's shell are 0.14.16's again, byte for byte (0.14.17 had changed their
60
+ hashes, not what they do); the shell runtime every served document inlines is not (P142's
61
+ changes, and P143's `hostless` branches, inert where a plan names a host; no hash covers it: P145);
62
+ in the nesting P141 is for (the outer page, then the app's page, then content), content can message
63
+ the outer page and every frame in its tree and learn its origin, so the outer page must check every
64
+ message it takes, and S7's egress rule covers its frames (§6 "What every host must do", S7); and
65
+ `framedBy` is compared with the host origins as browsers serialize origins (`https://a.example:443`
66
+ is `https://a.example`).
67
+ 0.15.1: P145, after Ferryman's audit of 0.15.0 (no P0, no escape, no new egress), amends P143 and
68
+ P144: their "byte for byte" is said as it holds (above); the host kit refuses an `access` answer
69
+ with `embed`, so a reader's issue endpoint never mints an embed session (S4); an embed page learns
70
+ where it is embedded (S4); and a host origin's or `framedBy`'s port is 1 to 65535, without a
71
+ leading zero, and its host as the URL parser gives it. No wall moves.
64
72
 
65
73
  ## 1. Two layers
66
74
 
@@ -572,8 +580,10 @@ the attacker (c), and its readers are strangers.
572
580
  `frame-ancestors *` for that session alone, never a reader's; it is anonymous, with no level or
573
581
  user, an artifact's page that isn't nested; its plan names no host, so it hears no one, Porthole
574
582
  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.
583
+ flag is signed into the session and the sealed address. Every other session's answers are, byte
584
+ for byte, what the same server without `embeds` answers, while an embed session of the same
585
+ artifact exists; cookies stay host-only. The host kit never mints one from `access` (its reader's
586
+ issue endpoint and clean addresses refuse an `embed` answer, P145).
577
587
  - A page opened in a tab of its own has its frame's powers and no more (P099): its CSP header
578
588
  carries the frame's sandbox (scripts on its own origin; no popups, forms, downloads, browser
579
589
  dialogs, or navigation of another window, its opener's included), and its `Permissions-Policy`
@@ -607,10 +617,17 @@ the attacker (c), and its readers are strangers.
607
617
  - Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
608
618
  - Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
609
619
  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.
620
+ - For embeds (P143): mint `embed` from one route of yours alone (never a reader's ticket or door;
621
+ with the host kit, `host.server.issue`, never `access`, which it refuses, P145), keep that route
622
+ from widening grants, and blank a takedown within a bound you state (your `authorize` answers,
623
+ cached or not). The embedding site sees the page load and hears what the page itself posts to its
624
+ parent or top. The page learns where it is embedded (P145, measured in Chromium, Firefox and
625
+ WebKit): its document's request carries your outer page's address as `Referer` (its origin, under
626
+ the default referrer policy; Firefox also sends it as `Origin`, Chromium and WebKit don't),
627
+ `document.referrer` says the same,
628
+ and `location.ancestorOrigins` names every ancestor, the embedding site's origin included. A page
629
+ with any egress (a `connect-src`, an image source) can send that out; one with none can't. Treat
630
+ where an embed is shown as known to its author.
614
631
  - Treat a public link's clean address as a tab's (P125): to show what one names in a frame, resolve
615
632
  it through your issue endpoint (`client.resolve`, `<PortholeView address>`). Its refusals (signed
616
633
  out, denied, not found) are your backend's word, drawn as the fallback with no frame built: keep
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.15.0",
3
+ "version": "0.15.1",
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": {
@@ -67,10 +67,37 @@ export function isHostOrigin(origin: unknown): origin is string {
67
67
  return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
68
68
  }
69
69
 
70
+ /**
71
+ * Whether an origin that matched `HOST_ORIGIN` is one a browser can serialize as it is written
72
+ * (P145): a port, where it names one, is 1 to 65535 in plain decimal (never `:0`, `:99999` or
73
+ * `:0443`), and an `http`/`https` host is as the URL parser gives it back (never `0x7f.0.0.1` for
74
+ * `127.0.0.1`). A default port (`:443`) is still taken: browsers drop it, and `normalOrigin`
75
+ * compares it so (P144). Such an origin matches no frame and no message, so refusing it only says
76
+ * so early.
77
+ */
78
+ function serializable(origin: string): boolean {
79
+ const port = /:(\d+)$/u.exec(origin)?.[1];
80
+ if (port !== undefined && !(/^[1-9]\d{0,4}$/u.test(port) && Number(port) <= 65_535)) {
81
+ return false;
82
+ }
83
+ const scheme = origin.slice(0, origin.indexOf(":"));
84
+ if (scheme !== "http" && scheme !== "https") {
85
+ return true;
86
+ }
87
+ try {
88
+ const url = new URL(origin);
89
+ return url.hostname === origin.slice(scheme.length + 3).replace(/:\d+$/u, "");
90
+ } catch {
91
+ return false;
92
+ }
93
+ }
94
+
70
95
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
71
96
  export function hostOriginProblem(origin: unknown): string | null {
72
97
  if (isHostOrigin(origin)) {
73
- return null;
98
+ return serializable(origin)
99
+ ? null
100
+ : `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
74
101
  }
75
102
  if (origin === "null") {
76
103
  return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
@@ -111,7 +138,8 @@ const LOOPBACK_HOST = (host: string): boolean =>
111
138
  * ancestor of every frame the host shows, above the host's own page, and never a host origin. An
112
139
  * exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
113
140
  * loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
114
- * desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
141
+ * desktop scheme, `"null"`, a CSP keyword or a list. Its port, where it names one, is 1 to 65535
142
+ * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
115
143
  */
116
144
  export function framedByProblem(origin: unknown): string | null {
117
145
  const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
@@ -121,6 +149,9 @@ export function framedByProblem(origin: unknown): string | null {
121
149
  ) {
122
150
  return `${JSON.stringify(origin)} is not an exact https origin (https://host[:port], lowercase, no path; http only on loopback)`;
123
151
  }
152
+ if (!serializable(origin as string)) {
153
+ return `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
154
+ }
124
155
  return null;
125
156
  }
126
157
 
@@ -121,10 +121,14 @@ export interface ContentHostOptions<V> {
121
121
  */
122
122
  readonly framedBy?: readonly string[];
123
123
  /**
124
- * Whether `access` may answer an embed grant (P143, `Grant.embed`): a public artifact page that
124
+ * Whether `server.issue` takes an embed grant (P143, `Grant.embed`): a public artifact page that
125
125
  * any site may frame, with no host (`ServerOptions.embeds`). Default false: an embed grant is
126
- * refused at issue. Only an embed session's answers say `frame-ancestors *`; every other answer
127
- * is as without it.
126
+ * refused at issue. Mint one from a route of your own that decides the page is public
127
+ * (`host.server.issue(instance, { anonymous: true, embed: true })`), never from `access`: `access`
128
+ * answers your readers (the issue endpoint, a clean address), and the kit refuses an `access`
129
+ * answer with `embed` (409 at the issue endpoint and a clean address's resolve; a clean address's
130
+ * tab gets its 409 page, as `enterBy` refuses it) (P145). Only an embed session's answers say
131
+ * `frame-ancestors *`; every other answer is as without it.
128
132
  */
129
133
  readonly embeds?: boolean;
130
134
  /** At least 32 random bytes (or a string of at least 32 bytes). */
@@ -167,7 +171,11 @@ export interface ContentHostOptions<V> {
167
171
  viewer: V | null,
168
172
  request: Request,
169
173
  ) => Awaitable<InstanceRef | null>;
170
- /** Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). */
174
+ /**
175
+ * Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). It
176
+ * answers readers, so never with `embed` (refused, P145): an embed grant is minted from a route
177
+ * of your own through `host.server.issue`.
178
+ */
171
179
  readonly access: (
172
180
  instance: InstanceRef,
173
181
  viewer: V | null,
@@ -1129,6 +1137,15 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1129
1137
  request: Request,
1130
1138
  more: { readonly page?: string; readonly resolved?: boolean } = {},
1131
1139
  ): Promise<Response> {
1140
+ // `access` answers readers, here and at a clean address: an embed grant (P143) is never
1141
+ // theirs, whatever `embeds` says (P145). A host mints it from a route of its own.
1142
+ if ((grant as { readonly embed?: unknown }).embed !== undefined) {
1143
+ return refusal(
1144
+ 409,
1145
+ "refused",
1146
+ "access never answers an embed grant: mint it from a route of your own with host.server.issue (P145)",
1147
+ );
1148
+ }
1132
1149
  let location: FrameLocation;
1133
1150
  try {
1134
1151
  location = await server!.issue(