@botiverse/porthole 0.14.5 → 0.14.6
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 +53 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -1
- package/dist/compile/policy.d.ts +6 -0
- package/dist/compile/policy.js +6 -0
- package/dist/conformance/entry.d.ts +25 -6
- package/dist/conformance/entry.js +69 -18
- package/dist/conformance/harness/page.d.ts +12 -0
- package/dist/conformance/harness/page.js +95 -51
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +39 -13
- package/dist/conformance/served.js +140 -0
- package/dist/files/paths.d.ts +2 -2
- package/dist/files/paths.js +12 -2
- package/dist/host/client.d.ts +8 -0
- package/dist/host/client.js +47 -17
- package/dist/host/create-host.d.ts +10 -0
- package/dist/host/create-host.js +124 -10
- package/dist/host/door.d.ts +41 -0
- package/dist/host/door.js +55 -0
- package/dist/host/locate.js +2 -0
- package/dist/host/locator.d.ts +55 -3
- package/dist/host/locator.js +152 -42
- package/dist/host/outcome.d.ts +54 -1
- package/dist/host/outcome.js +33 -8
- package/dist/host/types.d.ts +10 -2
- package/dist/isolation/served.d.ts +1 -1
- package/dist/isolation/served.js +35 -0
- package/dist/isolation/types.d.ts +20 -2
- package/dist/isolation/types.js +2 -0
- package/dist/platform/types.d.ts +22 -0
- package/dist/platform/web.js +55 -12
- package/dist/react/view.d.ts +13 -0
- package/dist/react/view.js +101 -2
- package/dist/server/files.d.ts +11 -0
- package/dist/server/files.js +26 -4
- package/dist/server/host.js +106 -28
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +6 -1
- package/dist/server/pages.d.ts +32 -0
- package/dist/server/pages.js +82 -6
- package/dist/server/server.js +140 -11
- package/dist/server/types.d.ts +15 -1
- package/dist/transport/post-message.d.ts +1 -9
- package/dist/transport/post-message.js +2 -8
- package/docs/ADOPTING.md +57 -4
- package/docs/DECISIONS.md +198 -0
- package/docs/DESIGN.md +24 -18
- package/docs/THREAT_MODEL.md +79 -13
- package/package.json +1 -1
- package/src/check/page.ts +6 -1
- package/src/compile/policy.ts +7 -0
- package/src/conformance/entry.ts +129 -24
- package/src/conformance/harness/page.ts +112 -49
- package/src/conformance/host-kit.ts +53 -16
- package/src/conformance/served.ts +175 -0
- package/src/files/paths.ts +11 -2
- package/src/host/client.ts +59 -22
- package/src/host/create-host.ts +144 -18
- package/src/host/door.ts +97 -0
- package/src/host/locate.ts +2 -0
- package/src/host/locator.ts +208 -57
- package/src/host/outcome.ts +41 -9
- package/src/host/types.ts +10 -2
- package/src/isolation/served.ts +40 -1
- package/src/isolation/types.ts +19 -2
- package/src/platform/types.ts +21 -0
- package/src/platform/web.ts +55 -20
- package/src/react/view.tsx +149 -2
- package/src/server/files.ts +37 -5
- package/src/server/host.ts +131 -46
- package/src/server/index.ts +6 -1
- package/src/server/pages.ts +101 -6
- package/src/server/server.ts +186 -19
- package/src/server/types.ts +16 -1
- package/src/transport/post-message.ts +1 -9
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { DoorSurface } from "../platform/types.ts";
|
|
2
|
+
import type { FrameOutcome } from "./types.ts";
|
|
3
|
+
/**
|
|
4
|
+
* A served display's door (P125). A served display that isn't nested (a served shell, a page, a
|
|
5
|
+
* view through the sandbox proxy) is framed on its scope's origin, where the scope's other displays
|
|
6
|
+
* run content with `allow-same-origin`: one of them reaches a new document there before its first
|
|
7
|
+
* script runs, so nothing its frame says, and nothing its silence suggests, is Porthole's word.
|
|
8
|
+
*
|
|
9
|
+
* So before its frame is made, the host frames its door: a page of Porthole's server on the same
|
|
10
|
+
* origin, in a frame of the host's own, hidden, sandboxed with scripts alone (an opaque origin, a
|
|
11
|
+
* new one each time, which no content is the same origin as), with no name (nothing targets it).
|
|
12
|
+
* The server takes the door's own ticket and runs the checks the content's address runs for the
|
|
13
|
+
* same grant (the host's check, the document, its entry), and the door says how loading went, once:
|
|
14
|
+
* `open` (frame the display), or `blocked` and why. The host takes that word only from the door
|
|
15
|
+
* frame's window, from an opaque origin (`"null"`), the first well-formed frame status it says; a
|
|
16
|
+
* door that loaded and said nothing never ran (`framing`: its server didn't let this page frame
|
|
17
|
+
* it). The door's frame is gone once it said, before the display's frame is made.
|
|
18
|
+
*
|
|
19
|
+
* "A `load` event is not a committed document" (DECISIONS P125): a document wiped and navigated
|
|
20
|
+
* while it parses never fires `load`, so no host may read a frame's first load as its first
|
|
21
|
+
* document. The door's "load, then `SETTLE_MS` of silence: framing" doesn't rest on that: no content
|
|
22
|
+
* ever runs in the door (its one script is Porthole's, by its hash, under `default-src 'none'`),
|
|
23
|
+
* so nothing navigates it from inside; and a sibling of its scope, which does get its `WindowProxy`
|
|
24
|
+
* while it loads, can't reach in: reading it throws (it is opaque), setting or replacing its
|
|
25
|
+
* `location` throws (the sibling's own sandbox navigates no frame not its own), and it has no
|
|
26
|
+
* name, so `window.open` and a link's or a form's `target` find nothing. The host hears it from
|
|
27
|
+
* `"null"` alone. `[door-reach]` and the `door-opaque` control hold that.
|
|
28
|
+
*/
|
|
29
|
+
export interface DoorWatch {
|
|
30
|
+
stop(): void;
|
|
31
|
+
}
|
|
32
|
+
export declare function watchDoor(options: {
|
|
33
|
+
readonly door: DoorSurface;
|
|
34
|
+
readonly timeoutMs: number;
|
|
35
|
+
/** The door said `open`: the display may be framed. */
|
|
36
|
+
readonly onOpen: () => void;
|
|
37
|
+
/** The door said `blocked`, or loaded and said nothing (`framing`), or nothing came in time. */
|
|
38
|
+
readonly onOutcome: (outcome: Exclude<FrameOutcome, {
|
|
39
|
+
state: "loaded";
|
|
40
|
+
}>) => void;
|
|
41
|
+
}): DoorWatch;
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { parseFrameStatus, SETTLE_MS } from "./outcome.js";
|
|
2
|
+
export function watchDoor(options) {
|
|
3
|
+
const { door } = options;
|
|
4
|
+
let decided = false;
|
|
5
|
+
const timers = new Set();
|
|
6
|
+
const later = (ms, run) => {
|
|
7
|
+
const timer = setTimeout(() => {
|
|
8
|
+
timers.delete(timer);
|
|
9
|
+
run();
|
|
10
|
+
}, ms);
|
|
11
|
+
timers.add(timer);
|
|
12
|
+
};
|
|
13
|
+
const stop = () => {
|
|
14
|
+
decided = true;
|
|
15
|
+
for (const timer of timers) {
|
|
16
|
+
clearTimeout(timer);
|
|
17
|
+
}
|
|
18
|
+
timers.clear();
|
|
19
|
+
unlisten();
|
|
20
|
+
unload();
|
|
21
|
+
};
|
|
22
|
+
const unlisten = door.transport.listen((data) => {
|
|
23
|
+
if (decided) {
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
const status = parseFrameStatus(data);
|
|
27
|
+
// A door says `open` or `blocked`, nothing else: anything else is no door's word.
|
|
28
|
+
if (status?.state === "open") {
|
|
29
|
+
stop();
|
|
30
|
+
options.onOpen();
|
|
31
|
+
}
|
|
32
|
+
else if (status?.state === "blocked") {
|
|
33
|
+
stop();
|
|
34
|
+
options.onOutcome({
|
|
35
|
+
state: "blocked",
|
|
36
|
+
reason: status.reason ?? "error",
|
|
37
|
+
...(status.status === undefined ? {} : { status: status.status }),
|
|
38
|
+
...(status.code === undefined ? {} : { code: status.code }),
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
});
|
|
42
|
+
const unload = door.onLoad(() => later(SETTLE_MS, () => {
|
|
43
|
+
if (!decided) {
|
|
44
|
+
stop();
|
|
45
|
+
options.onOutcome({ state: "blocked", reason: "framing" });
|
|
46
|
+
}
|
|
47
|
+
}));
|
|
48
|
+
later(options.timeoutMs, () => {
|
|
49
|
+
if (!decided) {
|
|
50
|
+
stop();
|
|
51
|
+
options.onOutcome({ state: "timeout" });
|
|
52
|
+
}
|
|
53
|
+
});
|
|
54
|
+
return { stop };
|
|
55
|
+
}
|
package/dist/host/locate.js
CHANGED
|
@@ -20,5 +20,7 @@ export async function locateServed(locator, instance, config, hostOrigin, signal
|
|
|
20
20
|
origin: location.origin,
|
|
21
21
|
...(location.reports === true ? { reports: true } : {}),
|
|
22
22
|
...(viewer === null ? {} : { viewer }),
|
|
23
|
+
// Its door (P125), checked with the location: the host frames it before `url`.
|
|
24
|
+
...(location.door === undefined ? {} : { door: new URL(location.door.url).href }),
|
|
23
25
|
};
|
|
24
26
|
}
|
package/dist/host/locator.d.ts
CHANGED
|
@@ -1,17 +1,31 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
-
import type { InstanceLocator } from "../isolation/types.ts";
|
|
2
|
+
import type { FrameLocation, InstanceLocator, InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import type { FrameOutcome } from "./types.ts";
|
|
3
4
|
/**
|
|
4
5
|
* The client half of the host kit (P066): a locator that asks the app's issue endpoint
|
|
5
6
|
* (`ContentHost.issue`) for a frame's location, and the choice between served and opaque configs.
|
|
6
7
|
* The client proposes an instance; the server's mapping decides what it means, and the server
|
|
7
8
|
* alone chooses the origin.
|
|
8
9
|
*/
|
|
9
|
-
/**
|
|
10
|
+
/**
|
|
11
|
+
* Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …), and
|
|
12
|
+
* for a refusal the host's own reason code where its answer gave one (`error.reason`, P125).
|
|
13
|
+
*/
|
|
10
14
|
export declare class LocateError extends Error {
|
|
11
15
|
readonly status: number;
|
|
12
16
|
readonly code: string;
|
|
13
|
-
|
|
17
|
+
/** The host's reason code from the issue answer's `error.reason` (a short lowercase token). */
|
|
18
|
+
readonly reason?: string;
|
|
19
|
+
constructor(message: string, status: number, code: string, reason?: string);
|
|
14
20
|
}
|
|
21
|
+
/**
|
|
22
|
+
* What a display shows when the host's own issue endpoint refused it (P125): the host asked before
|
|
23
|
+
* it built any frame, so this is the host's word, never a frame's. Only a refusal maps (401: sign
|
|
24
|
+
* in, 403: denied, with the host's code if its answer gave one, 404: not found); anything else
|
|
25
|
+
* (5xx, a network failure, a malformed answer) is null, the host's own failure (`locate`), never
|
|
26
|
+
* `denied`.
|
|
27
|
+
*/
|
|
28
|
+
export declare function outcomeOfRefusal(error: unknown): FrameOutcome | null;
|
|
15
29
|
export interface HttpLocatorOptions {
|
|
16
30
|
/** Headers for each request (an `authorization`), or a function giving them now. */
|
|
17
31
|
readonly headers?: HeadersInit | (() => HeadersInit);
|
|
@@ -21,8 +35,46 @@ export interface HttpLocatorOptions {
|
|
|
21
35
|
readonly onNotServed?: () => void;
|
|
22
36
|
readonly fetch?: typeof fetch;
|
|
23
37
|
}
|
|
38
|
+
/**
|
|
39
|
+
* A location's door as an issue endpoint answered it (P125): passed on as it came, checked with the
|
|
40
|
+
* location before any frame is made (`checkFrameLocation`); null for none, "bad" for one that
|
|
41
|
+
* isn't `{ url: string }`.
|
|
42
|
+
*/
|
|
43
|
+
export declare function doorOf(data: Record<string, unknown>): {
|
|
44
|
+
readonly url: string;
|
|
45
|
+
} | null | "bad";
|
|
46
|
+
/** The refusal an issue endpoint answered: its message, status, code and the host's reason. */
|
|
47
|
+
export declare function refusalOf(response: {
|
|
48
|
+
readonly status: number;
|
|
49
|
+
}, data: unknown): LocateError;
|
|
50
|
+
/** A frame location as an issue endpoint answered it, checked in shape; throws a `LocateError`. */
|
|
51
|
+
export declare function locationOf(status: number, data: unknown): FrameLocation;
|
|
24
52
|
/** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
|
|
25
53
|
export declare function httpLocator(url: string, options?: HttpLocatorOptions): InstanceLocator;
|
|
54
|
+
/**
|
|
55
|
+
* What a clean address resolves to (P125): its instance and an issued location for it (a ticket,
|
|
56
|
+
* a door), or the outcome the host's issue endpoint answered instead (signed out, denied, not
|
|
57
|
+
* found), before any frame is built. A clean address is for a tab; a frame shows what it names
|
|
58
|
+
* through `issue`.
|
|
59
|
+
*/
|
|
60
|
+
export type Resolved = {
|
|
61
|
+
readonly instance: InstanceRef;
|
|
62
|
+
readonly location: FrameLocation;
|
|
63
|
+
} | {
|
|
64
|
+
readonly outcome: FrameOutcome;
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* A locator whose first call answers `location` (one a `resolve` got), once, and every later one
|
|
68
|
+
* asks `then` (P125): bound to the one display that resolved it, so no other view of the same
|
|
69
|
+
* instance can take its tickets, and every run after the first issues afresh.
|
|
70
|
+
*/
|
|
71
|
+
export declare function oneShot(location: FrameLocation, then: InstanceLocator): InstanceLocator;
|
|
72
|
+
/**
|
|
73
|
+
* Asks the app's issue endpoint at `url` what the clean address `address` names, for this viewer
|
|
74
|
+
* (`{ address }`, P125). A refusal (401, 403, 404) is an outcome; anything else that isn't a
|
|
75
|
+
* location is thrown, the host's own failure.
|
|
76
|
+
*/
|
|
77
|
+
export declare function resolveAddress(url: string, address: string, options?: HttpLocatorOptions, signal?: AbortSignal): Promise<Resolved>;
|
|
26
78
|
/** What the page knows of content (`ContentHost.meta`, as the app's own meta carries it). */
|
|
27
79
|
export interface ServedMeta {
|
|
28
80
|
readonly served: boolean;
|
package/dist/host/locator.js
CHANGED
|
@@ -5,65 +5,175 @@ import { parseViewer } from "../runtime/levels.js";
|
|
|
5
5
|
* The client proposes an instance; the server's mapping decides what it means, and the server
|
|
6
6
|
* alone chooses the origin.
|
|
7
7
|
*/
|
|
8
|
-
/**
|
|
8
|
+
/**
|
|
9
|
+
* Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …), and
|
|
10
|
+
* for a refusal the host's own reason code where its answer gave one (`error.reason`, P125).
|
|
11
|
+
*/
|
|
9
12
|
export class LocateError extends Error {
|
|
10
13
|
status;
|
|
11
14
|
code;
|
|
12
|
-
|
|
15
|
+
/** The host's reason code from the issue answer's `error.reason` (a short lowercase token). */
|
|
16
|
+
reason;
|
|
17
|
+
constructor(message, status, code, reason) {
|
|
13
18
|
super(message);
|
|
14
19
|
this.name = "LocateError";
|
|
15
20
|
this.status = status;
|
|
16
21
|
this.code = code;
|
|
22
|
+
if (reason !== undefined) {
|
|
23
|
+
this.reason = reason;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
/** A host's reason code, as an outcome's `code` takes it (`FrameOutcome.code`). */
|
|
28
|
+
const REASON_CODE = /^[a-z0-9-]{1,40}$/u;
|
|
29
|
+
/**
|
|
30
|
+
* What a display shows when the host's own issue endpoint refused it (P125): the host asked before
|
|
31
|
+
* it built any frame, so this is the host's word, never a frame's. Only a refusal maps (401: sign
|
|
32
|
+
* in, 403: denied, with the host's code if its answer gave one, 404: not found); anything else
|
|
33
|
+
* (5xx, a network failure, a malformed answer) is null, the host's own failure (`locate`), never
|
|
34
|
+
* `denied`.
|
|
35
|
+
*/
|
|
36
|
+
export function outcomeOfRefusal(error) {
|
|
37
|
+
if (!(error instanceof LocateError)) {
|
|
38
|
+
return null;
|
|
39
|
+
}
|
|
40
|
+
const code = error.reason !== undefined && REASON_CODE.test(error.reason) ? { code: error.reason } : {};
|
|
41
|
+
// Only the issue endpoint's own refusal, by its shape (`{ error: { code } }` with the code that
|
|
42
|
+
// goes with its status): a bare 401, 403 or 404 from a router or a firewall in front of it is no
|
|
43
|
+
// answer of the host's, so it stays the host's own failure (`locate`).
|
|
44
|
+
if (error.status === 401 && error.code === "unauthenticated") {
|
|
45
|
+
return { state: "blocked", reason: "sign-in", status: 401 };
|
|
46
|
+
}
|
|
47
|
+
if (error.status === 403 && error.code === "forbidden") {
|
|
48
|
+
return { state: "blocked", reason: "denied", status: 403, ...code };
|
|
17
49
|
}
|
|
50
|
+
if (error.status === 404 && error.code === "not-found") {
|
|
51
|
+
return { state: "blocked", reason: "not-found", status: 404 };
|
|
52
|
+
}
|
|
53
|
+
return null;
|
|
18
54
|
}
|
|
19
55
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
56
|
+
/**
|
|
57
|
+
* A location's door as an issue endpoint answered it (P125): passed on as it came, checked with the
|
|
58
|
+
* location before any frame is made (`checkFrameLocation`); null for none, "bad" for one that
|
|
59
|
+
* isn't `{ url: string }`.
|
|
60
|
+
*/
|
|
61
|
+
export function doorOf(data) {
|
|
62
|
+
if (data.door === undefined) {
|
|
63
|
+
return null;
|
|
64
|
+
}
|
|
65
|
+
return isRecord(data.door) && typeof data.door.url === "string" ? { url: data.door.url } : "bad";
|
|
66
|
+
}
|
|
67
|
+
/** The refusal an issue endpoint answered: its message, status, code and the host's reason. */
|
|
68
|
+
export function refusalOf(response, data) {
|
|
69
|
+
const error = isRecord(data) && isRecord(data.error) ? data.error : {};
|
|
70
|
+
const code = typeof error.code === "string" ? error.code : "failed";
|
|
71
|
+
const reason = typeof error.reason === "string" && REASON_CODE.test(error.reason) ? error.reason : undefined;
|
|
72
|
+
return new LocateError(typeof error.message === "string"
|
|
73
|
+
? error.message
|
|
74
|
+
: `The app's issue endpoint answered ${response.status}`, response.status, code, reason);
|
|
75
|
+
}
|
|
76
|
+
/** A frame location as an issue endpoint answered it, checked in shape; throws a `LocateError`. */
|
|
77
|
+
export function locationOf(status, data) {
|
|
78
|
+
if (!isRecord(data) ||
|
|
79
|
+
typeof data.url !== "string" ||
|
|
80
|
+
typeof data.origin !== "string" ||
|
|
81
|
+
(data.reports !== undefined && typeof data.reports !== "boolean")) {
|
|
82
|
+
throw new LocateError("The app's issue endpoint gave no frame location", status, "bad-location");
|
|
83
|
+
}
|
|
84
|
+
// Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
|
|
85
|
+
const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
|
|
86
|
+
if (data.viewer !== undefined && viewer === null) {
|
|
87
|
+
throw new LocateError("The app's issue endpoint named a viewer that isn't one", status, "bad-location");
|
|
88
|
+
}
|
|
89
|
+
const door = doorOf(data);
|
|
90
|
+
if (door === "bad") {
|
|
91
|
+
throw new LocateError("The app's issue endpoint named a door that isn't one", status, "bad-location");
|
|
92
|
+
}
|
|
93
|
+
return {
|
|
94
|
+
url: data.url,
|
|
95
|
+
origin: data.origin,
|
|
96
|
+
...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
|
|
97
|
+
...(viewer === null ? {} : { viewer }),
|
|
98
|
+
...(door === null ? {} : { door }),
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
/** POSTs `body` to the app's issue endpoint at `url`: its answer's JSON, or the refusal thrown. */
|
|
102
|
+
async function askIssue(url, body, options, signal) {
|
|
103
|
+
const extra = typeof options.headers === "function" ? options.headers() : options.headers;
|
|
104
|
+
const headers = new Headers(extra);
|
|
105
|
+
headers.set("content-type", "application/json");
|
|
106
|
+
headers.set("accept", "application/json");
|
|
107
|
+
const response = await (options.fetch ?? fetch)(url, {
|
|
108
|
+
method: "POST",
|
|
109
|
+
headers,
|
|
110
|
+
credentials: options.credentials ?? "same-origin",
|
|
111
|
+
redirect: "error",
|
|
112
|
+
body: JSON.stringify(body),
|
|
113
|
+
...(signal === undefined ? {} : { signal }),
|
|
114
|
+
});
|
|
115
|
+
const data = await response.json().catch(() => null);
|
|
116
|
+
if (!response.ok) {
|
|
117
|
+
const refused = refusalOf(response, data);
|
|
118
|
+
if (refused.code === "not-served") {
|
|
119
|
+
options.onNotServed?.();
|
|
120
|
+
}
|
|
121
|
+
throw refused;
|
|
122
|
+
}
|
|
123
|
+
return { status: response.status, data };
|
|
124
|
+
}
|
|
20
125
|
/** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
|
|
21
126
|
export function httpLocator(url, options = {}) {
|
|
22
127
|
return {
|
|
23
128
|
async locate(instance, signal) {
|
|
24
|
-
const
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
options.onNotServed?.();
|
|
42
|
-
}
|
|
43
|
-
throw new LocateError(typeof error.message === "string"
|
|
44
|
-
? error.message
|
|
45
|
-
: `The app's issue endpoint answered ${response.status}`, response.status, code);
|
|
46
|
-
}
|
|
47
|
-
if (!isRecord(data) ||
|
|
48
|
-
typeof data.url !== "string" ||
|
|
49
|
-
typeof data.origin !== "string" ||
|
|
50
|
-
(data.reports !== undefined && typeof data.reports !== "boolean")) {
|
|
51
|
-
throw new LocateError("The app's issue endpoint gave no frame location", response.status, "bad-location");
|
|
52
|
-
}
|
|
53
|
-
// Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
|
|
54
|
-
const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
|
|
55
|
-
if (data.viewer !== undefined && viewer === null) {
|
|
56
|
-
throw new LocateError("The app's issue endpoint named a viewer that isn't one", response.status, "bad-location");
|
|
57
|
-
}
|
|
58
|
-
return {
|
|
59
|
-
url: data.url,
|
|
60
|
-
origin: data.origin,
|
|
61
|
-
...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
|
|
62
|
-
...(viewer === null ? {} : { viewer }),
|
|
63
|
-
};
|
|
129
|
+
const { status, data } = await askIssue(url, { instance }, options, signal);
|
|
130
|
+
return locationOf(status, data);
|
|
131
|
+
},
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* A locator whose first call answers `location` (one a `resolve` got), once, and every later one
|
|
136
|
+
* asks `then` (P125): bound to the one display that resolved it, so no other view of the same
|
|
137
|
+
* instance can take its tickets, and every run after the first issues afresh.
|
|
138
|
+
*/
|
|
139
|
+
export function oneShot(location, then) {
|
|
140
|
+
let first = location;
|
|
141
|
+
return {
|
|
142
|
+
locate(instance, signal) {
|
|
143
|
+
const given = first;
|
|
144
|
+
first = null;
|
|
145
|
+
return given === null ? then.locate(instance, signal) : Promise.resolve(given);
|
|
64
146
|
},
|
|
65
147
|
};
|
|
66
148
|
}
|
|
149
|
+
/** Whether a value is an instance as an issue endpoint gives it back: `{ scope, document }`. */
|
|
150
|
+
const isInstance = (value) => isRecord(value) &&
|
|
151
|
+
typeof value.scope === "string" &&
|
|
152
|
+
isRecord(value.document) &&
|
|
153
|
+
typeof value.document.kind === "string";
|
|
154
|
+
/**
|
|
155
|
+
* Asks the app's issue endpoint at `url` what the clean address `address` names, for this viewer
|
|
156
|
+
* (`{ address }`, P125). A refusal (401, 403, 404) is an outcome; anything else that isn't a
|
|
157
|
+
* location is thrown, the host's own failure.
|
|
158
|
+
*/
|
|
159
|
+
export async function resolveAddress(url, address, options = {}, signal) {
|
|
160
|
+
let answer;
|
|
161
|
+
try {
|
|
162
|
+
answer = await askIssue(url, { address }, options, signal);
|
|
163
|
+
}
|
|
164
|
+
catch (error) {
|
|
165
|
+
const outcome = outcomeOfRefusal(error);
|
|
166
|
+
if (outcome !== null) {
|
|
167
|
+
return { outcome };
|
|
168
|
+
}
|
|
169
|
+
throw error;
|
|
170
|
+
}
|
|
171
|
+
const { status, data } = answer;
|
|
172
|
+
if (!isRecord(data) || !isInstance(data.instance)) {
|
|
173
|
+
throw new LocateError("The app's issue endpoint resolved the address to no instance", status, "bad-location");
|
|
174
|
+
}
|
|
175
|
+
return { instance: data.instance, location: locationOf(status, data) };
|
|
176
|
+
}
|
|
67
177
|
/**
|
|
68
178
|
* The configs a page's displays run under: served (from the content source) while content is
|
|
69
179
|
* served, opaque otherwise; null while the page doesn't know yet, so a frame never starts opaque
|
package/dist/host/outcome.d.ts
CHANGED
|
@@ -1,8 +1,55 @@
|
|
|
1
1
|
import { type FrameSource } from "../isolation/types.ts";
|
|
2
2
|
import type { Surface } from "../platform/types.ts";
|
|
3
3
|
import type { FrameBlock, FrameOutcome } from "./types.ts";
|
|
4
|
+
/**
|
|
5
|
+
* How a display's first document went (P040). A frame's content is another origin's, so the host
|
|
6
|
+
* can't look inside; it goes by what it can see:
|
|
7
|
+
*
|
|
8
|
+
* - a shell or view that speaks for itself is loaded when it finishes its handshake;
|
|
9
|
+
* - a page of Porthole's `/server` says how it went (`porthole/notifications/frame-status`): it is
|
|
10
|
+
* entering an app, or blocked (its ticket used, no cookie kept in a frame, the app down); a url
|
|
11
|
+
* app is loaded when its document loads after the entry page;
|
|
12
|
+
* - a load from which nothing ever spoke, where something should have, is a page that never ran:
|
|
13
|
+
* framing refused;
|
|
14
|
+
* - an app from a host's own gateway is loaded on its first load, unless its page says it is
|
|
15
|
+
* blocked (the gateway may send the same message);
|
|
16
|
+
* - nothing settled in `timeoutMs`: a timeout.
|
|
17
|
+
*
|
|
18
|
+
* Who may say how loading went (P124). A frame status is taken only from a document of Porthole's
|
|
19
|
+
* server, a host's gateway or the host's own pages, never from content: its words draw the host's
|
|
20
|
+
* fallback, in Porthole's wording, with a link. Nothing in a message tells who sent it (a page
|
|
21
|
+
* that shares the frame's window and origin can send the same bytes), so the host goes by what
|
|
22
|
+
* content can't change: where the frame's documents come from, and in what order they speak.
|
|
23
|
+
*
|
|
24
|
+
* - An opaque frame's only document is the host's own shell, with the content in it: no page of
|
|
25
|
+
* Porthole's server ever loads there, so its every frame status is the content's.
|
|
26
|
+
* - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
|
|
27
|
+
* says Porthole's own word first in every document that holds content, before any of the
|
|
28
|
+
* content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
|
|
29
|
+
* reaches the host before anything its page says, through its shell). A status page says
|
|
30
|
+
* nothing but its frame status. So a frame status is taken only before anything else was heard
|
|
31
|
+
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
32
|
+
* After that, it came from the content (or from a later document, which in a display without
|
|
33
|
+
* files starts the display again, whose first document then says how it went).
|
|
34
|
+
* That holds against the display's own content, not against another display's (P125): a
|
|
35
|
+
* scope's displays share its origin, and one that runs reaches a new document of another's
|
|
36
|
+
* before that document's first script, where it can speak first, or stop or rewrite it so it
|
|
37
|
+
* says nothing. So the rule holds only where no content runs on the frame's origin: a nested
|
|
38
|
+
* page's shell, on a label of its own (P114).
|
|
39
|
+
* - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
|
|
40
|
+
* takes no frame status from its frame at all, and infers nothing from its silence (a load and
|
|
41
|
+
* no word is a timeout, never `framing`): its door said how loading went before the frame was
|
|
42
|
+
* made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
|
|
43
|
+
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
44
|
+
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
45
|
+
*
|
|
46
|
+
* A frame status not taken is dropped, and told once a run to the host (`refused`).
|
|
47
|
+
*/
|
|
48
|
+
/** How long after a load the frame's word may still arrive. */
|
|
49
|
+
export declare const SETTLE_MS = 400;
|
|
4
50
|
interface FrameStatus {
|
|
5
|
-
|
|
51
|
+
/** `open` is a door's word alone (P125): its display may be framed. */
|
|
52
|
+
readonly state: "entering" | "open" | "blocked";
|
|
6
53
|
readonly reason?: FrameBlock;
|
|
7
54
|
readonly status?: number;
|
|
8
55
|
readonly code?: string;
|
|
@@ -21,6 +68,12 @@ export declare function watchOutcome(options: {
|
|
|
21
68
|
readonly source: FrameSource;
|
|
22
69
|
/** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
|
|
23
70
|
readonly speaks: boolean;
|
|
71
|
+
/**
|
|
72
|
+
* The config nests its pages (P111): the frame holds Porthole's shell, on a label no content
|
|
73
|
+
* runs on, whose first word may be a frame status. Any other served frame that speaks takes
|
|
74
|
+
* none: its door told (P125).
|
|
75
|
+
*/
|
|
76
|
+
readonly nested?: boolean;
|
|
24
77
|
readonly timeoutMs: number;
|
|
25
78
|
readonly onOutcome: (outcome: FrameOutcome) => void;
|
|
26
79
|
/** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
|
package/dist/host/outcome.js
CHANGED
|
@@ -29,13 +29,22 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
29
29
|
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
30
30
|
* After that, it came from the content (or from a later document, which in a display without
|
|
31
31
|
* files starts the display again, whose first document then says how it went).
|
|
32
|
+
* That holds against the display's own content, not against another display's (P125): a
|
|
33
|
+
* scope's displays share its origin, and one that runs reaches a new document of another's
|
|
34
|
+
* before that document's first script, where it can speak first, or stop or rewrite it so it
|
|
35
|
+
* says nothing. So the rule holds only where no content runs on the frame's origin: a nested
|
|
36
|
+
* page's shell, on a label of its own (P114).
|
|
37
|
+
* - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
|
|
38
|
+
* takes no frame status from its frame at all, and infers nothing from its silence (a load and
|
|
39
|
+
* no word is a timeout, never `framing`): its door said how loading went before the frame was
|
|
40
|
+
* made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
|
|
32
41
|
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
33
42
|
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
34
43
|
*
|
|
35
44
|
* A frame status not taken is dropped, and told once a run to the host (`refused`).
|
|
36
45
|
*/
|
|
37
46
|
/** How long after a load the frame's word may still arrive. */
|
|
38
|
-
const SETTLE_MS = 400;
|
|
47
|
+
export const SETTLE_MS = 400;
|
|
39
48
|
const BLOCKS = [
|
|
40
49
|
"framing",
|
|
41
50
|
"cookies",
|
|
@@ -59,8 +68,8 @@ export function parseFrameStatus(data) {
|
|
|
59
68
|
if (params === null || typeof params !== "object") {
|
|
60
69
|
return null;
|
|
61
70
|
}
|
|
62
|
-
if (params.state === "entering") {
|
|
63
|
-
return { state:
|
|
71
|
+
if (params.state === "entering" || params.state === "open") {
|
|
72
|
+
return { state: params.state };
|
|
64
73
|
}
|
|
65
74
|
if (params.state !== "blocked") {
|
|
66
75
|
return null;
|
|
@@ -87,6 +96,7 @@ const namesFrameStatus = (data) => data !== null &&
|
|
|
87
96
|
export const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
|
|
88
97
|
export function watchOutcome(options) {
|
|
89
98
|
const { surface, source, speaks } = options;
|
|
99
|
+
const nested = options.nested === true;
|
|
90
100
|
const reports = source.kind === "url" && source.reports === true;
|
|
91
101
|
// The first outcome; after a load, only a later block (a status page, access revoked) is told.
|
|
92
102
|
let decided = null;
|
|
@@ -126,8 +136,8 @@ export function watchOutcome(options) {
|
|
|
126
136
|
options.onOutcome(outcome);
|
|
127
137
|
}
|
|
128
138
|
};
|
|
129
|
-
// Whether a frame status may be the word of a page of Porthole's (P124, above).
|
|
130
|
-
const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
|
|
139
|
+
// Whether a frame status may be the word of a page of Porthole's (P124, P125, above).
|
|
140
|
+
const mayBePorthole = () => source.kind === "url" && (!speaks || (nested && !spoke));
|
|
131
141
|
const unlisten = surface.transport.listen((data) => {
|
|
132
142
|
heard = true;
|
|
133
143
|
if (!namesFrameStatus(data)) {
|
|
@@ -142,6 +152,7 @@ export function watchOutcome(options) {
|
|
|
142
152
|
return;
|
|
143
153
|
}
|
|
144
154
|
const status = parseFrameStatus(data);
|
|
155
|
+
// `open` is a door's word (P125), never a frame's: nothing here.
|
|
145
156
|
if (status?.state === "entering") {
|
|
146
157
|
entering = true;
|
|
147
158
|
}
|
|
@@ -159,16 +170,30 @@ export function watchOutcome(options) {
|
|
|
159
170
|
decide({ state: "blocked", reason: "framing" });
|
|
160
171
|
}
|
|
161
172
|
});
|
|
173
|
+
// A served frame whose door told (P125): a load from which nothing spoke shows nothing, and
|
|
174
|
+
// no one can say why (another display of its scope may have stopped or rewritten it): a timeout,
|
|
175
|
+
// without waiting the whole of it, never `framing`.
|
|
176
|
+
const silent = () => later(SETTLE_MS, () => {
|
|
177
|
+
if (!spoke) {
|
|
178
|
+
decide({ state: "timeout" });
|
|
179
|
+
}
|
|
180
|
+
});
|
|
162
181
|
const unload = surface.onLoad(() => {
|
|
163
182
|
loads += 1;
|
|
164
183
|
if (decided !== null) {
|
|
165
184
|
return;
|
|
166
185
|
}
|
|
167
186
|
if (speaks) {
|
|
168
|
-
// A served shell or view says something before its first load ends;
|
|
169
|
-
// never ran.
|
|
187
|
+
// A served shell or view says something before its first load ends; a nested page's shell
|
|
188
|
+
// that never did never ran. Any other served frame's silence tells nothing (P125). (An
|
|
189
|
+
// opaque srcdoc frame always runs: its handshake decides.)
|
|
170
190
|
if (source.kind === "url") {
|
|
171
|
-
|
|
191
|
+
if (nested) {
|
|
192
|
+
neverRan();
|
|
193
|
+
}
|
|
194
|
+
else {
|
|
195
|
+
silent();
|
|
196
|
+
}
|
|
172
197
|
}
|
|
173
198
|
return;
|
|
174
199
|
}
|
package/dist/host/types.d.ts
CHANGED
|
@@ -121,9 +121,17 @@ export type HostErrorKind =
|
|
|
121
121
|
/**
|
|
122
122
|
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
123
123
|
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
124
|
-
* outcome. Told once a run.
|
|
124
|
+
* outcome. Told once a run. A served display that isn't nested takes none from its frame at
|
|
125
|
+
* all: its door says how loading went (P125).
|
|
125
126
|
*/
|
|
126
|
-
| "frame-status"
|
|
127
|
+
| "frame-status"
|
|
128
|
+
/**
|
|
129
|
+
* A served display that has a door (P125: a served shell, a page that isn't nested, the sandbox
|
|
130
|
+
* proxy) was located without one: the server is older than the host (upgrade it first), or a
|
|
131
|
+
* locator dropped `FrameLocation.door`. The display shows, but no frame status is taken, so a
|
|
132
|
+
* block is told as a timeout. Told once a mount.
|
|
133
|
+
*/
|
|
134
|
+
| "door";
|
|
127
135
|
/** What a display reports, by event name. */
|
|
128
136
|
/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
|
|
129
137
|
export type FrameBlock =
|
package/dist/isolation/served.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { DOOR_PATH } from "./types.js";
|
|
1
2
|
/**
|
|
2
3
|
* Checks for served frames (domain and external isolation), shared by the host's mount and by
|
|
3
4
|
* `/server`: a served origin must be one the config names, and never of the host's own site
|
|
@@ -135,11 +136,45 @@ nested = false) {
|
|
|
135
136
|
if (nested && !onNestedLabel(location.origin)) {
|
|
136
137
|
throw new TypeError(`The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`);
|
|
137
138
|
}
|
|
139
|
+
if (location.door !== undefined) {
|
|
140
|
+
checkDoor(location.door, location.origin, nested);
|
|
141
|
+
}
|
|
138
142
|
const host = parseOrigin(hostOrigin);
|
|
139
143
|
if (host !== null && maybeSameSite(origin.host, host.host)) {
|
|
140
144
|
throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
|
|
141
145
|
}
|
|
142
146
|
}
|
|
147
|
+
/**
|
|
148
|
+
* A location's door (P125): on the location's own origin, at Porthole's door path, never for a
|
|
149
|
+
* nested page (its shell's label serves no door: its first document is Porthole's own, P114).
|
|
150
|
+
* Named by its origin only in what is thrown: the door's address carries a ticket.
|
|
151
|
+
*/
|
|
152
|
+
function checkDoor(door, origin, nested) {
|
|
153
|
+
const url = door !== null && typeof door === "object" ? door.url : undefined;
|
|
154
|
+
if (typeof url !== "string") {
|
|
155
|
+
throw new TypeError("The located door is not { url }");
|
|
156
|
+
}
|
|
157
|
+
if (nested) {
|
|
158
|
+
throw new TypeError("A nested page is located with no door: its shell is Porthole's own first document (P125)");
|
|
159
|
+
}
|
|
160
|
+
let parsed;
|
|
161
|
+
try {
|
|
162
|
+
parsed = new URL(url);
|
|
163
|
+
}
|
|
164
|
+
catch {
|
|
165
|
+
throw new TypeError("The located door is not a URL");
|
|
166
|
+
}
|
|
167
|
+
// The load-bearing check (P125): the door is on the display's own origin, the one its issue
|
|
168
|
+
// located. Its path is pinned below too, for now; a later relaxation of the path (a content
|
|
169
|
+
// Worker's own door route) must keep this check as it is, apart from the path's.
|
|
170
|
+
if (parsed.origin !== origin) {
|
|
171
|
+
throw new TypeError(`The located door is not on its location's origin ${JSON.stringify(origin)} (it is on ${JSON.stringify(safeOrigin(url))})`);
|
|
172
|
+
}
|
|
173
|
+
// Porthole's door route (P125): pinned for now, not what makes the door the display's.
|
|
174
|
+
if (!parsed.pathname.startsWith(DOOR_PATH) || parsed.hash !== "") {
|
|
175
|
+
throw new TypeError(`The located door is not at ${DOOR_PATH}<key> on its origin`);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
143
178
|
/** A URL's origin, for a message: never its path or query (a ticket). */
|
|
144
179
|
function safeOrigin(url) {
|
|
145
180
|
try {
|