@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.
- package/CHANGELOG.md +42 -5
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +2 -1
- package/dist/isolation/served.js +33 -2
- package/dist/server/host.d.ts +12 -4
- package/dist/server/host.js +5 -0
- package/docs/ADOPTING.md +9 -2
- package/docs/DECISIONS.md +111 -2
- package/docs/DESIGN.md +1 -1
- package/docs/THREAT_MODEL.md +30 -13
- package/package.json +1 -1
- package/src/isolation/served.ts +33 -2
- package/src/server/host.ts +21 -4
|
@@ -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.
|
|
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
|
/**
|
package/dist/isolation/served.js
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
/**
|
package/dist/server/host.d.ts
CHANGED
|
@@ -88,10 +88,14 @@ export interface ContentHostOptions<V> {
|
|
|
88
88
|
*/
|
|
89
89
|
readonly framedBy?: readonly string[];
|
|
90
90
|
/**
|
|
91
|
-
* Whether `
|
|
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.
|
|
94
|
-
*
|
|
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
|
-
/**
|
|
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>;
|
package/dist/server/host.js
CHANGED
|
@@ -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)
|
|
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]
|
|
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
|
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.15.
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
the
|
|
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
|
|
576
|
-
for byte, while an embed session of the same
|
|
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
|
-
|
|
612
|
-
|
|
613
|
-
page itself posts to its
|
|
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.
|
|
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": {
|
package/src/isolation/served.ts
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
|
package/src/server/host.ts
CHANGED
|
@@ -121,10 +121,14 @@ export interface ContentHostOptions<V> {
|
|
|
121
121
|
*/
|
|
122
122
|
readonly framedBy?: readonly string[];
|
|
123
123
|
/**
|
|
124
|
-
* Whether `
|
|
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.
|
|
127
|
-
*
|
|
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
|
-
/**
|
|
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(
|