@botiverse/porthole 0.14.6 → 0.14.7
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 +13 -0
- package/dist/conformance/served.js +18 -10
- package/dist/server/index.js +2 -1
- package/dist/server/server.js +85 -36
- package/dist/server/types.d.ts +23 -0
- package/docs/ADOPTING.md +16 -0
- package/docs/DECISIONS.md +47 -0
- package/docs/THREAT_MODEL.md +1 -1
- package/package.json +1 -1
- package/src/conformance/served.ts +19 -10
- package/src/server/index.ts +2 -1
- package/src/server/server.ts +112 -45
- package/src/server/types.ts +25 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,19 @@
|
|
|
4
4
|
section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
|
|
5
5
|
P-numbers below.
|
|
6
6
|
|
|
7
|
+
## 0.14.7
|
|
8
|
+
|
|
9
|
+
- **`server.doorAnswer(instance, grant, request?, at?)` (P126):** the door's answer for a grant a
|
|
10
|
+
host admitted itself, for a host that signs its own tickets and verifies them in its content
|
|
11
|
+
Worker. It returns exactly what `/__porthole/door/<key>` answers after taking its ticket (the same
|
|
12
|
+
`authorize`, document, entry and page checks; `doorResponse` or `doorStatusResponse`, the door's
|
|
13
|
+
CSP, no cookie) and never takes a ticket: call it only for a request you authenticated, with the
|
|
14
|
+
grant you established. `serveDoor` now answers through it, so the two can't drift.
|
|
15
|
+
- **Conformance (P126):** `served.domain.door`'s check (4) swaps the `ticket` parameters between a
|
|
16
|
+
location's own content and door URLs instead of building `/__porthole/d/<key>` from the door
|
|
17
|
+
path, so a host whose door path ends otherwise (`/__porthole/door/_raft`) is judged by its own
|
|
18
|
+
URLs.
|
|
19
|
+
|
|
7
20
|
## 0.14.6
|
|
8
21
|
|
|
9
22
|
- **Every display ends with an outcome (P125):** a frame started again until its restarts ran out
|
|
@@ -1005,18 +1005,26 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1005
1005
|
const again = await page.request.get(door.href, { failOnStatusCode: false });
|
|
1006
1006
|
expect(again.status(), "probe: a used door ticket is 401 session").toBe(401);
|
|
1007
1007
|
// (4) The door ticket at the content route, and the content ticket at the door, open
|
|
1008
|
-
// nothing
|
|
1008
|
+
// nothing: the two tickets of one issue are not interchangeable. Each is swapped into the
|
|
1009
|
+
// other's own URL, each path kept as the host gave it (a host's door path need not end in
|
|
1010
|
+
// its content's key, P126); (6) a fresh door framed from a foreign origin hears nothing
|
|
1011
|
+
// (frame-ancestors).
|
|
1009
1012
|
const fresh = await host.locate(await host.shell("door-cross"));
|
|
1010
|
-
const
|
|
1011
|
-
const
|
|
1012
|
-
const
|
|
1013
|
-
const
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1013
|
+
const doorTicketAtContent = new URL(fresh.url);
|
|
1014
|
+
const contentTicketAtDoor = new URL(doorOf(fresh));
|
|
1015
|
+
const doorTicket = contentTicketAtDoor.searchParams.get("ticket");
|
|
1016
|
+
const contentTicket = doorTicketAtContent.searchParams.get("ticket");
|
|
1017
|
+
if (doorTicket === null || contentTicket === null) {
|
|
1018
|
+
info?.annotations.push({
|
|
1019
|
+
type: "measured",
|
|
1020
|
+
description: "the location's content or door URL carries no ticket query parameter: the swap presents none",
|
|
1021
|
+
});
|
|
1022
|
+
}
|
|
1023
|
+
doorTicketAtContent.searchParams.set("ticket", doorTicket ?? "");
|
|
1024
|
+
contentTicketAtDoor.searchParams.set("ticket", contentTicket ?? "");
|
|
1017
1025
|
for (const [what, url] of [
|
|
1018
|
-
["the door ticket at the content route", doorTicketAtContent],
|
|
1019
|
-
["the content ticket at the door", contentTicketAtDoor],
|
|
1026
|
+
["the door ticket at the content route", doorTicketAtContent.href],
|
|
1027
|
+
["the content ticket at the door", contentTicketAtDoor.href],
|
|
1020
1028
|
]) {
|
|
1021
1029
|
const response = await page.request.get(url, { failOnStatusCode: false });
|
|
1022
1030
|
expect(response.status(), `probe: ${what} opens nothing`).toBe(401);
|
package/dist/server/index.js
CHANGED
|
@@ -40,7 +40,8 @@ export { DOOR_PATH, FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
40
40
|
// A served display's door (P125): `/server` serves it for a shell, a page that isn't nested and the
|
|
41
41
|
// sandbox proxy; a content Worker of a host's own answers the same at `DOOR_PATH<key>`, after
|
|
42
42
|
// taking the door's own ticket (`TicketRecord.door`) and running the checks its content's address
|
|
43
|
-
// runs (docs/ADOPTING.md, "The door").
|
|
43
|
+
// runs (docs/ADOPTING.md, "The door"). A host that signs its own tickets answers it with
|
|
44
|
+
// `PortholeServer.doorAnswer` once it has admitted the request itself (P126).
|
|
44
45
|
export { doorResponse, doorStatusResponse } from "./pages.js";
|
|
45
46
|
// A nested page (P111): Porthole's shell at the framed address, the page and its files below the
|
|
46
47
|
// sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
|
package/dist/server/server.js
CHANGED
|
@@ -879,62 +879,82 @@ export function createServer(options) {
|
|
|
879
879
|
const rest = isPageRest(asked) ? asked : undefined;
|
|
880
880
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
881
881
|
}
|
|
882
|
+
/** A door that doesn't open (P125): its status, reason and the host's code, if any. */
|
|
883
|
+
const doorSays = (status, reason, method, code) => doorStatusResponse({
|
|
884
|
+
status,
|
|
885
|
+
reason,
|
|
886
|
+
...(code === undefined ? {} : { code }),
|
|
887
|
+
hostOrigins: options.hostOrigins,
|
|
888
|
+
frameAncestors,
|
|
889
|
+
method,
|
|
890
|
+
});
|
|
882
891
|
/**
|
|
883
892
|
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
884
|
-
* origin
|
|
885
|
-
*
|
|
886
|
-
*
|
|
887
|
-
* own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
|
|
888
|
-
* nested page's shell's label serves none (`serveShellLabel`).
|
|
893
|
+
* origin; then the door's answer for that ticket's grant (`answerDoor`, the one `doorAnswer`
|
|
894
|
+
* gives, P126). No other ticket opens it, and a nested page's shell's label serves none
|
|
895
|
+
* (`serveShellLabel`).
|
|
889
896
|
*/
|
|
890
897
|
async function serveDoor(request, url, label, key) {
|
|
891
898
|
const method = request.method.toUpperCase();
|
|
892
|
-
const say = (status, reason, code) => doorStatusResponse({
|
|
893
|
-
status,
|
|
894
|
-
reason,
|
|
895
|
-
...(code === undefined ? {} : { code }),
|
|
896
|
-
hostOrigins: options.hostOrigins,
|
|
897
|
-
frameAncestors,
|
|
898
|
-
method,
|
|
899
|
-
});
|
|
900
899
|
if (method !== "GET" && method !== "HEAD") {
|
|
901
|
-
return
|
|
900
|
+
return doorSays(405, "error", method);
|
|
902
901
|
}
|
|
902
|
+
let record;
|
|
903
903
|
try {
|
|
904
|
-
|
|
904
|
+
record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
905
905
|
if (record === null ||
|
|
906
906
|
record.door !== true ||
|
|
907
907
|
record.entry !== undefined ||
|
|
908
908
|
record.instance.document.kind === "external" ||
|
|
909
909
|
keys.instanceKey(record.instance) !== key ||
|
|
910
910
|
compiledFor(record.instance)?.config.nested === true) {
|
|
911
|
-
return
|
|
911
|
+
return doorSays(401, "session", method);
|
|
912
912
|
}
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
913
|
+
}
|
|
914
|
+
catch {
|
|
915
|
+
return doorSays(500, "error", method);
|
|
916
|
+
}
|
|
917
|
+
return answerDoor(request, {
|
|
918
|
+
instance: record.instance,
|
|
919
|
+
viewer: record.viewer,
|
|
920
|
+
origin: originOfLabel(label),
|
|
921
|
+
expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
|
|
922
|
+
...(record.anonymous === true ? { anonymous: true } : {}),
|
|
923
|
+
...(record.subject === undefined ? {} : { subject: record.subject }),
|
|
924
|
+
}, isPageRest(record.page) ? record.page : undefined);
|
|
925
|
+
}
|
|
926
|
+
/**
|
|
927
|
+
* The door's answer for an access already admitted (P125, P126): the checks the content's
|
|
928
|
+
* address runs for the same grant (the host's check, the document, its entry, the page it opens
|
|
929
|
+
* at), so the door says what the content's address would: `open`, or `blocked` and why. It sets
|
|
930
|
+
* no cookie and serves nothing of the content; the content's address takes its own ticket and
|
|
931
|
+
* checks again (P050), so the door only tells. `serveDoor` answers with it once its ticket is
|
|
932
|
+
* taken, and `doorAnswer` for a host that admitted the request itself: one answer for both.
|
|
933
|
+
*/
|
|
934
|
+
async function answerDoor(request, access,
|
|
935
|
+
/** A page below a file set's base its frame opens at (P125). */
|
|
936
|
+
below) {
|
|
937
|
+
const method = request.method.toUpperCase();
|
|
938
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
939
|
+
return doorSays(405, "error", method);
|
|
940
|
+
}
|
|
941
|
+
try {
|
|
921
942
|
const refused = await refusalOf(request, access);
|
|
922
943
|
if (refused !== null) {
|
|
923
|
-
return
|
|
944
|
+
return doorSays(403, "denied", method, refused.code);
|
|
924
945
|
}
|
|
925
946
|
const served = await documentOf(access.instance);
|
|
926
947
|
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
927
|
-
const below = isPageRest(record.page) ? record.page : undefined;
|
|
928
948
|
if (served === null ||
|
|
929
949
|
("files" in served
|
|
930
950
|
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
931
951
|
: below !== undefined)) {
|
|
932
|
-
return
|
|
952
|
+
return doorSays(404, "not-found", method);
|
|
933
953
|
}
|
|
934
954
|
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
935
955
|
}
|
|
936
956
|
catch {
|
|
937
|
-
return
|
|
957
|
+
return doorSays(500, "error", method);
|
|
938
958
|
}
|
|
939
959
|
}
|
|
940
960
|
/**
|
|
@@ -1496,12 +1516,8 @@ export function createServer(options) {
|
|
|
1496
1516
|
}
|
|
1497
1517
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1498
1518
|
}
|
|
1499
|
-
/** A
|
|
1500
|
-
|
|
1501
|
-
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1502
|
-
below) {
|
|
1503
|
-
const clean = cleanInstance(instance);
|
|
1504
|
-
check(clean);
|
|
1519
|
+
/** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
|
|
1520
|
+
function checkGrant(clean, grant) {
|
|
1505
1521
|
const anonymous = grant.anonymous === true;
|
|
1506
1522
|
if (anonymous) {
|
|
1507
1523
|
if (grant.viewer !== undefined) {
|
|
@@ -1520,10 +1536,20 @@ export function createServer(options) {
|
|
|
1520
1536
|
(typeof grant.subject !== "string" || grant.subject.length > SUBJECT_MAX)) {
|
|
1521
1537
|
throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
|
|
1522
1538
|
}
|
|
1539
|
+
return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
|
|
1540
|
+
}
|
|
1541
|
+
/** How long a grant's session lasts, checked (`sessionSeconds`). */
|
|
1542
|
+
const sessionOf = (grant) => seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
|
|
1543
|
+
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1544
|
+
async function mint(instance, grant, entry,
|
|
1545
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1546
|
+
below) {
|
|
1547
|
+
const clean = cleanInstance(instance);
|
|
1548
|
+
check(clean);
|
|
1549
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1523
1550
|
const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
|
|
1524
|
-
const sessionSeconds =
|
|
1551
|
+
const sessionSeconds = sessionOf(grant);
|
|
1525
1552
|
const key = keys.instanceKey(clean);
|
|
1526
|
-
const viewer = anonymous ? "" : grant.viewer;
|
|
1527
1553
|
const probe = keys.sign({
|
|
1528
1554
|
i: clean,
|
|
1529
1555
|
w: viewer,
|
|
@@ -1634,6 +1660,29 @@ export function createServer(options) {
|
|
|
1634
1660
|
...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
|
|
1635
1661
|
};
|
|
1636
1662
|
},
|
|
1663
|
+
async doorAnswer(instance, grant, request, at = {}) {
|
|
1664
|
+
// A host that admitted the request itself (P126): no ticket here, the grant is its word.
|
|
1665
|
+
const clean = cleanInstance(instance);
|
|
1666
|
+
check(clean);
|
|
1667
|
+
if (!hasDoor(clean)) {
|
|
1668
|
+
throw new TypeError("This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none");
|
|
1669
|
+
}
|
|
1670
|
+
const below = at.page;
|
|
1671
|
+
if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
|
|
1672
|
+
throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
|
|
1673
|
+
}
|
|
1674
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1675
|
+
const sessionSeconds = sessionOf(grant);
|
|
1676
|
+
const origin = originOfLabel(labelFor(clean));
|
|
1677
|
+
return answerDoor(request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`), {
|
|
1678
|
+
instance: clean,
|
|
1679
|
+
viewer,
|
|
1680
|
+
origin,
|
|
1681
|
+
expiresAt: Date.now() + sessionSeconds * 1_000,
|
|
1682
|
+
...(anonymous ? { anonymous: true } : {}),
|
|
1683
|
+
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
1684
|
+
}, below);
|
|
1685
|
+
},
|
|
1637
1686
|
forget(filter = {}) {
|
|
1638
1687
|
for (const [key, each] of answers) {
|
|
1639
1688
|
if ((filter.scope === undefined || each.scope === filter.scope) &&
|
package/dist/server/types.d.ts
CHANGED
|
@@ -324,6 +324,29 @@ export interface PortholeServer {
|
|
|
324
324
|
at?: {
|
|
325
325
|
readonly page?: string;
|
|
326
326
|
}): Promise<FrameLocation>;
|
|
327
|
+
/**
|
|
328
|
+
* A served display's door answer for a grant the host has already admitted (P126): exactly the
|
|
329
|
+
* Response its door (`DOOR_PATH<key>`, P125) answers once it has taken its own ticket for that
|
|
330
|
+
* instance and grant. The content's address's checks for that grant run here: the host's
|
|
331
|
+
* `authorize` check (`denied`, with its code), the document and its version (`not-found`), a file
|
|
332
|
+
* set's entry being a page and the page `at` names (`not-found`). The answer is `doorResponse`
|
|
333
|
+
* (open) or `doorStatusResponse` (blocked: reason, status, code), with the door's CSP (`sandbox
|
|
334
|
+
* allow-scripts`, `frame-ancestors` the host origins), `no-store`, and no cookie.
|
|
335
|
+
*
|
|
336
|
+
* It is a function, not a route, and it never takes a ticket: it is for a host that signs its own
|
|
337
|
+
* tickets (a content Worker that verifies them itself) and answers its door with it. The caller
|
|
338
|
+
* must have authenticated the request and established the grant itself, as it does before
|
|
339
|
+
* `issue`; Porthole's own door route takes its door ticket and then answers with this. `request`
|
|
340
|
+
* is what `authorize.check` is handed (and gives the method: HEAD has no body, a method other
|
|
341
|
+
* than GET or HEAD is 405); default, a GET of the door on the instance's origin. Throws, as
|
|
342
|
+
* `issue` does, for an instance or grant `issue` would refuse, and for an instance with no door
|
|
343
|
+
* (a nested page, a url-mode app).
|
|
344
|
+
*/
|
|
345
|
+
doorAnswer(instance: InstanceRef, grant: Grant, request?: Request,
|
|
346
|
+
/** The page below a file set's base the frame opens at, as `issue`'s `at` (P125). */
|
|
347
|
+
at?: {
|
|
348
|
+
readonly page?: string;
|
|
349
|
+
}): Promise<Response>;
|
|
327
350
|
/**
|
|
328
351
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
329
352
|
* (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
|
package/docs/ADOPTING.md
CHANGED
|
@@ -874,6 +874,22 @@ checks the content route runs for that grant, then answer `doorResponse({ hostOr
|
|
|
874
874
|
page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
|
|
875
875
|
`@botiverse/porthole/server`.
|
|
876
876
|
|
|
877
|
+
**A host that signs its own tickets** (P126) — its server mints its own ticket for a display and its
|
|
878
|
+
content Worker verifies it, so the Worker holds no Porthole ticket when the door is asked — answers
|
|
879
|
+
the door with **`server.doorAnswer(instance, grant, request?)`**, on the object `createServer`
|
|
880
|
+
returns. Raft's shape: the Worker routes its door path (`/__porthole/door/_raft`, say), verifies
|
|
881
|
+
its own ticket (signature, single use, bound to the label and the instance, and a door's, never its
|
|
882
|
+
content's), admits the request and recovers the grant it was signed for, then returns `await
|
|
883
|
+
server.doorAnswer(instance, grant, request)`. The answer is exactly what `/server`'s own door route
|
|
884
|
+
gives once it has taken its ticket: the host's `authorize` check (`denied` with its code), the
|
|
885
|
+
document and version, a file set's entry being a page (`not-found`), `doorResponse` or
|
|
886
|
+
`doorStatusResponse` with the door's CSP and no cookie. It never takes a ticket and checks nothing
|
|
887
|
+
about the request but its method: **you must have authenticated the request and established the
|
|
888
|
+
grant yourself**, as before `issue`. Pass the request so `authorize.check` sees it, and `{ page }`
|
|
889
|
+
as the fourth argument for a frame that opens at a file set's page below its version. It throws for
|
|
890
|
+
an instance with no door (a nested page, a url-mode app) and for an instance or grant `issue` would
|
|
891
|
+
refuse. The content route still takes its own ticket and checks again (P050).
|
|
892
|
+
|
|
877
893
|
`porthole.config(kind)` is the served config while frames are served, the opaque one while they
|
|
878
894
|
aren't, and null until the meta is known, so a frame never starts opaque and then restarts
|
|
879
895
|
served. The client's functions take no `this`: pass them bare
|
package/docs/DECISIONS.md
CHANGED
|
@@ -6972,3 +6972,50 @@ it.
|
|
|
6972
6972
|
**Revisit when** a host needs a later block told in a display with files (then: start it again on a
|
|
6973
6973
|
dropped status, its next run's first door says it), url mode gets a shell of Porthole's on the app's
|
|
6974
6974
|
origin, or the parallel-mount variant is measured and chosen.
|
|
6975
|
+
|
|
6976
|
+
## P126 · 2026-10-30 · The door's answer for a grant: hosts that sign their own tickets · Accepted
|
|
6977
|
+
|
|
6978
|
+
**Amends P125.** P125's door is answered by `/server` (`serveDoor`) once it takes the door's own
|
|
6979
|
+
ticket, or by a host's content Worker that takes that ticket itself. Raft signs its own tickets on
|
|
6980
|
+
its server and verifies them in its content Worker: at request time it holds no Porthole ticket, so
|
|
6981
|
+
it can neither present one to `serveDoor` nor reproduce the door's checks without copying them
|
|
6982
|
+
(Tenny and Remy, #wg-opensource, 2026-10-30).
|
|
6983
|
+
|
|
6984
|
+
**Decision.** `PortholeServer.doorAnswer(instance, grant, request?, at?)` — a function on the
|
|
6985
|
+
object `createServer` returns, **not a route** — returns exactly the Response `serveDoor` answers
|
|
6986
|
+
for that instance and grant once its ticket step is done: the content route's checks for the grant
|
|
6987
|
+
(the host's `authorize` check → 403 `denied` with its code; the document and its version, a file
|
|
6988
|
+
set's entry being a page, the page `at` names → 404 `not-found`; a failure → 500 `error`; a method
|
|
6989
|
+
other than GET/HEAD → 405), answered with `doorResponse` (open) or `doorStatusResponse`, with the
|
|
6990
|
+
door's CSP (`sandbox allow-scripts`, `frame-ancestors` the host origins), `no-store` and no cookie.
|
|
6991
|
+
`serveDoor` now takes and checks its ticket (single use, bound to label and key, a door ticket,
|
|
6992
|
+
never an entry or hop ticket, no door on a nested page's label: all as in P125) and then answers
|
|
6993
|
+
through the same code (`answerDoor`), so there is one answer, not two kept in step. `doorAnswer`
|
|
6994
|
+
never takes a ticket; it validates the instance and grant as `issue` does, and throws for an
|
|
6995
|
+
instance with no door (a nested page, a url-mode app). `request` is what `authorize.check` is
|
|
6996
|
+
handed; default, a GET of the door on the instance's origin.
|
|
6997
|
+
|
|
6998
|
+
**Threat.** None re-opened. The ticket is how `/server` knows a request was admitted; `doorAnswer`
|
|
6999
|
+
is for a caller that has authenticated the request and established the grant itself (its own
|
|
7000
|
+
ticket, verified in its Worker), as a host does before it calls `issue`. Nothing reaches it from
|
|
7001
|
+
the network that the host didn't route there, and its answer is the one `serveDoor` gives for the
|
|
7002
|
+
same grant, so the door says no more to its frame than P125's does. A host that calls it for a
|
|
7003
|
+
request it didn't admit tells a request `open` that its content route then still refuses (P050:
|
|
7004
|
+
the content route takes its own ticket and checks again), the same as a door ticket handed out
|
|
7005
|
+
wrongly would.
|
|
7006
|
+
|
|
7007
|
+
**Conformance.** `served.domain.door`'s check (4) no longer builds a content URL from the door
|
|
7008
|
+
path's last segment (a host's door path need not end in the content's key: Raft's is
|
|
7009
|
+
`/__porthole/door/_raft`): it swaps the `ticket` parameters between one location's own `url` and
|
|
7010
|
+
`door.url`, each path kept, and expects both refused (401), as before.
|
|
7011
|
+
|
|
7012
|
+
**Tested.** `test/server.test.ts` ("doorAnswer"): an allowed grant is open with the door's exact
|
|
7013
|
+
CSP; denied with the host's code (the check handed the caller's request); not-found for a missing
|
|
7014
|
+
version and for a file set whose entry isn't a page; HEAD and 405; what it throws; and `serveDoor`
|
|
7015
|
+
and `doorAnswer` give byte-identical status, headers and body for the same grant (open for each
|
|
7016
|
+
kind, denied, not-found, a page below a base). Reverse checks (2026-10-30): `serveDoor` answering
|
|
7017
|
+
`open` inline without the checks, and `serveDoor` running the same checks inline but answering
|
|
7018
|
+
with one more frame ancestor, each turn the identity test red (the second, that test alone).
|
|
7019
|
+
|
|
7020
|
+
**Revisit when** a host needs the door's answer to differ from its content route's (it must not:
|
|
7021
|
+
P125's invariant), or Porthole verifies a host's own tickets itself.
|
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.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.7 (2026-10-30). 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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.7",
|
|
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": {
|
|
@@ -1337,18 +1337,27 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1337
1337
|
expect(again.status(), "probe: a used door ticket is 401 session").toBe(401);
|
|
1338
1338
|
|
|
1339
1339
|
// (4) The door ticket at the content route, and the content ticket at the door, open
|
|
1340
|
-
// nothing
|
|
1340
|
+
// nothing: the two tickets of one issue are not interchangeable. Each is swapped into the
|
|
1341
|
+
// other's own URL, each path kept as the host gave it (a host's door path need not end in
|
|
1342
|
+
// its content's key, P126); (6) a fresh door framed from a foreign origin hears nothing
|
|
1343
|
+
// (frame-ancestors).
|
|
1341
1344
|
const fresh = await host.locate(await host.shell("door-cross"));
|
|
1342
|
-
const
|
|
1343
|
-
const
|
|
1344
|
-
const
|
|
1345
|
-
const
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1345
|
+
const doorTicketAtContent = new URL(fresh.url);
|
|
1346
|
+
const contentTicketAtDoor = new URL(doorOf(fresh));
|
|
1347
|
+
const doorTicket = contentTicketAtDoor.searchParams.get("ticket");
|
|
1348
|
+
const contentTicket = doorTicketAtContent.searchParams.get("ticket");
|
|
1349
|
+
if (doorTicket === null || contentTicket === null) {
|
|
1350
|
+
info?.annotations.push({
|
|
1351
|
+
type: "measured",
|
|
1352
|
+
description:
|
|
1353
|
+
"the location's content or door URL carries no ticket query parameter: the swap presents none",
|
|
1354
|
+
});
|
|
1355
|
+
}
|
|
1356
|
+
doorTicketAtContent.searchParams.set("ticket", doorTicket ?? "");
|
|
1357
|
+
contentTicketAtDoor.searchParams.set("ticket", contentTicket ?? "");
|
|
1349
1358
|
for (const [what, url] of [
|
|
1350
|
-
["the door ticket at the content route", doorTicketAtContent],
|
|
1351
|
-
["the content ticket at the door", contentTicketAtDoor],
|
|
1359
|
+
["the door ticket at the content route", doorTicketAtContent.href],
|
|
1360
|
+
["the content ticket at the door", contentTicketAtDoor.href],
|
|
1352
1361
|
] as const) {
|
|
1353
1362
|
const response = await page.request.get(url, { failOnStatusCode: false });
|
|
1354
1363
|
expect(response.status(), `probe: ${what} opens nothing`).toBe(401);
|
package/src/server/index.ts
CHANGED
|
@@ -73,7 +73,8 @@ export { DOOR_PATH, FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
|
73
73
|
// A served display's door (P125): `/server` serves it for a shell, a page that isn't nested and the
|
|
74
74
|
// sandbox proxy; a content Worker of a host's own answers the same at `DOOR_PATH<key>`, after
|
|
75
75
|
// taking the door's own ticket (`TicketRecord.door`) and running the checks its content's address
|
|
76
|
-
// runs (docs/ADOPTING.md, "The door").
|
|
76
|
+
// runs (docs/ADOPTING.md, "The door"). A host that signs its own tickets answers it with
|
|
77
|
+
// `PortholeServer.doorAnswer` once it has admitted the request itself (P126).
|
|
77
78
|
export { doorResponse, doorStatusResponse, type DoorOptions } from "./pages.ts";
|
|
78
79
|
// A nested page (P111): Porthole's shell at the framed address, the page and its files below the
|
|
79
80
|
// sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
|
package/src/server/server.ts
CHANGED
|
@@ -1125,13 +1125,22 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1125
1125
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
1126
1126
|
}
|
|
1127
1127
|
|
|
1128
|
+
/** A door that doesn't open (P125): its status, reason and the host's code, if any. */
|
|
1129
|
+
const doorSays = (status: number, reason: FrameBlock, method: string, code?: string): Response =>
|
|
1130
|
+
doorStatusResponse({
|
|
1131
|
+
status,
|
|
1132
|
+
reason,
|
|
1133
|
+
...(code === undefined ? {} : { code }),
|
|
1134
|
+
hostOrigins: options.hostOrigins,
|
|
1135
|
+
frameAncestors,
|
|
1136
|
+
method,
|
|
1137
|
+
});
|
|
1138
|
+
|
|
1128
1139
|
/**
|
|
1129
1140
|
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
1130
|
-
* origin
|
|
1131
|
-
*
|
|
1132
|
-
*
|
|
1133
|
-
* own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
|
|
1134
|
-
* nested page's shell's label serves none (`serveShellLabel`).
|
|
1141
|
+
* origin; then the door's answer for that ticket's grant (`answerDoor`, the one `doorAnswer`
|
|
1142
|
+
* gives, P126). No other ticket opens it, and a nested page's shell's label serves none
|
|
1143
|
+
* (`serveShellLabel`).
|
|
1135
1144
|
*/
|
|
1136
1145
|
async function serveDoor(
|
|
1137
1146
|
request: Request,
|
|
@@ -1140,20 +1149,12 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1140
1149
|
key: string,
|
|
1141
1150
|
): Promise<Response> {
|
|
1142
1151
|
const method = request.method.toUpperCase();
|
|
1143
|
-
const say = (status: number, reason: FrameBlock, code?: string): Response =>
|
|
1144
|
-
doorStatusResponse({
|
|
1145
|
-
status,
|
|
1146
|
-
reason,
|
|
1147
|
-
...(code === undefined ? {} : { code }),
|
|
1148
|
-
hostOrigins: options.hostOrigins,
|
|
1149
|
-
frameAncestors,
|
|
1150
|
-
method,
|
|
1151
|
-
});
|
|
1152
1152
|
if (method !== "GET" && method !== "HEAD") {
|
|
1153
|
-
return
|
|
1153
|
+
return doorSays(405, "error", method);
|
|
1154
1154
|
}
|
|
1155
|
+
let record: TicketRecord | null;
|
|
1155
1156
|
try {
|
|
1156
|
-
|
|
1157
|
+
record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
1157
1158
|
if (
|
|
1158
1159
|
record === null ||
|
|
1159
1160
|
record.door !== true ||
|
|
@@ -1162,34 +1163,61 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1162
1163
|
keys.instanceKey(record.instance) !== key ||
|
|
1163
1164
|
compiledFor(record.instance)?.config.nested === true
|
|
1164
1165
|
) {
|
|
1165
|
-
return
|
|
1166
|
+
return doorSays(401, "session", method);
|
|
1166
1167
|
}
|
|
1167
|
-
|
|
1168
|
+
} catch {
|
|
1169
|
+
return doorSays(500, "error", method);
|
|
1170
|
+
}
|
|
1171
|
+
return answerDoor(
|
|
1172
|
+
request,
|
|
1173
|
+
{
|
|
1168
1174
|
instance: record.instance,
|
|
1169
1175
|
viewer: record.viewer,
|
|
1170
1176
|
origin: originOfLabel(label),
|
|
1171
1177
|
expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
|
|
1172
1178
|
...(record.anonymous === true ? { anonymous: true } : {}),
|
|
1173
1179
|
...(record.subject === undefined ? {} : { subject: record.subject }),
|
|
1174
|
-
}
|
|
1180
|
+
},
|
|
1181
|
+
isPageRest(record.page) ? record.page : undefined,
|
|
1182
|
+
);
|
|
1183
|
+
}
|
|
1184
|
+
|
|
1185
|
+
/**
|
|
1186
|
+
* The door's answer for an access already admitted (P125, P126): the checks the content's
|
|
1187
|
+
* address runs for the same grant (the host's check, the document, its entry, the page it opens
|
|
1188
|
+
* at), so the door says what the content's address would: `open`, or `blocked` and why. It sets
|
|
1189
|
+
* no cookie and serves nothing of the content; the content's address takes its own ticket and
|
|
1190
|
+
* checks again (P050), so the door only tells. `serveDoor` answers with it once its ticket is
|
|
1191
|
+
* taken, and `doorAnswer` for a host that admitted the request itself: one answer for both.
|
|
1192
|
+
*/
|
|
1193
|
+
async function answerDoor(
|
|
1194
|
+
request: Request,
|
|
1195
|
+
access: Access,
|
|
1196
|
+
/** A page below a file set's base its frame opens at (P125). */
|
|
1197
|
+
below: string | undefined,
|
|
1198
|
+
): Promise<Response> {
|
|
1199
|
+
const method = request.method.toUpperCase();
|
|
1200
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
1201
|
+
return doorSays(405, "error", method);
|
|
1202
|
+
}
|
|
1203
|
+
try {
|
|
1175
1204
|
const refused = await refusalOf(request, access);
|
|
1176
1205
|
if (refused !== null) {
|
|
1177
|
-
return
|
|
1206
|
+
return doorSays(403, "denied", method, refused.code);
|
|
1178
1207
|
}
|
|
1179
1208
|
const served = await documentOf(access.instance);
|
|
1180
1209
|
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
1181
|
-
const below = isPageRest(record.page) ? record.page : undefined;
|
|
1182
1210
|
if (
|
|
1183
1211
|
served === null ||
|
|
1184
1212
|
("files" in served
|
|
1185
1213
|
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
1186
1214
|
: below !== undefined)
|
|
1187
1215
|
) {
|
|
1188
|
-
return
|
|
1216
|
+
return doorSays(404, "not-found", method);
|
|
1189
1217
|
}
|
|
1190
1218
|
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
1191
1219
|
} catch {
|
|
1192
|
-
return
|
|
1220
|
+
return doorSays(500, "error", method);
|
|
1193
1221
|
}
|
|
1194
1222
|
}
|
|
1195
1223
|
|
|
@@ -1839,22 +1867,11 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1839
1867
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1840
1868
|
}
|
|
1841
1869
|
|
|
1842
|
-
/** A
|
|
1843
|
-
|
|
1844
|
-
|
|
1870
|
+
/** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
|
|
1871
|
+
function checkGrant(
|
|
1872
|
+
clean: InstanceRef,
|
|
1845
1873
|
grant: Grant,
|
|
1846
|
-
|
|
1847
|
-
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1848
|
-
below?: string,
|
|
1849
|
-
): Promise<{
|
|
1850
|
-
readonly clean: InstanceRef;
|
|
1851
|
-
readonly key: string;
|
|
1852
|
-
readonly ticket: string;
|
|
1853
|
-
/** The door's own ticket (P125), for a display framed on its scope's origin. */
|
|
1854
|
-
readonly door: string | null;
|
|
1855
|
-
}> {
|
|
1856
|
-
const clean = cleanInstance(instance);
|
|
1857
|
-
check(clean);
|
|
1874
|
+
): { readonly anonymous: boolean; readonly viewer: string } {
|
|
1858
1875
|
const anonymous = grant.anonymous === true;
|
|
1859
1876
|
if (anonymous) {
|
|
1860
1877
|
if (grant.viewer !== undefined) {
|
|
@@ -1876,15 +1893,33 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1876
1893
|
) {
|
|
1877
1894
|
throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
|
|
1878
1895
|
}
|
|
1896
|
+
return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
|
|
1897
|
+
}
|
|
1898
|
+
|
|
1899
|
+
/** How long a grant's session lasts, checked (`sessionSeconds`). */
|
|
1900
|
+
const sessionOf = (grant: Grant): number =>
|
|
1901
|
+
seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
|
|
1902
|
+
|
|
1903
|
+
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1904
|
+
async function mint(
|
|
1905
|
+
instance: InstanceRef,
|
|
1906
|
+
grant: Grant,
|
|
1907
|
+
entry?: TicketRecord["entry"],
|
|
1908
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1909
|
+
below?: string,
|
|
1910
|
+
): Promise<{
|
|
1911
|
+
readonly clean: InstanceRef;
|
|
1912
|
+
readonly key: string;
|
|
1913
|
+
readonly ticket: string;
|
|
1914
|
+
/** The door's own ticket (P125), for a display framed on its scope's origin. */
|
|
1915
|
+
readonly door: string | null;
|
|
1916
|
+
}> {
|
|
1917
|
+
const clean = cleanInstance(instance);
|
|
1918
|
+
check(clean);
|
|
1919
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1879
1920
|
const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
|
|
1880
|
-
const sessionSeconds =
|
|
1881
|
-
grant.sessionSeconds,
|
|
1882
|
-
DEFAULT_SESSION_SECONDS,
|
|
1883
|
-
MAX_SESSION_SECONDS,
|
|
1884
|
-
"sessionSeconds",
|
|
1885
|
-
);
|
|
1921
|
+
const sessionSeconds = sessionOf(grant);
|
|
1886
1922
|
const key = keys.instanceKey(clean);
|
|
1887
|
-
const viewer = anonymous ? "" : grant.viewer;
|
|
1888
1923
|
const probe = keys.sign({
|
|
1889
1924
|
i: clean,
|
|
1890
1925
|
w: viewer,
|
|
@@ -2008,6 +2043,38 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
2008
2043
|
};
|
|
2009
2044
|
},
|
|
2010
2045
|
|
|
2046
|
+
async doorAnswer(instance, grant, request, at = {}): Promise<Response> {
|
|
2047
|
+
// A host that admitted the request itself (P126): no ticket here, the grant is its word.
|
|
2048
|
+
const clean = cleanInstance(instance);
|
|
2049
|
+
check(clean);
|
|
2050
|
+
if (!hasDoor(clean)) {
|
|
2051
|
+
throw new TypeError(
|
|
2052
|
+
"This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none",
|
|
2053
|
+
);
|
|
2054
|
+
}
|
|
2055
|
+
const below = at.page;
|
|
2056
|
+
if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
|
|
2057
|
+
throw new TypeError(
|
|
2058
|
+
"A frame's page is a relative path below an artifact's files (no . or ..)",
|
|
2059
|
+
);
|
|
2060
|
+
}
|
|
2061
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
2062
|
+
const sessionSeconds = sessionOf(grant);
|
|
2063
|
+
const origin = originOfLabel(labelFor(clean));
|
|
2064
|
+
return answerDoor(
|
|
2065
|
+
request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`),
|
|
2066
|
+
{
|
|
2067
|
+
instance: clean,
|
|
2068
|
+
viewer,
|
|
2069
|
+
origin,
|
|
2070
|
+
expiresAt: Date.now() + sessionSeconds * 1_000,
|
|
2071
|
+
...(anonymous ? { anonymous: true } : {}),
|
|
2072
|
+
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
2073
|
+
},
|
|
2074
|
+
below,
|
|
2075
|
+
);
|
|
2076
|
+
},
|
|
2077
|
+
|
|
2011
2078
|
forget(filter = {}) {
|
|
2012
2079
|
for (const [key, each] of answers) {
|
|
2013
2080
|
if (
|
package/src/server/types.ts
CHANGED
|
@@ -342,6 +342,31 @@ export interface PortholeServer {
|
|
|
342
342
|
*/
|
|
343
343
|
at?: { readonly page?: string },
|
|
344
344
|
): Promise<FrameLocation>;
|
|
345
|
+
/**
|
|
346
|
+
* A served display's door answer for a grant the host has already admitted (P126): exactly the
|
|
347
|
+
* Response its door (`DOOR_PATH<key>`, P125) answers once it has taken its own ticket for that
|
|
348
|
+
* instance and grant. The content's address's checks for that grant run here: the host's
|
|
349
|
+
* `authorize` check (`denied`, with its code), the document and its version (`not-found`), a file
|
|
350
|
+
* set's entry being a page and the page `at` names (`not-found`). The answer is `doorResponse`
|
|
351
|
+
* (open) or `doorStatusResponse` (blocked: reason, status, code), with the door's CSP (`sandbox
|
|
352
|
+
* allow-scripts`, `frame-ancestors` the host origins), `no-store`, and no cookie.
|
|
353
|
+
*
|
|
354
|
+
* It is a function, not a route, and it never takes a ticket: it is for a host that signs its own
|
|
355
|
+
* tickets (a content Worker that verifies them itself) and answers its door with it. The caller
|
|
356
|
+
* must have authenticated the request and established the grant itself, as it does before
|
|
357
|
+
* `issue`; Porthole's own door route takes its door ticket and then answers with this. `request`
|
|
358
|
+
* is what `authorize.check` is handed (and gives the method: HEAD has no body, a method other
|
|
359
|
+
* than GET or HEAD is 405); default, a GET of the door on the instance's origin. Throws, as
|
|
360
|
+
* `issue` does, for an instance or grant `issue` would refuse, and for an instance with no door
|
|
361
|
+
* (a nested page, a url-mode app).
|
|
362
|
+
*/
|
|
363
|
+
doorAnswer(
|
|
364
|
+
instance: InstanceRef,
|
|
365
|
+
grant: Grant,
|
|
366
|
+
request?: Request,
|
|
367
|
+
/** The page below a file set's base the frame opens at, as `issue`'s `at` (P125). */
|
|
368
|
+
at?: { readonly page?: string },
|
|
369
|
+
): Promise<Response>;
|
|
345
370
|
/**
|
|
346
371
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
347
372
|
* (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
|