@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
package/src/host/locator.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { parseViewer } from "../runtime/levels.ts";
|
|
2
2
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
-
import type { FrameLocation, InstanceLocator } from "../isolation/types.ts";
|
|
3
|
+
import type { FrameLocation, InstanceLocator, InstanceRef } from "../isolation/types.ts";
|
|
4
|
+
import type { FrameOutcome } from "./types.ts";
|
|
4
5
|
|
|
5
6
|
/**
|
|
6
7
|
* The client half of the host kit (P066): a locator that asks the app's issue endpoint
|
|
@@ -9,17 +10,56 @@ import type { FrameLocation, InstanceLocator } from "../isolation/types.ts";
|
|
|
9
10
|
* alone chooses the origin.
|
|
10
11
|
*/
|
|
11
12
|
|
|
12
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …), and
|
|
15
|
+
* for a refusal the host's own reason code where its answer gave one (`error.reason`, P125).
|
|
16
|
+
*/
|
|
13
17
|
export class LocateError extends Error {
|
|
14
18
|
readonly status: number;
|
|
15
19
|
readonly code: string;
|
|
20
|
+
/** The host's reason code from the issue answer's `error.reason` (a short lowercase token). */
|
|
21
|
+
readonly reason?: string;
|
|
16
22
|
|
|
17
|
-
constructor(message: string, status: number, code: string) {
|
|
23
|
+
constructor(message: string, status: number, code: string, reason?: string) {
|
|
18
24
|
super(message);
|
|
19
25
|
this.name = "LocateError";
|
|
20
26
|
this.status = status;
|
|
21
27
|
this.code = code;
|
|
28
|
+
if (reason !== undefined) {
|
|
29
|
+
this.reason = reason;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** A host's reason code, as an outcome's `code` takes it (`FrameOutcome.code`). */
|
|
35
|
+
const REASON_CODE = /^[a-z0-9-]{1,40}$/u;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* What a display shows when the host's own issue endpoint refused it (P125): the host asked before
|
|
39
|
+
* it built any frame, so this is the host's word, never a frame's. Only a refusal maps (401: sign
|
|
40
|
+
* in, 403: denied, with the host's code if its answer gave one, 404: not found); anything else
|
|
41
|
+
* (5xx, a network failure, a malformed answer) is null, the host's own failure (`locate`), never
|
|
42
|
+
* `denied`.
|
|
43
|
+
*/
|
|
44
|
+
export function outcomeOfRefusal(error: unknown): FrameOutcome | null {
|
|
45
|
+
if (!(error instanceof LocateError)) {
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
const code =
|
|
49
|
+
error.reason !== undefined && REASON_CODE.test(error.reason) ? { code: error.reason } : {};
|
|
50
|
+
// Only the issue endpoint's own refusal, by its shape (`{ error: { code } }` with the code that
|
|
51
|
+
// goes with its status): a bare 401, 403 or 404 from a router or a firewall in front of it is no
|
|
52
|
+
// answer of the host's, so it stays the host's own failure (`locate`).
|
|
53
|
+
if (error.status === 401 && error.code === "unauthenticated") {
|
|
54
|
+
return { state: "blocked", reason: "sign-in", status: 401 };
|
|
55
|
+
}
|
|
56
|
+
if (error.status === 403 && error.code === "forbidden") {
|
|
57
|
+
return { state: "blocked", reason: "denied", status: 403, ...code };
|
|
58
|
+
}
|
|
59
|
+
if (error.status === 404 && error.code === "not-found") {
|
|
60
|
+
return { state: "blocked", reason: "not-found", status: 404 };
|
|
22
61
|
}
|
|
62
|
+
return null;
|
|
23
63
|
}
|
|
24
64
|
|
|
25
65
|
export interface HttpLocatorOptions {
|
|
@@ -35,68 +75,179 @@ export interface HttpLocatorOptions {
|
|
|
35
75
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
36
76
|
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
37
77
|
|
|
78
|
+
/**
|
|
79
|
+
* A location's door as an issue endpoint answered it (P125): passed on as it came, checked with the
|
|
80
|
+
* location before any frame is made (`checkFrameLocation`); null for none, "bad" for one that
|
|
81
|
+
* isn't `{ url: string }`.
|
|
82
|
+
*/
|
|
83
|
+
export function doorOf(data: Record<string, unknown>): { readonly url: string } | null | "bad" {
|
|
84
|
+
if (data.door === undefined) {
|
|
85
|
+
return null;
|
|
86
|
+
}
|
|
87
|
+
return isRecord(data.door) && typeof data.door.url === "string" ? { url: data.door.url } : "bad";
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The refusal an issue endpoint answered: its message, status, code and the host's reason. */
|
|
91
|
+
export function refusalOf(response: { readonly status: number }, data: unknown): LocateError {
|
|
92
|
+
const error = isRecord(data) && isRecord(data.error) ? data.error : {};
|
|
93
|
+
const code = typeof error.code === "string" ? error.code : "failed";
|
|
94
|
+
const reason =
|
|
95
|
+
typeof error.reason === "string" && REASON_CODE.test(error.reason) ? error.reason : undefined;
|
|
96
|
+
return new LocateError(
|
|
97
|
+
typeof error.message === "string"
|
|
98
|
+
? error.message
|
|
99
|
+
: `The app's issue endpoint answered ${response.status}`,
|
|
100
|
+
response.status,
|
|
101
|
+
code,
|
|
102
|
+
reason,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** A frame location as an issue endpoint answered it, checked in shape; throws a `LocateError`. */
|
|
107
|
+
export function locationOf(status: number, data: unknown): FrameLocation {
|
|
108
|
+
if (
|
|
109
|
+
!isRecord(data) ||
|
|
110
|
+
typeof data.url !== "string" ||
|
|
111
|
+
typeof data.origin !== "string" ||
|
|
112
|
+
(data.reports !== undefined && typeof data.reports !== "boolean")
|
|
113
|
+
) {
|
|
114
|
+
throw new LocateError(
|
|
115
|
+
"The app's issue endpoint gave no frame location",
|
|
116
|
+
status,
|
|
117
|
+
"bad-location",
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
// Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
|
|
121
|
+
const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
|
|
122
|
+
if (data.viewer !== undefined && viewer === null) {
|
|
123
|
+
throw new LocateError(
|
|
124
|
+
"The app's issue endpoint named a viewer that isn't one",
|
|
125
|
+
status,
|
|
126
|
+
"bad-location",
|
|
127
|
+
);
|
|
128
|
+
}
|
|
129
|
+
const door = doorOf(data);
|
|
130
|
+
if (door === "bad") {
|
|
131
|
+
throw new LocateError(
|
|
132
|
+
"The app's issue endpoint named a door that isn't one",
|
|
133
|
+
status,
|
|
134
|
+
"bad-location",
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
return {
|
|
138
|
+
url: data.url,
|
|
139
|
+
origin: data.origin,
|
|
140
|
+
...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
|
|
141
|
+
...(viewer === null ? {} : { viewer }),
|
|
142
|
+
...(door === null ? {} : { door }),
|
|
143
|
+
} satisfies FrameLocation;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** POSTs `body` to the app's issue endpoint at `url`: its answer's JSON, or the refusal thrown. */
|
|
147
|
+
async function askIssue(
|
|
148
|
+
url: string,
|
|
149
|
+
body: Record<string, unknown>,
|
|
150
|
+
options: HttpLocatorOptions,
|
|
151
|
+
signal?: AbortSignal,
|
|
152
|
+
): Promise<{ readonly status: number; readonly data: unknown }> {
|
|
153
|
+
const extra = typeof options.headers === "function" ? options.headers() : options.headers;
|
|
154
|
+
const headers = new Headers(extra);
|
|
155
|
+
headers.set("content-type", "application/json");
|
|
156
|
+
headers.set("accept", "application/json");
|
|
157
|
+
const response = await (options.fetch ?? fetch)(url, {
|
|
158
|
+
method: "POST",
|
|
159
|
+
headers,
|
|
160
|
+
credentials: options.credentials ?? "same-origin",
|
|
161
|
+
redirect: "error",
|
|
162
|
+
body: JSON.stringify(body),
|
|
163
|
+
...(signal === undefined ? {} : { signal }),
|
|
164
|
+
});
|
|
165
|
+
const data: unknown = await response.json().catch(() => null);
|
|
166
|
+
if (!response.ok) {
|
|
167
|
+
const refused = refusalOf(response, data);
|
|
168
|
+
if (refused.code === "not-served") {
|
|
169
|
+
options.onNotServed?.();
|
|
170
|
+
}
|
|
171
|
+
throw refused;
|
|
172
|
+
}
|
|
173
|
+
return { status: response.status, data };
|
|
174
|
+
}
|
|
175
|
+
|
|
38
176
|
/** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
|
|
39
177
|
export function httpLocator(url: string, options: HttpLocatorOptions = {}): InstanceLocator {
|
|
40
178
|
return {
|
|
41
179
|
async locate(instance, signal) {
|
|
42
|
-
const
|
|
43
|
-
|
|
44
|
-
headers.set("content-type", "application/json");
|
|
45
|
-
headers.set("accept", "application/json");
|
|
46
|
-
const response = await (options.fetch ?? fetch)(url, {
|
|
47
|
-
method: "POST",
|
|
48
|
-
headers,
|
|
49
|
-
credentials: options.credentials ?? "same-origin",
|
|
50
|
-
redirect: "error",
|
|
51
|
-
body: JSON.stringify({ instance }),
|
|
52
|
-
...(signal === undefined ? {} : { signal }),
|
|
53
|
-
});
|
|
54
|
-
const data: unknown = await response.json().catch(() => null);
|
|
55
|
-
if (!response.ok) {
|
|
56
|
-
const error = isRecord(data) && isRecord(data.error) ? data.error : {};
|
|
57
|
-
const code = typeof error.code === "string" ? error.code : "failed";
|
|
58
|
-
if (code === "not-served") {
|
|
59
|
-
options.onNotServed?.();
|
|
60
|
-
}
|
|
61
|
-
throw new LocateError(
|
|
62
|
-
typeof error.message === "string"
|
|
63
|
-
? error.message
|
|
64
|
-
: `The app's issue endpoint answered ${response.status}`,
|
|
65
|
-
response.status,
|
|
66
|
-
code,
|
|
67
|
-
);
|
|
68
|
-
}
|
|
69
|
-
if (
|
|
70
|
-
!isRecord(data) ||
|
|
71
|
-
typeof data.url !== "string" ||
|
|
72
|
-
typeof data.origin !== "string" ||
|
|
73
|
-
(data.reports !== undefined && typeof data.reports !== "boolean")
|
|
74
|
-
) {
|
|
75
|
-
throw new LocateError(
|
|
76
|
-
"The app's issue endpoint gave no frame location",
|
|
77
|
-
response.status,
|
|
78
|
-
"bad-location",
|
|
79
|
-
);
|
|
80
|
-
}
|
|
81
|
-
// Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
|
|
82
|
-
const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
|
|
83
|
-
if (data.viewer !== undefined && viewer === null) {
|
|
84
|
-
throw new LocateError(
|
|
85
|
-
"The app's issue endpoint named a viewer that isn't one",
|
|
86
|
-
response.status,
|
|
87
|
-
"bad-location",
|
|
88
|
-
);
|
|
89
|
-
}
|
|
90
|
-
return {
|
|
91
|
-
url: data.url,
|
|
92
|
-
origin: data.origin,
|
|
93
|
-
...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
|
|
94
|
-
...(viewer === null ? {} : { viewer }),
|
|
95
|
-
} satisfies FrameLocation;
|
|
180
|
+
const { status, data } = await askIssue(url, { instance }, options, signal);
|
|
181
|
+
return locationOf(status, data);
|
|
96
182
|
},
|
|
97
183
|
};
|
|
98
184
|
}
|
|
99
185
|
|
|
186
|
+
/**
|
|
187
|
+
* What a clean address resolves to (P125): its instance and an issued location for it (a ticket,
|
|
188
|
+
* a door), or the outcome the host's issue endpoint answered instead (signed out, denied, not
|
|
189
|
+
* found), before any frame is built. A clean address is for a tab; a frame shows what it names
|
|
190
|
+
* through `issue`.
|
|
191
|
+
*/
|
|
192
|
+
export type Resolved =
|
|
193
|
+
| { readonly instance: InstanceRef; readonly location: FrameLocation }
|
|
194
|
+
| { readonly outcome: FrameOutcome };
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* A locator whose first call answers `location` (one a `resolve` got), once, and every later one
|
|
198
|
+
* asks `then` (P125): bound to the one display that resolved it, so no other view of the same
|
|
199
|
+
* instance can take its tickets, and every run after the first issues afresh.
|
|
200
|
+
*/
|
|
201
|
+
export function oneShot(location: FrameLocation, then: InstanceLocator): InstanceLocator {
|
|
202
|
+
let first: FrameLocation | null = location;
|
|
203
|
+
return {
|
|
204
|
+
locate(instance, signal) {
|
|
205
|
+
const given = first;
|
|
206
|
+
first = null;
|
|
207
|
+
return given === null ? then.locate(instance, signal) : Promise.resolve(given);
|
|
208
|
+
},
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** Whether a value is an instance as an issue endpoint gives it back: `{ scope, document }`. */
|
|
213
|
+
const isInstance = (value: unknown): value is InstanceRef =>
|
|
214
|
+
isRecord(value) &&
|
|
215
|
+
typeof value.scope === "string" &&
|
|
216
|
+
isRecord(value.document) &&
|
|
217
|
+
typeof value.document.kind === "string";
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Asks the app's issue endpoint at `url` what the clean address `address` names, for this viewer
|
|
221
|
+
* (`{ address }`, P125). A refusal (401, 403, 404) is an outcome; anything else that isn't a
|
|
222
|
+
* location is thrown, the host's own failure.
|
|
223
|
+
*/
|
|
224
|
+
export async function resolveAddress(
|
|
225
|
+
url: string,
|
|
226
|
+
address: string,
|
|
227
|
+
options: HttpLocatorOptions = {},
|
|
228
|
+
signal?: AbortSignal,
|
|
229
|
+
): Promise<Resolved> {
|
|
230
|
+
let answer: { readonly status: number; readonly data: unknown };
|
|
231
|
+
try {
|
|
232
|
+
answer = await askIssue(url, { address }, options, signal);
|
|
233
|
+
} catch (error) {
|
|
234
|
+
const outcome = outcomeOfRefusal(error);
|
|
235
|
+
if (outcome !== null) {
|
|
236
|
+
return { outcome };
|
|
237
|
+
}
|
|
238
|
+
throw error;
|
|
239
|
+
}
|
|
240
|
+
const { status, data } = answer;
|
|
241
|
+
if (!isRecord(data) || !isInstance(data.instance)) {
|
|
242
|
+
throw new LocateError(
|
|
243
|
+
"The app's issue endpoint resolved the address to no instance",
|
|
244
|
+
status,
|
|
245
|
+
"bad-location",
|
|
246
|
+
);
|
|
247
|
+
}
|
|
248
|
+
return { instance: data.instance, location: locationOf(status, data) };
|
|
249
|
+
}
|
|
250
|
+
|
|
100
251
|
/** What the page knows of content (`ContentHost.meta`, as the app's own meta carries it). */
|
|
101
252
|
export interface ServedMeta {
|
|
102
253
|
readonly served: boolean;
|
package/src/host/outcome.ts
CHANGED
|
@@ -32,6 +32,15 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
|
|
|
32
32
|
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
33
33
|
* After that, it came from the content (or from a later document, which in a display without
|
|
34
34
|
* files starts the display again, whose first document then says how it went).
|
|
35
|
+
* That holds against the display's own content, not against another display's (P125): a
|
|
36
|
+
* scope's displays share its origin, and one that runs reaches a new document of another's
|
|
37
|
+
* before that document's first script, where it can speak first, or stop or rewrite it so it
|
|
38
|
+
* says nothing. So the rule holds only where no content runs on the frame's origin: a nested
|
|
39
|
+
* page's shell, on a label of its own (P114).
|
|
40
|
+
* - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
|
|
41
|
+
* takes no frame status from its frame at all, and infers nothing from its silence (a load and
|
|
42
|
+
* no word is a timeout, never `framing`): its door said how loading went before the frame was
|
|
43
|
+
* made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
|
|
35
44
|
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
36
45
|
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
37
46
|
*
|
|
@@ -39,7 +48,7 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
|
|
|
39
48
|
*/
|
|
40
49
|
|
|
41
50
|
/** How long after a load the frame's word may still arrive. */
|
|
42
|
-
const SETTLE_MS = 400;
|
|
51
|
+
export const SETTLE_MS = 400;
|
|
43
52
|
|
|
44
53
|
const BLOCKS: readonly FrameBlock[] = [
|
|
45
54
|
"framing",
|
|
@@ -53,7 +62,8 @@ const BLOCKS: readonly FrameBlock[] = [
|
|
|
53
62
|
];
|
|
54
63
|
|
|
55
64
|
interface FrameStatus {
|
|
56
|
-
|
|
65
|
+
/** `open` is a door's word alone (P125): its display may be framed. */
|
|
66
|
+
readonly state: "entering" | "open" | "blocked";
|
|
57
67
|
readonly reason?: FrameBlock;
|
|
58
68
|
readonly status?: number;
|
|
59
69
|
readonly code?: string;
|
|
@@ -77,8 +87,8 @@ export function parseFrameStatus(data: unknown): FrameStatus | null {
|
|
|
77
87
|
if (params === null || typeof params !== "object") {
|
|
78
88
|
return null;
|
|
79
89
|
}
|
|
80
|
-
if (params.state === "entering") {
|
|
81
|
-
return { state:
|
|
90
|
+
if (params.state === "entering" || params.state === "open") {
|
|
91
|
+
return { state: params.state };
|
|
82
92
|
}
|
|
83
93
|
if (params.state !== "blocked") {
|
|
84
94
|
return null;
|
|
@@ -119,12 +129,19 @@ export function watchOutcome(options: {
|
|
|
119
129
|
readonly source: FrameSource;
|
|
120
130
|
/** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
|
|
121
131
|
readonly speaks: boolean;
|
|
132
|
+
/**
|
|
133
|
+
* The config nests its pages (P111): the frame holds Porthole's shell, on a label no content
|
|
134
|
+
* runs on, whose first word may be a frame status. Any other served frame that speaks takes
|
|
135
|
+
* none: its door told (P125).
|
|
136
|
+
*/
|
|
137
|
+
readonly nested?: boolean;
|
|
122
138
|
readonly timeoutMs: number;
|
|
123
139
|
readonly onOutcome: (outcome: FrameOutcome) => void;
|
|
124
140
|
/** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
|
|
125
141
|
readonly refused?: (message: string) => void;
|
|
126
142
|
}): OutcomeWatch {
|
|
127
143
|
const { surface, source, speaks } = options;
|
|
144
|
+
const nested = options.nested === true;
|
|
128
145
|
const reports = source.kind === "url" && source.reports === true;
|
|
129
146
|
// The first outcome; after a load, only a later block (a status page, access revoked) is told.
|
|
130
147
|
let decided: FrameOutcome["state"] | null = null;
|
|
@@ -163,8 +180,8 @@ export function watchOutcome(options: {
|
|
|
163
180
|
options.onOutcome(outcome);
|
|
164
181
|
}
|
|
165
182
|
};
|
|
166
|
-
// Whether a frame status may be the word of a page of Porthole's (P124, above).
|
|
167
|
-
const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
|
|
183
|
+
// Whether a frame status may be the word of a page of Porthole's (P124, P125, above).
|
|
184
|
+
const mayBePorthole = () => source.kind === "url" && (!speaks || (nested && !spoke));
|
|
168
185
|
const unlisten = surface.transport.listen((data) => {
|
|
169
186
|
heard = true;
|
|
170
187
|
if (!namesFrameStatus(data)) {
|
|
@@ -179,6 +196,7 @@ export function watchOutcome(options: {
|
|
|
179
196
|
return;
|
|
180
197
|
}
|
|
181
198
|
const status = parseFrameStatus(data);
|
|
199
|
+
// `open` is a door's word (P125), never a frame's: nothing here.
|
|
182
200
|
if (status?.state === "entering") {
|
|
183
201
|
entering = true;
|
|
184
202
|
} else if (status?.state === "blocked") {
|
|
@@ -196,16 +214,30 @@ export function watchOutcome(options: {
|
|
|
196
214
|
decide({ state: "blocked", reason: "framing" });
|
|
197
215
|
}
|
|
198
216
|
});
|
|
217
|
+
// A served frame whose door told (P125): a load from which nothing spoke shows nothing, and
|
|
218
|
+
// no one can say why (another display of its scope may have stopped or rewritten it): a timeout,
|
|
219
|
+
// without waiting the whole of it, never `framing`.
|
|
220
|
+
const silent = () =>
|
|
221
|
+
later(SETTLE_MS, () => {
|
|
222
|
+
if (!spoke) {
|
|
223
|
+
decide({ state: "timeout" });
|
|
224
|
+
}
|
|
225
|
+
});
|
|
199
226
|
const unload = surface.onLoad(() => {
|
|
200
227
|
loads += 1;
|
|
201
228
|
if (decided !== null) {
|
|
202
229
|
return;
|
|
203
230
|
}
|
|
204
231
|
if (speaks) {
|
|
205
|
-
// A served shell or view says something before its first load ends;
|
|
206
|
-
// never ran.
|
|
232
|
+
// A served shell or view says something before its first load ends; a nested page's shell
|
|
233
|
+
// that never did never ran. Any other served frame's silence tells nothing (P125). (An
|
|
234
|
+
// opaque srcdoc frame always runs: its handshake decides.)
|
|
207
235
|
if (source.kind === "url") {
|
|
208
|
-
|
|
236
|
+
if (nested) {
|
|
237
|
+
neverRan();
|
|
238
|
+
} else {
|
|
239
|
+
silent();
|
|
240
|
+
}
|
|
209
241
|
}
|
|
210
242
|
return;
|
|
211
243
|
}
|
package/src/host/types.ts
CHANGED
|
@@ -129,9 +129,17 @@ export type HostErrorKind =
|
|
|
129
129
|
/**
|
|
130
130
|
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
131
131
|
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
132
|
-
* outcome. Told once a run.
|
|
132
|
+
* outcome. Told once a run. A served display that isn't nested takes none from its frame at
|
|
133
|
+
* all: its door says how loading went (P125).
|
|
133
134
|
*/
|
|
134
|
-
| "frame-status"
|
|
135
|
+
| "frame-status"
|
|
136
|
+
/**
|
|
137
|
+
* A served display that has a door (P125: a served shell, a page that isn't nested, the sandbox
|
|
138
|
+
* proxy) was located without one: the server is older than the host (upgrade it first), or a
|
|
139
|
+
* locator dropped `FrameLocation.door`. The display shows, but no frame status is taken, so a
|
|
140
|
+
* block is told as a timeout. Told once a mount.
|
|
141
|
+
*/
|
|
142
|
+
| "door";
|
|
135
143
|
|
|
136
144
|
/** What a display reports, by event name. */
|
|
137
145
|
/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
|
package/src/isolation/served.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { DOOR_PATH, type FrameLocation } from "./types.ts";
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* Checks for served frames (domain and external isolation), shared by the host's mount and by
|
|
@@ -172,6 +172,9 @@ export function checkFrameLocation(
|
|
|
172
172
|
`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`,
|
|
173
173
|
);
|
|
174
174
|
}
|
|
175
|
+
if (location.door !== undefined) {
|
|
176
|
+
checkDoor(location.door, location.origin, nested);
|
|
177
|
+
}
|
|
175
178
|
const host = parseOrigin(hostOrigin);
|
|
176
179
|
if (host !== null && maybeSameSite(origin.host, host.host)) {
|
|
177
180
|
throw new TypeError(
|
|
@@ -180,6 +183,42 @@ export function checkFrameLocation(
|
|
|
180
183
|
}
|
|
181
184
|
}
|
|
182
185
|
|
|
186
|
+
/**
|
|
187
|
+
* A location's door (P125): on the location's own origin, at Porthole's door path, never for a
|
|
188
|
+
* nested page (its shell's label serves no door: its first document is Porthole's own, P114).
|
|
189
|
+
* Named by its origin only in what is thrown: the door's address carries a ticket.
|
|
190
|
+
*/
|
|
191
|
+
function checkDoor(door: unknown, origin: string, nested: boolean): void {
|
|
192
|
+
const url =
|
|
193
|
+
door !== null && typeof door === "object" ? (door as { url?: unknown }).url : undefined;
|
|
194
|
+
if (typeof url !== "string") {
|
|
195
|
+
throw new TypeError("The located door is not { url }");
|
|
196
|
+
}
|
|
197
|
+
if (nested) {
|
|
198
|
+
throw new TypeError(
|
|
199
|
+
"A nested page is located with no door: its shell is Porthole's own first document (P125)",
|
|
200
|
+
);
|
|
201
|
+
}
|
|
202
|
+
let parsed: URL;
|
|
203
|
+
try {
|
|
204
|
+
parsed = new URL(url);
|
|
205
|
+
} catch {
|
|
206
|
+
throw new TypeError("The located door is not a URL");
|
|
207
|
+
}
|
|
208
|
+
// The load-bearing check (P125): the door is on the display's own origin, the one its issue
|
|
209
|
+
// located. Its path is pinned below too, for now; a later relaxation of the path (a content
|
|
210
|
+
// Worker's own door route) must keep this check as it is, apart from the path's.
|
|
211
|
+
if (parsed.origin !== origin) {
|
|
212
|
+
throw new TypeError(
|
|
213
|
+
`The located door is not on its location's origin ${JSON.stringify(origin)} (it is on ${JSON.stringify(safeOrigin(url))})`,
|
|
214
|
+
);
|
|
215
|
+
}
|
|
216
|
+
// Porthole's door route (P125): pinned for now, not what makes the door the display's.
|
|
217
|
+
if (!parsed.pathname.startsWith(DOOR_PATH) || parsed.hash !== "") {
|
|
218
|
+
throw new TypeError(`The located door is not at ${DOOR_PATH}<key> on its origin`);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
|
|
183
222
|
/** A URL's origin, for a message: never its path or query (a ticket). */
|
|
184
223
|
function safeOrigin(url: string): string {
|
|
185
224
|
try {
|
package/src/isolation/types.ts
CHANGED
|
@@ -69,8 +69,22 @@ export interface FrameLocation {
|
|
|
69
69
|
* the display's bridge checks each runtime method's level against it.
|
|
70
70
|
*/
|
|
71
71
|
readonly viewer?: ViewerInfo;
|
|
72
|
+
/**
|
|
73
|
+
* The display's door (P125): a page of Porthole's on the same origin, at
|
|
74
|
+
* `/__porthole/door/<instance key>?ticket=<its own ticket>`, that says how loading went before
|
|
75
|
+
* any content is framed. The host frames it opaque and hidden, and takes its one frame status
|
|
76
|
+
* (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page that isn't
|
|
77
|
+
* nested and the sandbox proxy: content of the scope runs on their origin, so no frame status
|
|
78
|
+
* from their own frame is ever Porthole's. A host that is given none for one of them takes no
|
|
79
|
+
* frame status at all (a load that shows nothing is a timeout) and says so (`hostError` kind
|
|
80
|
+
* `door`). A custom locator passes it on as it came.
|
|
81
|
+
*/
|
|
82
|
+
readonly door?: { readonly url: string };
|
|
72
83
|
}
|
|
73
84
|
|
|
85
|
+
/** Where a served display's door is (P125): `<origin>/__porthole/door/<instance key>`. */
|
|
86
|
+
export const DOOR_PATH = "/__porthole/door/";
|
|
87
|
+
|
|
74
88
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
75
89
|
export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
76
90
|
|
|
@@ -94,8 +108,9 @@ export const STORAGE_USED_METHOD = "porthole/storage-used";
|
|
|
94
108
|
|
|
95
109
|
/**
|
|
96
110
|
* Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
|
|
97
|
-
* own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called
|
|
98
|
-
* mount
|
|
111
|
+
* own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called for every
|
|
112
|
+
* run (a mount, a reload, a restart after the content navigated away): answer each with a fresh
|
|
113
|
+
* issue, since a ticket and a door ticket are each good once (P125).
|
|
99
114
|
*/
|
|
100
115
|
export interface InstanceLocator {
|
|
101
116
|
locate(instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
|
|
@@ -114,4 +129,6 @@ export type FrameSource =
|
|
|
114
129
|
readonly reports?: boolean;
|
|
115
130
|
/** The issue's viewer (`FrameLocation.viewer`), for the display's bridge. */
|
|
116
131
|
readonly viewer?: ViewerInfo;
|
|
132
|
+
/** The display's door (`FrameLocation.door`, P125): framed before `url`. */
|
|
133
|
+
readonly door?: string;
|
|
117
134
|
};
|
package/src/platform/types.ts
CHANGED
|
@@ -80,8 +80,29 @@ export interface Surface {
|
|
|
80
80
|
destroy(): void;
|
|
81
81
|
}
|
|
82
82
|
|
|
83
|
+
/**
|
|
84
|
+
* A served display's door (P125): a hidden frame of the host's own at the door's address,
|
|
85
|
+
* sandboxed with scripts alone (an opaque origin no content shares), with no `allow`, no name, out
|
|
86
|
+
* of focus and of the accessibility tree. Its one frame status is heard from its window and the
|
|
87
|
+
* opaque origin (`"null"`) alone.
|
|
88
|
+
*/
|
|
89
|
+
export interface DoorSurface {
|
|
90
|
+
readonly transport: Transport;
|
|
91
|
+
/** The platform's own element for the door (an `HTMLIFrameElement` on the web). */
|
|
92
|
+
readonly element: unknown;
|
|
93
|
+
/** Every load of the door's document. */
|
|
94
|
+
onLoad(listener: () => void): () => void;
|
|
95
|
+
destroy(): void;
|
|
96
|
+
}
|
|
97
|
+
|
|
83
98
|
export interface PlatformHost<Container = HTMLElement> {
|
|
84
99
|
readonly name: string;
|
|
85
100
|
/** Creates an isolated frame in `container`, its policy set before its document loads. */
|
|
86
101
|
createSurface(container: Container, spec: SurfaceSpec): Surface;
|
|
102
|
+
/**
|
|
103
|
+
* Creates a served display's door in `container` (P125), loading `url`. A platform without one
|
|
104
|
+
* shows served displays that have a door without it: no frame status is taken from them, and
|
|
105
|
+
* the host hears a `door` host error.
|
|
106
|
+
*/
|
|
107
|
+
createDoor?(container: Container, spec: { readonly url: string }): DoorSurface;
|
|
87
108
|
}
|
package/src/platform/web.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
+
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
1
2
|
import type { ColorScheme } from "../config/schema.ts";
|
|
2
3
|
import {
|
|
3
|
-
FRAME_STATUS_METHOD,
|
|
4
4
|
SHELL_BEAT_METHOD,
|
|
5
5
|
SHELL_LOOK_METHOD,
|
|
6
6
|
SHELL_METHOD_PREFIX,
|
|
@@ -9,14 +9,7 @@ import {
|
|
|
9
9
|
import { postMessageTransport } from "../transport/post-message.ts";
|
|
10
10
|
import { focusGuard, type FocusGuard, type FocusTake } from "./focus-guard.ts";
|
|
11
11
|
import type { Transport } from "../transport/types.ts";
|
|
12
|
-
import type { PlatformHost, Surface, SurfaceSpec } from "./types.ts";
|
|
13
|
-
|
|
14
|
-
/** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
|
|
15
|
-
const isFrameStatus = (data: unknown): boolean =>
|
|
16
|
-
data !== null &&
|
|
17
|
-
typeof data === "object" &&
|
|
18
|
-
(data as { jsonrpc?: unknown }).jsonrpc === "2.0" &&
|
|
19
|
-
(data as { method?: unknown }).method === FRAME_STATUS_METHOD;
|
|
12
|
+
import type { DoorSurface, PlatformHost, Surface, SurfaceSpec } from "./types.ts";
|
|
20
13
|
|
|
21
14
|
/** A shell's own message (P111), by its namespace. */
|
|
22
15
|
const isShellWord = (data: unknown): data is { method: string; params?: unknown } =>
|
|
@@ -139,17 +132,10 @@ export const webPlatform: PlatformHost = {
|
|
|
139
132
|
const guard = focusGuard(view);
|
|
140
133
|
const taken = new Set<(take: FocusTake) => void>();
|
|
141
134
|
const nested = spec.nested === true && spec.source.kind === "url";
|
|
142
|
-
// A
|
|
143
|
-
//
|
|
144
|
-
|
|
145
|
-
const opened = postMessageTransport(
|
|
146
|
-
() => frame.contentWindow,
|
|
147
|
-
origin,
|
|
148
|
-
view,
|
|
149
|
-
origin === "null" || own === "null" || own === origin
|
|
150
|
-
? undefined
|
|
151
|
-
: { origin: own, accept: isFrameStatus },
|
|
152
|
-
);
|
|
135
|
+
// A frame is heard from its own window and its located origin alone: never the host's own
|
|
136
|
+
// origin (P125 removed P068's in-frame pages and the channel that heard them), so no page of
|
|
137
|
+
// the host's own can speak for a frame either.
|
|
138
|
+
const opened = postMessageTransport(() => frame.contentWindow, origin, view);
|
|
153
139
|
const unguard = guard.add(
|
|
154
140
|
frame,
|
|
155
141
|
(take) => {
|
|
@@ -227,4 +213,53 @@ export const webPlatform: PlatformHost = {
|
|
|
227
213
|
},
|
|
228
214
|
};
|
|
229
215
|
},
|
|
216
|
+
/**
|
|
217
|
+
* A served display's door (P125): hidden (no size, `visibility: hidden`, which still runs its
|
|
218
|
+
* script and fires its load on all three engines), out of focus and of the accessibility tree,
|
|
219
|
+
* sandboxed with scripts alone, no `allow`, no name. Nothing but its frame status is heard from
|
|
220
|
+
* it, from its window and the opaque origin alone; the focus guard, the bridge and annotations
|
|
221
|
+
* never see it.
|
|
222
|
+
*/
|
|
223
|
+
createDoor(container: HTMLElement, spec: { readonly url: string }): DoorSurface {
|
|
224
|
+
// oxlint-disable-next-line react/iframe-missing-sandbox -- set from the door's list, next
|
|
225
|
+
const frame = container.ownerDocument.createElement("iframe");
|
|
226
|
+
frame.setAttribute("sandbox", DOOR_SANDBOX_TOKENS.join(" "));
|
|
227
|
+
frame.setAttribute("allow", "");
|
|
228
|
+
frame.setAttribute("referrerpolicy", "no-referrer");
|
|
229
|
+
frame.setAttribute("aria-hidden", "true");
|
|
230
|
+
frame.setAttribute("tabindex", "-1");
|
|
231
|
+
frame.setAttribute("inert", "");
|
|
232
|
+
frame.setAttribute("loading", "eager");
|
|
233
|
+
frame.dataset.portholeDoor = "";
|
|
234
|
+
Object.assign(frame.style, {
|
|
235
|
+
display: "block",
|
|
236
|
+
width: "0",
|
|
237
|
+
height: "0",
|
|
238
|
+
border: "0",
|
|
239
|
+
visibility: "hidden",
|
|
240
|
+
});
|
|
241
|
+
frame.src = spec.url;
|
|
242
|
+
const loaded = new Set<() => void>();
|
|
243
|
+
frame.addEventListener("load", () => {
|
|
244
|
+
for (const listener of loaded) {
|
|
245
|
+
listener();
|
|
246
|
+
}
|
|
247
|
+
});
|
|
248
|
+
container.append(frame);
|
|
249
|
+
const view = container.ownerDocument.defaultView ?? window;
|
|
250
|
+
const transport = postMessageTransport(() => frame.contentWindow, "null", view);
|
|
251
|
+
return {
|
|
252
|
+
transport,
|
|
253
|
+
element: frame,
|
|
254
|
+
onLoad(listener) {
|
|
255
|
+
loaded.add(listener);
|
|
256
|
+
return () => loaded.delete(listener);
|
|
257
|
+
},
|
|
258
|
+
destroy() {
|
|
259
|
+
loaded.clear();
|
|
260
|
+
transport.close();
|
|
261
|
+
frame.remove();
|
|
262
|
+
},
|
|
263
|
+
};
|
|
264
|
+
},
|
|
230
265
|
};
|