@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
|
@@ -30,12 +30,26 @@ function invoke(page, method, ...args) {
|
|
|
30
30
|
}, [method, args]);
|
|
31
31
|
}
|
|
32
32
|
/** The display's frame element's document, once it exists. */
|
|
33
|
+
/** A display's first outcome, once it has one (P040, P125). */
|
|
34
|
+
async function outcomeOf(page, id) {
|
|
35
|
+
let found = null;
|
|
36
|
+
await expect
|
|
37
|
+
.poll(async () => {
|
|
38
|
+
const events = await invoke(page, "events", id);
|
|
39
|
+
const each = events.find((event) => event.type === "outcome");
|
|
40
|
+
found = each === undefined ? null : each.detail;
|
|
41
|
+
return found !== null;
|
|
42
|
+
}, { message: "the display has an outcome", timeout: 15_000 })
|
|
43
|
+
.toBe(true);
|
|
44
|
+
return found;
|
|
45
|
+
}
|
|
33
46
|
async function frameIn(page, id) {
|
|
34
47
|
let found = null;
|
|
35
48
|
await expect
|
|
36
49
|
.poll(async () => {
|
|
37
50
|
const element = await page
|
|
38
|
-
|
|
51
|
+
// The display's own frame, never its door (P125), which is gone once it said its word.
|
|
52
|
+
.locator(`#porthole-display-${id} iframe:not([data-porthole-door])`)
|
|
39
53
|
.elementHandle({ timeout: 2_000 })
|
|
40
54
|
.catch(() => null);
|
|
41
55
|
found = (await element?.contentFrame()) ?? null;
|
|
@@ -223,24 +237,35 @@ export function hostConformance(options) {
|
|
|
223
237
|
: given.unknown,
|
|
224
238
|
}),
|
|
225
239
|
async frame(page, url) {
|
|
240
|
+
await ready(page);
|
|
241
|
+
if (options.issue === undefined) {
|
|
242
|
+
throw new Error("A clean address is framed through the app's issue endpoint ({ address }, P125): give defineHostConformance its issue");
|
|
243
|
+
}
|
|
244
|
+
const instance = await served.artifact("entry", "1");
|
|
245
|
+
const id = await invoke(page, "showAddress", configOf(instance), {
|
|
246
|
+
issue: options.issue.url,
|
|
247
|
+
...(options.issue.headers === undefined ? {} : { headers: options.issue.headers }),
|
|
248
|
+
}, url);
|
|
249
|
+
return {
|
|
250
|
+
frame: () => frameIn(page, id),
|
|
251
|
+
outcome: () => outcomeOf(page, id),
|
|
252
|
+
framed: () => invoke(page, "framed", id),
|
|
253
|
+
};
|
|
254
|
+
},
|
|
255
|
+
async frameDirectly(page, url) {
|
|
226
256
|
await ready(page);
|
|
227
257
|
const instance = await served.artifact("entry", "1");
|
|
228
258
|
const id = await invoke(page, "show", configOf(instance), instance, {
|
|
229
259
|
location: { url, origin: new URL(url).origin },
|
|
230
260
|
});
|
|
231
261
|
return {
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
await
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
found = each === undefined ? null : each.detail;
|
|
240
|
-
return found !== null;
|
|
241
|
-
}, { message: "the display has an outcome", timeout: 15_000 })
|
|
242
|
-
.toBe(true);
|
|
243
|
-
return found;
|
|
262
|
+
outcome: () => outcomeOf(page, id),
|
|
263
|
+
framed: () => invoke(page, "framed", id),
|
|
264
|
+
async hostErrors() {
|
|
265
|
+
const events = await invoke(page, "events", id);
|
|
266
|
+
return events.flatMap((event) => event.type === "hostError"
|
|
267
|
+
? [event.detail]
|
|
268
|
+
: []);
|
|
244
269
|
},
|
|
245
270
|
};
|
|
246
271
|
},
|
|
@@ -297,6 +322,7 @@ const DOMAIN_CASES = [
|
|
|
297
322
|
"served.domain.self-navigation",
|
|
298
323
|
...TAB_CASES,
|
|
299
324
|
"served.domain.frame-ancestors",
|
|
325
|
+
"served.domain.door",
|
|
300
326
|
"served.domain.egress",
|
|
301
327
|
];
|
|
302
328
|
/**
|
|
@@ -952,6 +952,146 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
952
952
|
expect(shown.origin, "probe: a foreign origin framed the content's origin").not.toBe(location.origin);
|
|
953
953
|
}
|
|
954
954
|
});
|
|
955
|
+
define("served.domain.door", "a served display's door is on its own origin, opaque, says open from null, is taken once, refuses the wrong ticket, and says what the content route says (P125)", async ({ page }) => {
|
|
956
|
+
const doorOf = (location) => {
|
|
957
|
+
expect(location.door, "probe: the server gives a door for a served display").toBeDefined();
|
|
958
|
+
return location.door.url;
|
|
959
|
+
};
|
|
960
|
+
// Land on a host-origin page first, so the door (framed by it) is within frame-ancestors.
|
|
961
|
+
await host.show(page, await host.shell("door-nav"), { content: SHELL_CONTENT });
|
|
962
|
+
// (1) The door is on the display's own origin, at Porthole's door path.
|
|
963
|
+
const first = await host.locate(await host.shell("door-shape"));
|
|
964
|
+
const door = new URL(doorOf(first));
|
|
965
|
+
expect(door.origin, "probe: the door is on the display's origin").toBe(first.origin);
|
|
966
|
+
expect(door.pathname, "probe: the door is at /__porthole/door/<key>").toMatch(/^\/__porthole\/door\/[A-Za-z0-9_-]+$/u);
|
|
967
|
+
// (2) Framed opaque (sandbox allow-scripts), it says `open` from the opaque origin within
|
|
968
|
+
// SETTLE_MS; (5) and a door on a tab of its own is an opaque origin too.
|
|
969
|
+
const said = await page.evaluate(async ({ url, settle }) => {
|
|
970
|
+
const frame = document.createElement("iframe");
|
|
971
|
+
// Opaque: scripts only (the probe frames the door as the host does, P125).
|
|
972
|
+
frame.sandbox.add("allow-scripts");
|
|
973
|
+
const got = new Promise((resolve) => {
|
|
974
|
+
const onMessage = (event) => {
|
|
975
|
+
if (event.source === frame.contentWindow) {
|
|
976
|
+
window.removeEventListener("message", onMessage);
|
|
977
|
+
resolve({ origin: event.origin, data: event.data });
|
|
978
|
+
}
|
|
979
|
+
};
|
|
980
|
+
window.addEventListener("message", onMessage);
|
|
981
|
+
setTimeout(() => resolve(null), settle);
|
|
982
|
+
});
|
|
983
|
+
frame.src = url;
|
|
984
|
+
document.body.append(frame);
|
|
985
|
+
const message = await got;
|
|
986
|
+
frame.remove();
|
|
987
|
+
return message;
|
|
988
|
+
}, { url: door.href, settle: SETTLE_MS + 2_000 });
|
|
989
|
+
expect(said, "probe: the door said nothing when framed opaque").not.toBeNull();
|
|
990
|
+
expect(said?.origin, "probe: the door spoke from an opaque origin").toBe("null");
|
|
991
|
+
expect(said?.data?.method, "probe: the door spoke a frame status").toBe("porthole/notifications/frame-status");
|
|
992
|
+
expect(said?.data?.params?.state, "probe: the door said open").toBe("open");
|
|
993
|
+
// (5) The door's own answer is sandboxed in its header too (opaque on a tab, and in a frame a
|
|
994
|
+
// host's platform forgot to sandbox): scripts alone, never its origin, and no cookie.
|
|
995
|
+
const headered = await host.locate(await host.shell("door-header"));
|
|
996
|
+
const doorAnswer = await page.request.get(doorOf(headered), { failOnStatusCode: false });
|
|
997
|
+
const doorCsp = doorAnswer.headers()["content-security-policy"] ?? "";
|
|
998
|
+
expect(doorAnswer.status(), "probe: a fresh door ticket opens the door").toBe(200);
|
|
999
|
+
expect(doorCsp
|
|
1000
|
+
.split(";")
|
|
1001
|
+
.map((each) => each.trim())
|
|
1002
|
+
.filter((each) => each.startsWith("sandbox")), "probe: the door's header sandboxes it with scripts alone, keeping no origin of its own").toEqual(["sandbox allow-scripts"]);
|
|
1003
|
+
expect(doorAnswer.headers()["set-cookie"], "probe: the door sets no cookie").toBeUndefined();
|
|
1004
|
+
// (3) The same door ticket again opens nothing: a used ticket is `session`.
|
|
1005
|
+
const again = await page.request.get(door.href, { failOnStatusCode: false });
|
|
1006
|
+
expect(again.status(), "probe: a used door ticket is 401 session").toBe(401);
|
|
1007
|
+
// (4) The door ticket at the content route, and the content ticket at the door, open
|
|
1008
|
+
// nothing; (6) a fresh door framed from a foreign origin hears nothing (frame-ancestors).
|
|
1009
|
+
const fresh = await host.locate(await host.shell("door-cross"));
|
|
1010
|
+
const freshDoor = new URL(doorOf(fresh));
|
|
1011
|
+
const freshContent = new URL(fresh.url);
|
|
1012
|
+
const key = freshDoor.pathname.split("/").at(-1) ?? "";
|
|
1013
|
+
const doorTicket = freshDoor.searchParams.get("ticket") ?? "";
|
|
1014
|
+
const contentTicket = freshContent.searchParams.get("ticket") ?? "";
|
|
1015
|
+
const doorTicketAtContent = `${fresh.origin}/__porthole/d/${key}?ticket=${doorTicket}`;
|
|
1016
|
+
const contentTicketAtDoor = `${fresh.origin}/__porthole/door/${key}?ticket=${contentTicket}`;
|
|
1017
|
+
for (const [what, url] of [
|
|
1018
|
+
["the door ticket at the content route", doorTicketAtContent],
|
|
1019
|
+
["the content ticket at the door", contentTicketAtDoor],
|
|
1020
|
+
]) {
|
|
1021
|
+
const response = await page.request.get(url, { failOnStatusCode: false });
|
|
1022
|
+
expect(response.status(), `probe: ${what} opens nothing`).toBe(401);
|
|
1023
|
+
}
|
|
1024
|
+
// (7) The door and the content route say the same block for the same grant (P125's
|
|
1025
|
+
// invariant): for one issue, its door ticket at the door and its content ticket at
|
|
1026
|
+
// `/__porthole/d/`, each from a browser with no cookie, answer the same status and reason.
|
|
1027
|
+
// `session`: each ticket already used once; `not-found`: a version that doesn't exist.
|
|
1028
|
+
const browser = page.context().browser();
|
|
1029
|
+
const wordOf = async (url) => {
|
|
1030
|
+
const isolated = await browser.newContext();
|
|
1031
|
+
try {
|
|
1032
|
+
const answer = await isolated.request.get(url, {
|
|
1033
|
+
failOnStatusCode: false,
|
|
1034
|
+
maxRedirects: 0,
|
|
1035
|
+
headers: { "sec-fetch-dest": "iframe" },
|
|
1036
|
+
});
|
|
1037
|
+
const body = await answer.text();
|
|
1038
|
+
return {
|
|
1039
|
+
status: answer.status(),
|
|
1040
|
+
reason: /data-porthole-reason="([a-z-]+)"/u.exec(body)?.[1] ?? null,
|
|
1041
|
+
};
|
|
1042
|
+
}
|
|
1043
|
+
finally {
|
|
1044
|
+
await isolated.close();
|
|
1045
|
+
}
|
|
1046
|
+
};
|
|
1047
|
+
const used = await host.locate(await host.shell("door-same-session"));
|
|
1048
|
+
await wordOf(doorOf(used));
|
|
1049
|
+
await wordOf(used.url);
|
|
1050
|
+
const usedDoor = await wordOf(doorOf(used));
|
|
1051
|
+
const usedContent = await wordOf(used.url);
|
|
1052
|
+
expect(usedDoor, "probe: a used door ticket says session").toEqual({
|
|
1053
|
+
status: 401,
|
|
1054
|
+
reason: "session",
|
|
1055
|
+
});
|
|
1056
|
+
expect(usedContent, "probe: the content route says what the door says (used)").toEqual(usedDoor);
|
|
1057
|
+
const page1 = await host.artifact("door-same-missing", "1");
|
|
1058
|
+
const missing = page1.document.kind === "artifact"
|
|
1059
|
+
? { ...page1, document: { ...page1.document, version: "porthole-no-such-version" } }
|
|
1060
|
+
: page1;
|
|
1061
|
+
let gone = null;
|
|
1062
|
+
try {
|
|
1063
|
+
gone = await host.locate(missing);
|
|
1064
|
+
}
|
|
1065
|
+
catch {
|
|
1066
|
+
// A host that refuses to issue for a version it doesn't have answers before any frame.
|
|
1067
|
+
info?.annotations.push({
|
|
1068
|
+
type: "measured",
|
|
1069
|
+
description: "the host refuses to issue for a missing version: not-found is never framed",
|
|
1070
|
+
});
|
|
1071
|
+
}
|
|
1072
|
+
if (gone !== null) {
|
|
1073
|
+
const goneDoor = await wordOf(doorOf(gone));
|
|
1074
|
+
const goneContent = await wordOf(gone.url);
|
|
1075
|
+
expect(goneDoor, "probe: a missing document's door says not-found").toEqual({
|
|
1076
|
+
status: 404,
|
|
1077
|
+
reason: "not-found",
|
|
1078
|
+
});
|
|
1079
|
+
expect(goneContent, "probe: the content route says what the door says (missing)").toEqual(goneDoor);
|
|
1080
|
+
}
|
|
1081
|
+
// (6) A fresh door from a foreign origin: frame-ancestors refuses it, so it says nothing.
|
|
1082
|
+
const foreignDoor = await host.locate(await host.shell("door-foreign"));
|
|
1083
|
+
await host.frameFromForeignOrigin(page, doorOf(foreignDoor));
|
|
1084
|
+
await page.waitForTimeout(SETTLE_MS);
|
|
1085
|
+
for (const frame of page.frames().slice(1)) {
|
|
1086
|
+
const reached = await Promise.race([
|
|
1087
|
+
frame
|
|
1088
|
+
.evaluate(() => document.querySelector("[data-porthole-door]") !== null)
|
|
1089
|
+
.catch(() => false),
|
|
1090
|
+
new Promise((resolve) => setTimeout(() => resolve(false), 2_000)),
|
|
1091
|
+
]);
|
|
1092
|
+
expect(reached, "probe: a foreign origin framed the door").toBe(false);
|
|
1093
|
+
}
|
|
1094
|
+
});
|
|
955
1095
|
define("served.domain.egress", "the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it", async ({ page }) => {
|
|
956
1096
|
const display = await host.show(page, await host.shell("egress"), {
|
|
957
1097
|
content: SHELL_CONTENT,
|
package/dist/files/paths.d.ts
CHANGED
|
@@ -49,8 +49,8 @@ export interface FileSetProblem {
|
|
|
49
49
|
/**
|
|
50
50
|
* Checks a version's files before it is published (P081): every path by `filePathProblem`; no
|
|
51
51
|
* two paths that differ only in case, and no path that is both a file and a directory; the
|
|
52
|
-
* entry is one of them; the count, each size and the total
|
|
53
|
-
* `fileLimits`). Empty when it may be published.
|
|
52
|
+
* entry is one of them, and a page (`.html` or `.htm`, P125); the count, each size and the total
|
|
53
|
+
* within the limits (a config's, see `fileLimits`). Empty when it may be published.
|
|
54
54
|
*/
|
|
55
55
|
export declare function checkFileSet(files: Readonly<Record<string, FileSetEntryLike>>, options?: {
|
|
56
56
|
readonly entry?: string;
|
package/dist/files/paths.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { isPagePath } from "./types.js";
|
|
1
2
|
/**
|
|
2
3
|
* A version made of files (P081): the rules a published path follows, the limits a version is
|
|
3
4
|
* held to, and how a request's path finds its file. Pure: any runtime. A host checks a version
|
|
@@ -94,8 +95,8 @@ const sizeOf = (bytes) => bytes >= 1024 * 1024
|
|
|
94
95
|
/**
|
|
95
96
|
* Checks a version's files before it is published (P081): every path by `filePathProblem`; no
|
|
96
97
|
* two paths that differ only in case, and no path that is both a file and a directory; the
|
|
97
|
-
* entry is one of them; the count, each size and the total
|
|
98
|
-
* `fileLimits`). Empty when it may be published.
|
|
98
|
+
* entry is one of them, and a page (`.html` or `.htm`, P125); the count, each size and the total
|
|
99
|
+
* within the limits (a config's, see `fileLimits`). Empty when it may be published.
|
|
99
100
|
*/
|
|
100
101
|
export function checkFileSet(files, options = {}) {
|
|
101
102
|
const limits = options.limits ?? fileLimits();
|
|
@@ -169,6 +170,15 @@ export function checkFileSet(files, options = {}) {
|
|
|
169
170
|
message: `No ${JSON.stringify(entry)}: the page the version opens at is one of its files`,
|
|
170
171
|
});
|
|
171
172
|
}
|
|
173
|
+
else if (!isPagePath(entry)) {
|
|
174
|
+
// A version opens at a page (P125, P124-2): any other file is served inert, says nothing, and
|
|
175
|
+
// would show only Porthole's fallback.
|
|
176
|
+
problems.push({
|
|
177
|
+
path: entry,
|
|
178
|
+
code: "entry",
|
|
179
|
+
message: `${JSON.stringify(entry)} isn't a page: the version opens at an .html (or .htm) file of its own`,
|
|
180
|
+
});
|
|
181
|
+
}
|
|
172
182
|
return problems;
|
|
173
183
|
}
|
|
174
184
|
/**
|
package/dist/host/client.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { Displays } from "../displays/displays.ts";
|
|
3
3
|
import type { FrameLocation, InstanceLocator, InstanceRef } from "../isolation/types.ts";
|
|
4
|
+
import { type Resolved } from "./locator.ts";
|
|
4
5
|
import type { FrameOutcome } from "./types.ts";
|
|
5
6
|
/**
|
|
6
7
|
* The client half of the host kit (P072): what the app's page needs from its server's Porthole
|
|
@@ -60,6 +61,13 @@ export interface PortholeClient<N extends string = string> extends InstanceLocat
|
|
|
60
61
|
config(this: void, kind: N): PortholeConfig | null;
|
|
61
62
|
/** The same, for an instance's kind. */
|
|
62
63
|
configFor(this: void, instance: InstanceRef): PortholeConfig | null;
|
|
64
|
+
/**
|
|
65
|
+
* What a clean address names, for this viewer (P125): its instance and an issued location (a
|
|
66
|
+
* door, a ticket) for the caller's own first frame (`oneShot(location, locator)`), or the outcome
|
|
67
|
+
* the frame endpoint answered instead (signed out, denied, not found), with no frame built. A
|
|
68
|
+
* clean address is for a tab: never frame one directly (`checkFrameLocation` refuses it).
|
|
69
|
+
*/
|
|
70
|
+
resolve(this: void, address: string, signal?: AbortSignal): Promise<Resolved>;
|
|
63
71
|
/** An instance's clean address (`entry.pathOf` on the server), or null. */
|
|
64
72
|
link(this: void, instance: InstanceRef): Promise<string | null>;
|
|
65
73
|
/** The clean address if already known (from locating the instance), for rendering. */
|
package/dist/host/client.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { LocateError } from "./locator.js";
|
|
1
|
+
import { LocateError, locationOf, outcomeOfRefusal, refusalOf } from "./locator.js";
|
|
2
2
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
3
3
|
/**
|
|
4
4
|
* Whether a sign-in's `next` is the app's authorize route (P072): the open-redirect guard a
|
|
@@ -100,7 +100,7 @@ export function portholeClient(options) {
|
|
|
100
100
|
return null;
|
|
101
101
|
}
|
|
102
102
|
};
|
|
103
|
-
const
|
|
103
|
+
const askFrames = async (body, signal) => {
|
|
104
104
|
const headers = headersNow();
|
|
105
105
|
headers.set("content-type", "application/json");
|
|
106
106
|
headers.set("accept", "application/json");
|
|
@@ -109,29 +109,58 @@ export function portholeClient(options) {
|
|
|
109
109
|
headers,
|
|
110
110
|
credentials,
|
|
111
111
|
redirect: "error",
|
|
112
|
-
body: JSON.stringify(
|
|
112
|
+
body: JSON.stringify(body),
|
|
113
113
|
...(signal === undefined ? {} : { signal }),
|
|
114
114
|
});
|
|
115
115
|
const data = await answer.json().catch(() => null);
|
|
116
116
|
if (!answer.ok) {
|
|
117
|
-
const
|
|
118
|
-
|
|
119
|
-
if (code === "not-served") {
|
|
117
|
+
const refused = refusalOf(answer, data);
|
|
118
|
+
if (refused.code === "not-served") {
|
|
120
119
|
void refresh();
|
|
121
120
|
}
|
|
122
|
-
throw
|
|
123
|
-
|
|
124
|
-
|
|
121
|
+
throw refused;
|
|
122
|
+
}
|
|
123
|
+
return { status: answer.status, data };
|
|
124
|
+
};
|
|
125
|
+
/** A location as the frame endpoint gave it: its door (P125) passed on, as it came. */
|
|
126
|
+
const located = (status, data) => {
|
|
127
|
+
const { viewer: _viewer, ...location } = locationOf(status, data);
|
|
128
|
+
return location;
|
|
129
|
+
};
|
|
130
|
+
const issue = async (instance, signal) => {
|
|
131
|
+
const key = keyOf(instance);
|
|
132
|
+
const { status, data } = await askFrames({ instance }, signal);
|
|
133
|
+
const location = located(status, data);
|
|
134
|
+
links.set(key, isRecord(data) && typeof data.link === "string" ? data.link : null);
|
|
135
|
+
return location;
|
|
136
|
+
};
|
|
137
|
+
const resolve = async (address, signal) => {
|
|
138
|
+
let answer;
|
|
139
|
+
try {
|
|
140
|
+
answer = await askFrames({ address }, signal);
|
|
141
|
+
}
|
|
142
|
+
catch (error) {
|
|
143
|
+
// Signed out, denied, not found: the host's own answer, before any frame (P125).
|
|
144
|
+
const outcome = outcomeOfRefusal(error);
|
|
145
|
+
if (outcome !== null) {
|
|
146
|
+
return { outcome };
|
|
147
|
+
}
|
|
148
|
+
throw error;
|
|
125
149
|
}
|
|
126
|
-
|
|
127
|
-
|
|
150
|
+
const { status, data } = answer;
|
|
151
|
+
const instance = isRecord(data) ? data.instance : undefined;
|
|
152
|
+
if (!isRecord(instance) ||
|
|
153
|
+
typeof instance.scope !== "string" ||
|
|
154
|
+
!isRecord(instance.document) ||
|
|
155
|
+
typeof instance.document.kind !== "string") {
|
|
156
|
+
throw new LocateError("The app's frame endpoint resolved the address to no instance", status, "bad-location");
|
|
128
157
|
}
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
};
|
|
158
|
+
const found = instance;
|
|
159
|
+
const location = located(status, data);
|
|
160
|
+
// The location is the caller's, for its own first frame only (`oneShot`): never kept here,
|
|
161
|
+
// where another view of the same instance could take it.
|
|
162
|
+
links.set(keyOf(found), isRecord(data) && typeof data.link === "string" ? data.link : null);
|
|
163
|
+
return { instance: found, location };
|
|
135
164
|
};
|
|
136
165
|
let lastHandoff = 0;
|
|
137
166
|
const handoff = async () => {
|
|
@@ -187,6 +216,7 @@ export function portholeClient(options) {
|
|
|
187
216
|
config: (kind) => configOf(kind),
|
|
188
217
|
configFor: (instance) => configOf(options.displays.kindOf(instance)),
|
|
189
218
|
locate: issue,
|
|
219
|
+
resolve,
|
|
190
220
|
link,
|
|
191
221
|
knownLink: (instance) => links.get(keyOf(instance)) ?? null,
|
|
192
222
|
openInTab: (instance) => {
|
|
@@ -1,6 +1,16 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { AdapterConnection, ShellConnection } from "../protocol/adapter.ts";
|
|
3
3
|
import type { HostOptions, PortholeHost } from "./types.ts";
|
|
4
|
+
/** What the host is told of a served display located without its door (P125), once a mount. */
|
|
5
|
+
export declare const NO_DOOR = "A served display needs a door from issue (FrameLocation.door, P125), and this location has none, so no frame was made: upgrade the server (or content Worker) that issues it, and pass the door on from a locator of your own. A clean address is for a tab: to frame what it names, resolve it with client.resolve(address) or <PortholeView address>";
|
|
6
|
+
/**
|
|
7
|
+
* What the host is told when its locator gives a run the location an earlier run had (P125): its
|
|
8
|
+
* tickets were taken by that run, so its door says `blocked: session`. A locator issues anew for
|
|
9
|
+
* every run (a reload, a restart after the content navigated away).
|
|
10
|
+
*/
|
|
11
|
+
export declare const REUSED_LOCATION = "The locator gave this run a location an earlier run of this display already used (P125): its tickets are taken, so its door answers that the link has been used. A locator must issue anew for every run (InstanceLocator.locate is called for each one)";
|
|
12
|
+
/** What the host is told when its platform makes no doors (P125): no served frame is made. */
|
|
13
|
+
export declare const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
|
|
4
14
|
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
5
15
|
export declare const TRACKED_PER_SECOND = 60;
|
|
6
16
|
/**
|
package/dist/host/create-host.js
CHANGED
|
@@ -10,6 +10,8 @@ import { capabilitySpec } from "../config/capabilities.js";
|
|
|
10
10
|
import { locateServed } from "./locate.js";
|
|
11
11
|
import { mayPassOn } from "./pass-on.js";
|
|
12
12
|
import { watchOutcome } from "./outcome.js";
|
|
13
|
+
import { watchDoor } from "./door.js";
|
|
14
|
+
import { outcomeOfRefusal } from "./locator.js";
|
|
13
15
|
import { STORAGE_USED_METHOD } from "../isolation/types.js";
|
|
14
16
|
import { webPlatform } from "../platform/web.js";
|
|
15
17
|
import { TAKES } from "../platform/focus-guard.js";
|
|
@@ -22,6 +24,16 @@ import { parseViewer } from "../runtime/levels.js";
|
|
|
22
24
|
const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
|
|
23
25
|
/** How many times a display is started again after its content navigated its frame away. */
|
|
24
26
|
const MAX_RESTARTS = 3;
|
|
27
|
+
/** What the host is told of a served display located without its door (P125), once a mount. */
|
|
28
|
+
export const NO_DOOR = "A served display needs a door from issue (FrameLocation.door, P125), and this location has none, so no frame was made: upgrade the server (or content Worker) that issues it, and pass the door on from a locator of your own. A clean address is for a tab: to frame what it names, resolve it with client.resolve(address) or <PortholeView address>";
|
|
29
|
+
/**
|
|
30
|
+
* What the host is told when its locator gives a run the location an earlier run had (P125): its
|
|
31
|
+
* tickets were taken by that run, so its door says `blocked: session`. A locator issues anew for
|
|
32
|
+
* every run (a reload, a restart after the content navigated away).
|
|
33
|
+
*/
|
|
34
|
+
export const REUSED_LOCATION = "The locator gave this run a location an earlier run of this display already used (P125): its tickets are taken, so its door answers that the link has been used. A locator must issue anew for every run (InstanceLocator.locate is called for each one)";
|
|
35
|
+
/** What the host is told when its platform makes no doors (P125): no served frame is made. */
|
|
36
|
+
export const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
|
|
25
37
|
const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
|
|
26
38
|
/** The frame's annotation reports, by method. */
|
|
27
39
|
const REPORTS = {
|
|
@@ -48,6 +60,10 @@ export function createHost(config, options = {}) {
|
|
|
48
60
|
}
|
|
49
61
|
// A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
|
|
50
62
|
const speaks = config.mode !== "url";
|
|
63
|
+
const nested = config.nested === true;
|
|
64
|
+
// A served display on its scope's origin, beside the scope's other content (P125): its door
|
|
65
|
+
// says how loading went, before its frame is made.
|
|
66
|
+
const hasDoor = config.isolation === "domain" && speaks && !nested;
|
|
51
67
|
const adapter = (options.adapter ?? shellAdapter);
|
|
52
68
|
const platform = options.platform ?? webPlatform;
|
|
53
69
|
const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
|
|
@@ -88,6 +104,11 @@ export function createHost(config, options = {}) {
|
|
|
88
104
|
}
|
|
89
105
|
const listeners = new Map();
|
|
90
106
|
const emit = (event, detail) => {
|
|
107
|
+
// An outcome ends a loading episode: the next run (a restart, a reload) gets a clock of
|
|
108
|
+
// its own (P125).
|
|
109
|
+
if (event === "outcome") {
|
|
110
|
+
episodeBegan = null;
|
|
111
|
+
}
|
|
91
112
|
for (const listener of listeners.get(event) ?? []) {
|
|
92
113
|
listener(detail);
|
|
93
114
|
}
|
|
@@ -111,6 +132,10 @@ export function createHost(config, options = {}) {
|
|
|
111
132
|
let bridge = null;
|
|
112
133
|
let destroyed = false;
|
|
113
134
|
let restarts = 0;
|
|
135
|
+
// When the loading episode that has no outcome yet began: its first run, not each restart's
|
|
136
|
+
// (P125). However often a frame is started again (a sibling of its scope wiping or
|
|
137
|
+
// navigating it, P125 S7), the display's time runs out and it has an outcome.
|
|
138
|
+
let episodeBegan = null;
|
|
114
139
|
let generation = 0;
|
|
115
140
|
// The viewer's answer for this display (P079): asked once, kept across its frames; or the
|
|
116
141
|
// host's refusal of them all (P080).
|
|
@@ -119,6 +144,10 @@ export function createHost(config, options = {}) {
|
|
|
119
144
|
: onceConsent(options.consent);
|
|
120
145
|
let abort = null;
|
|
121
146
|
let outcomeWatch = null;
|
|
147
|
+
let door = null;
|
|
148
|
+
// The addresses earlier runs were located at (P125): a ticket opens once, so a run given one
|
|
149
|
+
// again is told to the host (its outcome is the server's word, unchanged).
|
|
150
|
+
const locatedAt = new Set();
|
|
122
151
|
let themeFrame = null;
|
|
123
152
|
const view = container.ownerDocument.defaultView;
|
|
124
153
|
// The adapter's own operations, the last call of each, replayed into every new frame.
|
|
@@ -420,6 +449,11 @@ export function createHost(config, options = {}) {
|
|
|
420
449
|
return;
|
|
421
450
|
}
|
|
422
451
|
};
|
|
452
|
+
const closeDoor = () => {
|
|
453
|
+
door?.watch.stop();
|
|
454
|
+
door?.frame.destroy();
|
|
455
|
+
door = null;
|
|
456
|
+
};
|
|
423
457
|
const stop = () => {
|
|
424
458
|
// A run that ran a page with storage of its own making and never heard it used: no (P111).
|
|
425
459
|
if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
|
|
@@ -435,12 +469,48 @@ export function createHost(config, options = {}) {
|
|
|
435
469
|
abort = null;
|
|
436
470
|
outcomeWatch?.stop();
|
|
437
471
|
outcomeWatch = null;
|
|
472
|
+
closeDoor();
|
|
438
473
|
connection?.close();
|
|
439
474
|
connection = null;
|
|
440
475
|
surface?.destroy();
|
|
441
476
|
surface = null;
|
|
442
477
|
};
|
|
443
|
-
const
|
|
478
|
+
const timeoutMs = config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
|
|
479
|
+
/**
|
|
480
|
+
* A served display with a door (P125): its door first, alone, in a frame of the host's own;
|
|
481
|
+
* its frame only once the door said `open`, within what is left of the run's time. A door
|
|
482
|
+
* that said `blocked` (or never ran, or never answered) is the run's outcome, and nothing of
|
|
483
|
+
* the content is framed. A location without a door (an older server, a locator that drops
|
|
484
|
+
* it, a clean address someone framed) is refused before any frame is made: `blocked:
|
|
485
|
+
* locate`, and the host hears why (`door`). Nothing infers a door's word from anything else.
|
|
486
|
+
*/
|
|
487
|
+
const enter = (source, timeLeft = timeoutMs) => {
|
|
488
|
+
if (!hasDoor || source.kind !== "url") {
|
|
489
|
+
start(source, timeLeft);
|
|
490
|
+
return;
|
|
491
|
+
}
|
|
492
|
+
if (source.door === undefined || platform.createDoor === undefined) {
|
|
493
|
+
hostError(source.door === undefined ? NO_DOOR : NO_DOOR_PLATFORM, "door");
|
|
494
|
+
emit("outcome", { state: "blocked", reason: "locate" });
|
|
495
|
+
return;
|
|
496
|
+
}
|
|
497
|
+
const began = Date.now();
|
|
498
|
+
const frame = platform.createDoor(container, { url: source.door });
|
|
499
|
+
const watch = watchDoor({
|
|
500
|
+
door: frame,
|
|
501
|
+
timeoutMs: timeLeft,
|
|
502
|
+
onOpen: () => {
|
|
503
|
+
closeDoor();
|
|
504
|
+
start(source, Math.max(0, timeLeft - (Date.now() - began)));
|
|
505
|
+
},
|
|
506
|
+
onOutcome: (outcome) => {
|
|
507
|
+
closeDoor();
|
|
508
|
+
emit("outcome", outcome);
|
|
509
|
+
},
|
|
510
|
+
});
|
|
511
|
+
door = { frame, watch };
|
|
512
|
+
};
|
|
513
|
+
const start = (source, timeLeft) => {
|
|
444
514
|
const navigatedAway = () => {
|
|
445
515
|
emit("navigated", undefined);
|
|
446
516
|
if (restarts < MAX_RESTARTS) {
|
|
@@ -450,6 +520,9 @@ export function createHost(config, options = {}) {
|
|
|
450
520
|
else {
|
|
451
521
|
stop();
|
|
452
522
|
contentError("The content kept navigating its frame away; it was stopped.");
|
|
523
|
+
// Every display ends with an outcome (P125): a frame stopped after its restarts ran out
|
|
524
|
+
// is one the host can draw a fallback for, never an empty box.
|
|
525
|
+
emit("outcome", { state: "blocked", reason: "error" });
|
|
453
526
|
}
|
|
454
527
|
};
|
|
455
528
|
const framed = platform.createSurface(container, {
|
|
@@ -512,7 +585,8 @@ export function createHost(config, options = {}) {
|
|
|
512
585
|
surface: created,
|
|
513
586
|
source,
|
|
514
587
|
speaks,
|
|
515
|
-
|
|
588
|
+
nested,
|
|
589
|
+
timeoutMs: timeLeft,
|
|
516
590
|
onOutcome: (outcome) => emit("outcome", outcome),
|
|
517
591
|
// A frame status from the content (P124): never shown, the host's to hear.
|
|
518
592
|
refused: (message) => hostError(message, "frame-status"),
|
|
@@ -600,8 +674,13 @@ export function createHost(config, options = {}) {
|
|
|
600
674
|
return;
|
|
601
675
|
}
|
|
602
676
|
generation += 1;
|
|
677
|
+
if (episodeBegan === null) {
|
|
678
|
+
episodeBegan = Date.now();
|
|
679
|
+
}
|
|
680
|
+
// What is left of this episode's time: a restart doesn't start the clock again.
|
|
681
|
+
const timeLeft = Math.max(0, timeoutMs - (Date.now() - episodeBegan));
|
|
603
682
|
if (config.isolation === "opaque") {
|
|
604
|
-
|
|
683
|
+
enter({
|
|
605
684
|
kind: "srcdoc",
|
|
606
685
|
html: compiled.shellDocument({
|
|
607
686
|
origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
|
|
@@ -609,7 +688,7 @@ export function createHost(config, options = {}) {
|
|
|
609
688
|
...nonceOf(options.nonce),
|
|
610
689
|
...(mount.document === undefined ? {} : { document: mount.document }),
|
|
611
690
|
}),
|
|
612
|
-
});
|
|
691
|
+
}, timeLeft);
|
|
613
692
|
return;
|
|
614
693
|
}
|
|
615
694
|
const mine = generation;
|
|
@@ -621,16 +700,50 @@ export function createHost(config, options = {}) {
|
|
|
621
700
|
return;
|
|
622
701
|
}
|
|
623
702
|
const hostOrigin = container.ownerDocument.defaultView?.location.origin ?? "";
|
|
703
|
+
// The run's time covers locating too: a backend that never answers is a timeout.
|
|
704
|
+
const began = Date.now();
|
|
705
|
+
let settled = false;
|
|
706
|
+
const late = setTimeout(() => {
|
|
707
|
+
if (!settled && mine === generation && !destroyed) {
|
|
708
|
+
settled = true;
|
|
709
|
+
controller.abort();
|
|
710
|
+
hostError("The host's backend didn't give a location in time", "locate");
|
|
711
|
+
emit("outcome", { state: "timeout" });
|
|
712
|
+
}
|
|
713
|
+
}, timeLeft);
|
|
714
|
+
// A run stopped (destroyed, started again) stops its clock too.
|
|
715
|
+
controller.signal.addEventListener("abort", () => clearTimeout(late), { once: true });
|
|
624
716
|
locateServed(locator, instance, config, hostOrigin, controller.signal).then((source) => {
|
|
625
|
-
|
|
626
|
-
|
|
717
|
+
clearTimeout(late);
|
|
718
|
+
if (!settled && mine === generation && !destroyed) {
|
|
719
|
+
settled = true;
|
|
720
|
+
if (source.kind === "url") {
|
|
721
|
+
const seen = [source.url, ...(source.door === undefined ? [] : [source.door])];
|
|
722
|
+
if (seen.some((each) => locatedAt.has(each))) {
|
|
723
|
+
hostError(REUSED_LOCATION, "locate");
|
|
724
|
+
}
|
|
725
|
+
for (const each of seen) {
|
|
726
|
+
locatedAt.add(each);
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
enter(source, Math.max(0, timeLeft - (Date.now() - began)));
|
|
627
730
|
}
|
|
628
731
|
}, (error) => {
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
732
|
+
clearTimeout(late);
|
|
733
|
+
if (settled || mine !== generation || controller.signal.aborted) {
|
|
734
|
+
return;
|
|
735
|
+
}
|
|
736
|
+
settled = true;
|
|
737
|
+
// The host's own issue endpoint refused (signed out, denied, not found, P125): its
|
|
738
|
+
// word, before any frame, never the content's. Anything else is the host's own failure
|
|
739
|
+
// (its backend down, a network error, a malformed answer): `locate`, never `denied`.
|
|
740
|
+
const refused = outcomeOfRefusal(error);
|
|
741
|
+
if (refused !== null) {
|
|
742
|
+
emit("outcome", refused);
|
|
743
|
+
return;
|
|
633
744
|
}
|
|
745
|
+
hostError(error instanceof Error ? error.message : String(error), "locate");
|
|
746
|
+
emit("outcome", { state: "blocked", reason: "locate" });
|
|
634
747
|
});
|
|
635
748
|
};
|
|
636
749
|
run();
|
|
@@ -670,6 +783,7 @@ export function createHost(config, options = {}) {
|
|
|
670
783
|
},
|
|
671
784
|
reload() {
|
|
672
785
|
restarts = 0;
|
|
786
|
+
episodeBegan = null;
|
|
673
787
|
run();
|
|
674
788
|
},
|
|
675
789
|
focus() {
|