@botiverse/porthole 0.14.5 → 0.14.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +66 -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 +148 -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 +7 -1
- package/dist/server/pages.d.ts +32 -0
- package/dist/server/pages.js +82 -6
- package/dist/server/server.js +194 -16
- package/dist/server/types.d.ts +38 -1
- package/dist/transport/post-message.d.ts +1 -9
- package/dist/transport/post-message.js +2 -8
- package/docs/ADOPTING.md +73 -4
- package/docs/DECISIONS.md +245 -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 +184 -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 +7 -1
- package/src/server/pages.ts +101 -6
- package/src/server/server.ts +266 -32
- package/src/server/types.ts +41 -1
- package/src/transport/post-message.ts +1 -9
|
@@ -1257,6 +1257,190 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1257
1257
|
},
|
|
1258
1258
|
);
|
|
1259
1259
|
|
|
1260
|
+
define(
|
|
1261
|
+
"served.domain.door",
|
|
1262
|
+
"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)",
|
|
1263
|
+
async ({ page }) => {
|
|
1264
|
+
const doorOf = (location: Awaited<ReturnType<typeof host.locate>>): string => {
|
|
1265
|
+
expect(
|
|
1266
|
+
location.door,
|
|
1267
|
+
"probe: the server gives a door for a served display",
|
|
1268
|
+
).toBeDefined();
|
|
1269
|
+
return location.door!.url;
|
|
1270
|
+
};
|
|
1271
|
+
// Land on a host-origin page first, so the door (framed by it) is within frame-ancestors.
|
|
1272
|
+
await host.show(page, await host.shell("door-nav"), { content: SHELL_CONTENT });
|
|
1273
|
+
// (1) The door is on the display's own origin, at Porthole's door path.
|
|
1274
|
+
const first = await host.locate(await host.shell("door-shape"));
|
|
1275
|
+
const door = new URL(doorOf(first));
|
|
1276
|
+
expect(door.origin, "probe: the door is on the display's origin").toBe(first.origin);
|
|
1277
|
+
expect(door.pathname, "probe: the door is at /__porthole/door/<key>").toMatch(
|
|
1278
|
+
/^\/__porthole\/door\/[A-Za-z0-9_-]+$/u,
|
|
1279
|
+
);
|
|
1280
|
+
|
|
1281
|
+
// (2) Framed opaque (sandbox allow-scripts), it says `open` from the opaque origin within
|
|
1282
|
+
// SETTLE_MS; (5) and a door on a tab of its own is an opaque origin too.
|
|
1283
|
+
const said = await page.evaluate(
|
|
1284
|
+
async ({ url, settle }) => {
|
|
1285
|
+
const frame = document.createElement("iframe");
|
|
1286
|
+
// Opaque: scripts only (the probe frames the door as the host does, P125).
|
|
1287
|
+
frame.sandbox.add("allow-scripts");
|
|
1288
|
+
const got = new Promise<{ origin: string; data: unknown } | null>((resolve) => {
|
|
1289
|
+
const onMessage = (event: MessageEvent) => {
|
|
1290
|
+
if (event.source === frame.contentWindow) {
|
|
1291
|
+
window.removeEventListener("message", onMessage);
|
|
1292
|
+
resolve({ origin: event.origin, data: event.data });
|
|
1293
|
+
}
|
|
1294
|
+
};
|
|
1295
|
+
window.addEventListener("message", onMessage);
|
|
1296
|
+
setTimeout(() => resolve(null), settle);
|
|
1297
|
+
});
|
|
1298
|
+
frame.src = url;
|
|
1299
|
+
document.body.append(frame);
|
|
1300
|
+
const message = await got;
|
|
1301
|
+
frame.remove();
|
|
1302
|
+
return message;
|
|
1303
|
+
},
|
|
1304
|
+
{ url: door.href, settle: SETTLE_MS + 2_000 },
|
|
1305
|
+
);
|
|
1306
|
+
expect(said, "probe: the door said nothing when framed opaque").not.toBeNull();
|
|
1307
|
+
expect(said?.origin, "probe: the door spoke from an opaque origin").toBe("null");
|
|
1308
|
+
expect(
|
|
1309
|
+
(said?.data as { method?: unknown } | null)?.method,
|
|
1310
|
+
"probe: the door spoke a frame status",
|
|
1311
|
+
).toBe("porthole/notifications/frame-status");
|
|
1312
|
+
expect(
|
|
1313
|
+
(said?.data as { params?: { state?: unknown } } | null)?.params?.state,
|
|
1314
|
+
"probe: the door said open",
|
|
1315
|
+
).toBe("open");
|
|
1316
|
+
|
|
1317
|
+
// (5) The door's own answer is sandboxed in its header too (opaque on a tab, and in a frame a
|
|
1318
|
+
// host's platform forgot to sandbox): scripts alone, never its origin, and no cookie.
|
|
1319
|
+
const headered = await host.locate(await host.shell("door-header"));
|
|
1320
|
+
const doorAnswer = await page.request.get(doorOf(headered), { failOnStatusCode: false });
|
|
1321
|
+
const doorCsp = doorAnswer.headers()["content-security-policy"] ?? "";
|
|
1322
|
+
expect(doorAnswer.status(), "probe: a fresh door ticket opens the door").toBe(200);
|
|
1323
|
+
expect(
|
|
1324
|
+
doorCsp
|
|
1325
|
+
.split(";")
|
|
1326
|
+
.map((each) => each.trim())
|
|
1327
|
+
.filter((each) => each.startsWith("sandbox")),
|
|
1328
|
+
"probe: the door's header sandboxes it with scripts alone, keeping no origin of its own",
|
|
1329
|
+
).toEqual(["sandbox allow-scripts"]);
|
|
1330
|
+
expect(
|
|
1331
|
+
doorAnswer.headers()["set-cookie"],
|
|
1332
|
+
"probe: the door sets no cookie",
|
|
1333
|
+
).toBeUndefined();
|
|
1334
|
+
|
|
1335
|
+
// (3) The same door ticket again opens nothing: a used ticket is `session`.
|
|
1336
|
+
const again = await page.request.get(door.href, { failOnStatusCode: false });
|
|
1337
|
+
expect(again.status(), "probe: a used door ticket is 401 session").toBe(401);
|
|
1338
|
+
|
|
1339
|
+
// (4) The door ticket at the content route, and the content ticket at the door, open
|
|
1340
|
+
// nothing: the two tickets of one issue are not interchangeable. Each is swapped into the
|
|
1341
|
+
// other's own URL, each path kept as the host gave it (a host's door path need not end in
|
|
1342
|
+
// its content's key, P126); (6) a fresh door framed from a foreign origin hears nothing
|
|
1343
|
+
// (frame-ancestors).
|
|
1344
|
+
const fresh = await host.locate(await host.shell("door-cross"));
|
|
1345
|
+
const doorTicketAtContent = new URL(fresh.url);
|
|
1346
|
+
const contentTicketAtDoor = new URL(doorOf(fresh));
|
|
1347
|
+
const doorTicket = contentTicketAtDoor.searchParams.get("ticket");
|
|
1348
|
+
const contentTicket = doorTicketAtContent.searchParams.get("ticket");
|
|
1349
|
+
if (doorTicket === null || contentTicket === null) {
|
|
1350
|
+
info?.annotations.push({
|
|
1351
|
+
type: "measured",
|
|
1352
|
+
description:
|
|
1353
|
+
"the location's content or door URL carries no ticket query parameter: the swap presents none",
|
|
1354
|
+
});
|
|
1355
|
+
}
|
|
1356
|
+
doorTicketAtContent.searchParams.set("ticket", doorTicket ?? "");
|
|
1357
|
+
contentTicketAtDoor.searchParams.set("ticket", contentTicket ?? "");
|
|
1358
|
+
for (const [what, url] of [
|
|
1359
|
+
["the door ticket at the content route", doorTicketAtContent.href],
|
|
1360
|
+
["the content ticket at the door", contentTicketAtDoor.href],
|
|
1361
|
+
] as const) {
|
|
1362
|
+
const response = await page.request.get(url, { failOnStatusCode: false });
|
|
1363
|
+
expect(response.status(), `probe: ${what} opens nothing`).toBe(401);
|
|
1364
|
+
}
|
|
1365
|
+
|
|
1366
|
+
// (7) The door and the content route say the same block for the same grant (P125's
|
|
1367
|
+
// invariant): for one issue, its door ticket at the door and its content ticket at
|
|
1368
|
+
// `/__porthole/d/`, each from a browser with no cookie, answer the same status and reason.
|
|
1369
|
+
// `session`: each ticket already used once; `not-found`: a version that doesn't exist.
|
|
1370
|
+
const browser = page.context().browser();
|
|
1371
|
+
const wordOf = async (url: string) => {
|
|
1372
|
+
const isolated = await browser!.newContext();
|
|
1373
|
+
try {
|
|
1374
|
+
const answer = await isolated.request.get(url, {
|
|
1375
|
+
failOnStatusCode: false,
|
|
1376
|
+
maxRedirects: 0,
|
|
1377
|
+
headers: { "sec-fetch-dest": "iframe" },
|
|
1378
|
+
});
|
|
1379
|
+
const body = await answer.text();
|
|
1380
|
+
return {
|
|
1381
|
+
status: answer.status(),
|
|
1382
|
+
reason: /data-porthole-reason="([a-z-]+)"/u.exec(body)?.[1] ?? null,
|
|
1383
|
+
};
|
|
1384
|
+
} finally {
|
|
1385
|
+
await isolated.close();
|
|
1386
|
+
}
|
|
1387
|
+
};
|
|
1388
|
+
const used = await host.locate(await host.shell("door-same-session"));
|
|
1389
|
+
await wordOf(doorOf(used));
|
|
1390
|
+
await wordOf(used.url);
|
|
1391
|
+
const usedDoor = await wordOf(doorOf(used));
|
|
1392
|
+
const usedContent = await wordOf(used.url);
|
|
1393
|
+
expect(usedDoor, "probe: a used door ticket says session").toEqual({
|
|
1394
|
+
status: 401,
|
|
1395
|
+
reason: "session",
|
|
1396
|
+
});
|
|
1397
|
+
expect(usedContent, "probe: the content route says what the door says (used)").toEqual(
|
|
1398
|
+
usedDoor,
|
|
1399
|
+
);
|
|
1400
|
+
const page1 = await host.artifact("door-same-missing", "1");
|
|
1401
|
+
const missing: InstanceRef =
|
|
1402
|
+
page1.document.kind === "artifact"
|
|
1403
|
+
? { ...page1, document: { ...page1.document, version: "porthole-no-such-version" } }
|
|
1404
|
+
: page1;
|
|
1405
|
+
let gone: FrameLocation | null = null;
|
|
1406
|
+
try {
|
|
1407
|
+
gone = await host.locate(missing);
|
|
1408
|
+
} catch {
|
|
1409
|
+
// A host that refuses to issue for a version it doesn't have answers before any frame.
|
|
1410
|
+
info?.annotations.push({
|
|
1411
|
+
type: "measured",
|
|
1412
|
+
description:
|
|
1413
|
+
"the host refuses to issue for a missing version: not-found is never framed",
|
|
1414
|
+
});
|
|
1415
|
+
}
|
|
1416
|
+
if (gone !== null) {
|
|
1417
|
+
const goneDoor = await wordOf(doorOf(gone));
|
|
1418
|
+
const goneContent = await wordOf(gone.url);
|
|
1419
|
+
expect(goneDoor, "probe: a missing document's door says not-found").toEqual({
|
|
1420
|
+
status: 404,
|
|
1421
|
+
reason: "not-found",
|
|
1422
|
+
});
|
|
1423
|
+
expect(goneContent, "probe: the content route says what the door says (missing)").toEqual(
|
|
1424
|
+
goneDoor,
|
|
1425
|
+
);
|
|
1426
|
+
}
|
|
1427
|
+
|
|
1428
|
+
// (6) A fresh door from a foreign origin: frame-ancestors refuses it, so it says nothing.
|
|
1429
|
+
const foreignDoor = await host.locate(await host.shell("door-foreign"));
|
|
1430
|
+
await host.frameFromForeignOrigin(page, doorOf(foreignDoor));
|
|
1431
|
+
await page.waitForTimeout(SETTLE_MS);
|
|
1432
|
+
for (const frame of page.frames().slice(1)) {
|
|
1433
|
+
const reached = await Promise.race([
|
|
1434
|
+
frame
|
|
1435
|
+
.evaluate(() => document.querySelector("[data-porthole-door]") !== null)
|
|
1436
|
+
.catch(() => false),
|
|
1437
|
+
new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 2_000)),
|
|
1438
|
+
]);
|
|
1439
|
+
expect(reached, "probe: a foreign origin framed the door").toBe(false);
|
|
1440
|
+
}
|
|
1441
|
+
},
|
|
1442
|
+
);
|
|
1443
|
+
|
|
1260
1444
|
define(
|
|
1261
1445
|
"served.domain.egress",
|
|
1262
1446
|
"the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it",
|
package/src/files/paths.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Limits, PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import { isPagePath } from "./types.ts";
|
|
2
3
|
|
|
3
4
|
/**
|
|
4
5
|
* A version made of files (P081): the rules a published path follows, the limits a version is
|
|
@@ -124,8 +125,8 @@ const sizeOf = (bytes: number): string =>
|
|
|
124
125
|
/**
|
|
125
126
|
* Checks a version's files before it is published (P081): every path by `filePathProblem`; no
|
|
126
127
|
* two paths that differ only in case, and no path that is both a file and a directory; the
|
|
127
|
-
* entry is one of them; the count, each size and the total
|
|
128
|
-
* `fileLimits`). Empty when it may be published.
|
|
128
|
+
* entry is one of them, and a page (`.html` or `.htm`, P125); the count, each size and the total
|
|
129
|
+
* within the limits (a config's, see `fileLimits`). Empty when it may be published.
|
|
129
130
|
*/
|
|
130
131
|
export function checkFileSet(
|
|
131
132
|
files: Readonly<Record<string, FileSetEntryLike>>,
|
|
@@ -200,6 +201,14 @@ export function checkFileSet(
|
|
|
200
201
|
code: "entry",
|
|
201
202
|
message: `No ${JSON.stringify(entry)}: the page the version opens at is one of its files`,
|
|
202
203
|
});
|
|
204
|
+
} else if (!isPagePath(entry)) {
|
|
205
|
+
// A version opens at a page (P125, P124-2): any other file is served inert, says nothing, and
|
|
206
|
+
// would show only Porthole's fallback.
|
|
207
|
+
problems.push({
|
|
208
|
+
path: entry,
|
|
209
|
+
code: "entry",
|
|
210
|
+
message: `${JSON.stringify(entry)} isn't a page: the version opens at an .html (or .htm) file of its own`,
|
|
211
|
+
});
|
|
203
212
|
}
|
|
204
213
|
return problems;
|
|
205
214
|
}
|
package/src/host/client.ts
CHANGED
|
@@ -1,7 +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 { LocateError } from "./locator.ts";
|
|
4
|
+
import { LocateError, locationOf, outcomeOfRefusal, refusalOf, type Resolved } from "./locator.ts";
|
|
5
5
|
import type { FrameOutcome } from "./types.ts";
|
|
6
6
|
|
|
7
7
|
/**
|
|
@@ -65,6 +65,13 @@ export interface PortholeClient<N extends string = string> extends InstanceLocat
|
|
|
65
65
|
config(this: void, kind: N): PortholeConfig | null;
|
|
66
66
|
/** The same, for an instance's kind. */
|
|
67
67
|
configFor(this: void, instance: InstanceRef): PortholeConfig | null;
|
|
68
|
+
/**
|
|
69
|
+
* What a clean address names, for this viewer (P125): its instance and an issued location (a
|
|
70
|
+
* door, a ticket) for the caller's own first frame (`oneShot(location, locator)`), or the outcome
|
|
71
|
+
* the frame endpoint answered instead (signed out, denied, not found), with no frame built. A
|
|
72
|
+
* clean address is for a tab: never frame one directly (`checkFrameLocation` refuses it).
|
|
73
|
+
*/
|
|
74
|
+
resolve(this: void, address: string, signal?: AbortSignal): Promise<Resolved>;
|
|
68
75
|
/** An instance's clean address (`entry.pathOf` on the server), or null. */
|
|
69
76
|
link(this: void, instance: InstanceRef): Promise<string | null>;
|
|
70
77
|
/** The clean address if already known (from locating the instance), for rendering. */
|
|
@@ -199,7 +206,7 @@ export function portholeClient<N extends string>(
|
|
|
199
206
|
}
|
|
200
207
|
};
|
|
201
208
|
|
|
202
|
-
const
|
|
209
|
+
const askFrames = async (body: Record<string, unknown>, signal?: AbortSignal) => {
|
|
203
210
|
const headers = headersNow();
|
|
204
211
|
headers.set("content-type", "application/json");
|
|
205
212
|
headers.set("accept", "application/json");
|
|
@@ -208,37 +215,66 @@ export function portholeClient<N extends string>(
|
|
|
208
215
|
headers,
|
|
209
216
|
credentials,
|
|
210
217
|
redirect: "error",
|
|
211
|
-
body: JSON.stringify(
|
|
218
|
+
body: JSON.stringify(body),
|
|
212
219
|
...(signal === undefined ? {} : { signal }),
|
|
213
220
|
});
|
|
214
221
|
const data: unknown = await answer.json().catch(() => null);
|
|
215
222
|
if (!answer.ok) {
|
|
216
|
-
const
|
|
217
|
-
|
|
218
|
-
if (code === "not-served") {
|
|
223
|
+
const refused = refusalOf(answer, data);
|
|
224
|
+
if (refused.code === "not-served") {
|
|
219
225
|
void refresh();
|
|
220
226
|
}
|
|
221
|
-
throw
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
227
|
+
throw refused;
|
|
228
|
+
}
|
|
229
|
+
return { status: answer.status, data };
|
|
230
|
+
};
|
|
231
|
+
|
|
232
|
+
/** A location as the frame endpoint gave it: its door (P125) passed on, as it came. */
|
|
233
|
+
const located = (status: number, data: unknown): FrameLocation => {
|
|
234
|
+
const { viewer: _viewer, ...location } = locationOf(status, data);
|
|
235
|
+
return location;
|
|
236
|
+
};
|
|
237
|
+
|
|
238
|
+
const issue = async (instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation> => {
|
|
239
|
+
const key = keyOf(instance);
|
|
240
|
+
const { status, data } = await askFrames({ instance }, signal);
|
|
241
|
+
const location = located(status, data);
|
|
242
|
+
links.set(key, isRecord(data) && typeof data.link === "string" ? data.link : null);
|
|
243
|
+
return location;
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
const resolve = async (address: string, signal?: AbortSignal): Promise<Resolved> => {
|
|
247
|
+
let answer: { readonly status: number; readonly data: unknown };
|
|
248
|
+
try {
|
|
249
|
+
answer = await askFrames({ address }, signal);
|
|
250
|
+
} catch (error) {
|
|
251
|
+
// Signed out, denied, not found: the host's own answer, before any frame (P125).
|
|
252
|
+
const outcome = outcomeOfRefusal(error);
|
|
253
|
+
if (outcome !== null) {
|
|
254
|
+
return { outcome };
|
|
255
|
+
}
|
|
256
|
+
throw error;
|
|
228
257
|
}
|
|
229
|
-
|
|
258
|
+
const { status, data } = answer;
|
|
259
|
+
const instance = isRecord(data) ? data.instance : undefined;
|
|
260
|
+
if (
|
|
261
|
+
!isRecord(instance) ||
|
|
262
|
+
typeof instance.scope !== "string" ||
|
|
263
|
+
!isRecord(instance.document) ||
|
|
264
|
+
typeof instance.document.kind !== "string"
|
|
265
|
+
) {
|
|
230
266
|
throw new LocateError(
|
|
231
|
-
"The app's frame endpoint
|
|
232
|
-
|
|
267
|
+
"The app's frame endpoint resolved the address to no instance",
|
|
268
|
+
status,
|
|
233
269
|
"bad-location",
|
|
234
270
|
);
|
|
235
271
|
}
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
};
|
|
272
|
+
const found = instance as unknown as InstanceRef;
|
|
273
|
+
const location = located(status, data);
|
|
274
|
+
// The location is the caller's, for its own first frame only (`oneShot`): never kept here,
|
|
275
|
+
// where another view of the same instance could take it.
|
|
276
|
+
links.set(keyOf(found), isRecord(data) && typeof data.link === "string" ? data.link : null);
|
|
277
|
+
return { instance: found, location };
|
|
242
278
|
};
|
|
243
279
|
|
|
244
280
|
let lastHandoff = 0;
|
|
@@ -297,6 +333,7 @@ export function portholeClient<N extends string>(
|
|
|
297
333
|
config: (kind) => configOf(kind),
|
|
298
334
|
configFor: (instance) => configOf(options.displays.kindOf(instance)),
|
|
299
335
|
locate: issue,
|
|
336
|
+
resolve,
|
|
300
337
|
link,
|
|
301
338
|
knownLink: (instance) => links.get(keyOf(instance)) ?? null,
|
|
302
339
|
openInTab: (instance) => {
|
package/src/host/create-host.ts
CHANGED
|
@@ -28,10 +28,12 @@ import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
|
28
28
|
import { locateServed } from "./locate.ts";
|
|
29
29
|
import { mayPassOn } from "./pass-on.ts";
|
|
30
30
|
import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
|
|
31
|
+
import { watchDoor, type DoorWatch } from "./door.ts";
|
|
32
|
+
import { outcomeOfRefusal } from "./locator.ts";
|
|
31
33
|
import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
|
|
32
34
|
import { webPlatform } from "../platform/web.ts";
|
|
33
35
|
import { TAKES } from "../platform/focus-guard.ts";
|
|
34
|
-
import type { Surface } from "../platform/types.ts";
|
|
36
|
+
import type { DoorSurface, Surface } from "../platform/types.ts";
|
|
35
37
|
import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
|
|
36
38
|
import {
|
|
37
39
|
MCP_APPS_STYLE_VARIABLES,
|
|
@@ -58,6 +60,22 @@ const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
|
|
|
58
60
|
/** How many times a display is started again after its content navigated its frame away. */
|
|
59
61
|
const MAX_RESTARTS = 3;
|
|
60
62
|
|
|
63
|
+
/** What the host is told of a served display located without its door (P125), once a mount. */
|
|
64
|
+
export const NO_DOOR =
|
|
65
|
+
"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>";
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* What the host is told when its locator gives a run the location an earlier run had (P125): its
|
|
69
|
+
* tickets were taken by that run, so its door says `blocked: session`. A locator issues anew for
|
|
70
|
+
* every run (a reload, a restart after the content navigated away).
|
|
71
|
+
*/
|
|
72
|
+
export const REUSED_LOCATION =
|
|
73
|
+
"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)";
|
|
74
|
+
|
|
75
|
+
/** What the host is told when its platform makes no doors (P125): no served frame is made. */
|
|
76
|
+
export const NO_DOOR_PLATFORM =
|
|
77
|
+
"This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
|
|
78
|
+
|
|
61
79
|
const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
|
|
62
80
|
|
|
63
81
|
/** The frame's annotation reports, by method. */
|
|
@@ -94,6 +112,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
94
112
|
}
|
|
95
113
|
// A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
|
|
96
114
|
const speaks = config.mode !== "url";
|
|
115
|
+
const nested = config.nested === true;
|
|
116
|
+
// A served display on its scope's origin, beside the scope's other content (P125): its door
|
|
117
|
+
// says how loading went, before its frame is made.
|
|
118
|
+
const hasDoor = config.isolation === "domain" && speaks && !nested;
|
|
97
119
|
const adapter = (options.adapter ?? shellAdapter) as ProtocolAdapter<C>;
|
|
98
120
|
const platform = options.platform ?? webPlatform;
|
|
99
121
|
const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
|
|
@@ -148,6 +170,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
148
170
|
|
|
149
171
|
const listeners = new Map<keyof DisplayEvents, Set<(detail: never) => void>>();
|
|
150
172
|
const emit = <E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]) => {
|
|
173
|
+
// An outcome ends a loading episode: the next run (a restart, a reload) gets a clock of
|
|
174
|
+
// its own (P125).
|
|
175
|
+
if (event === "outcome") {
|
|
176
|
+
episodeBegan = null;
|
|
177
|
+
}
|
|
151
178
|
for (const listener of listeners.get(event) ?? []) {
|
|
152
179
|
(listener as (detail: DisplayEvents[E]) => void)(detail);
|
|
153
180
|
}
|
|
@@ -172,6 +199,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
172
199
|
let bridge: DisplayBridge | null = null;
|
|
173
200
|
let destroyed = false;
|
|
174
201
|
let restarts = 0;
|
|
202
|
+
// When the loading episode that has no outcome yet began: its first run, not each restart's
|
|
203
|
+
// (P125). However often a frame is started again (a sibling of its scope wiping or
|
|
204
|
+
// navigating it, P125 S7), the display's time runs out and it has an outcome.
|
|
205
|
+
let episodeBegan: number | null = null;
|
|
175
206
|
let generation = 0;
|
|
176
207
|
// The viewer's answer for this display (P079): asked once, kept across its frames; or the
|
|
177
208
|
// host's refusal of them all (P080).
|
|
@@ -181,6 +212,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
181
212
|
: onceConsent(options.consent);
|
|
182
213
|
let abort: AbortController | null = null;
|
|
183
214
|
let outcomeWatch: OutcomeWatch | null = null;
|
|
215
|
+
let door: { readonly frame: DoorSurface; readonly watch: DoorWatch } | null = null;
|
|
216
|
+
// The addresses earlier runs were located at (P125): a ticket opens once, so a run given one
|
|
217
|
+
// again is told to the host (its outcome is the server's word, unchanged).
|
|
218
|
+
const locatedAt = new Set<string>();
|
|
184
219
|
let themeFrame: number | null = null;
|
|
185
220
|
const view = container.ownerDocument.defaultView;
|
|
186
221
|
// The adapter's own operations, the last call of each, replayed into every new frame.
|
|
@@ -492,6 +527,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
492
527
|
}
|
|
493
528
|
};
|
|
494
529
|
|
|
530
|
+
const closeDoor = () => {
|
|
531
|
+
door?.watch.stop();
|
|
532
|
+
door?.frame.destroy();
|
|
533
|
+
door = null;
|
|
534
|
+
};
|
|
535
|
+
|
|
495
536
|
const stop = () => {
|
|
496
537
|
// A run that ran a page with storage of its own making and never heard it used: no (P111).
|
|
497
538
|
if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
|
|
@@ -507,13 +548,51 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
507
548
|
abort = null;
|
|
508
549
|
outcomeWatch?.stop();
|
|
509
550
|
outcomeWatch = null;
|
|
551
|
+
closeDoor();
|
|
510
552
|
connection?.close();
|
|
511
553
|
connection = null;
|
|
512
554
|
surface?.destroy();
|
|
513
555
|
surface = null;
|
|
514
556
|
};
|
|
515
557
|
|
|
516
|
-
const
|
|
558
|
+
const timeoutMs = config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* A served display with a door (P125): its door first, alone, in a frame of the host's own;
|
|
562
|
+
* its frame only once the door said `open`, within what is left of the run's time. A door
|
|
563
|
+
* that said `blocked` (or never ran, or never answered) is the run's outcome, and nothing of
|
|
564
|
+
* the content is framed. A location without a door (an older server, a locator that drops
|
|
565
|
+
* it, a clean address someone framed) is refused before any frame is made: `blocked:
|
|
566
|
+
* locate`, and the host hears why (`door`). Nothing infers a door's word from anything else.
|
|
567
|
+
*/
|
|
568
|
+
const enter = (source: FrameSource, timeLeft = timeoutMs) => {
|
|
569
|
+
if (!hasDoor || source.kind !== "url") {
|
|
570
|
+
start(source, timeLeft);
|
|
571
|
+
return;
|
|
572
|
+
}
|
|
573
|
+
if (source.door === undefined || platform.createDoor === undefined) {
|
|
574
|
+
hostError(source.door === undefined ? NO_DOOR : NO_DOOR_PLATFORM, "door");
|
|
575
|
+
emit("outcome", { state: "blocked", reason: "locate" });
|
|
576
|
+
return;
|
|
577
|
+
}
|
|
578
|
+
const began = Date.now();
|
|
579
|
+
const frame = platform.createDoor(container, { url: source.door });
|
|
580
|
+
const watch = watchDoor({
|
|
581
|
+
door: frame,
|
|
582
|
+
timeoutMs: timeLeft,
|
|
583
|
+
onOpen: () => {
|
|
584
|
+
closeDoor();
|
|
585
|
+
start(source, Math.max(0, timeLeft - (Date.now() - began)));
|
|
586
|
+
},
|
|
587
|
+
onOutcome: (outcome) => {
|
|
588
|
+
closeDoor();
|
|
589
|
+
emit("outcome", outcome);
|
|
590
|
+
},
|
|
591
|
+
});
|
|
592
|
+
door = { frame, watch };
|
|
593
|
+
};
|
|
594
|
+
|
|
595
|
+
const start = (source: FrameSource, timeLeft: number) => {
|
|
517
596
|
const navigatedAway = () => {
|
|
518
597
|
emit("navigated", undefined);
|
|
519
598
|
if (restarts < MAX_RESTARTS) {
|
|
@@ -522,6 +601,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
522
601
|
} else {
|
|
523
602
|
stop();
|
|
524
603
|
contentError("The content kept navigating its frame away; it was stopped.");
|
|
604
|
+
// Every display ends with an outcome (P125): a frame stopped after its restarts ran out
|
|
605
|
+
// is one the host can draw a fallback for, never an empty box.
|
|
606
|
+
emit("outcome", { state: "blocked", reason: "error" });
|
|
525
607
|
}
|
|
526
608
|
};
|
|
527
609
|
const framed = platform.createSurface(container, {
|
|
@@ -587,7 +669,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
587
669
|
surface: created,
|
|
588
670
|
source,
|
|
589
671
|
speaks,
|
|
590
|
-
|
|
672
|
+
nested,
|
|
673
|
+
timeoutMs: timeLeft,
|
|
591
674
|
onOutcome: (outcome) => emit("outcome", outcome),
|
|
592
675
|
// A frame status from the content (P124): never shown, the host's to hear.
|
|
593
676
|
refused: (message) => hostError(message, "frame-status"),
|
|
@@ -679,16 +762,24 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
679
762
|
return;
|
|
680
763
|
}
|
|
681
764
|
generation += 1;
|
|
765
|
+
if (episodeBegan === null) {
|
|
766
|
+
episodeBegan = Date.now();
|
|
767
|
+
}
|
|
768
|
+
// What is left of this episode's time: a restart doesn't start the clock again.
|
|
769
|
+
const timeLeft = Math.max(0, timeoutMs - (Date.now() - episodeBegan));
|
|
682
770
|
if (config.isolation === "opaque") {
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
771
|
+
enter(
|
|
772
|
+
{
|
|
773
|
+
kind: "srcdoc",
|
|
774
|
+
html: compiled.shellDocument({
|
|
775
|
+
origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
|
|
776
|
+
title: mount.title,
|
|
777
|
+
...nonceOf(options.nonce),
|
|
778
|
+
...(mount.document === undefined ? {} : { document: mount.document }),
|
|
779
|
+
}),
|
|
780
|
+
},
|
|
781
|
+
timeLeft,
|
|
782
|
+
);
|
|
692
783
|
return;
|
|
693
784
|
}
|
|
694
785
|
const mine = generation;
|
|
@@ -700,18 +791,52 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
700
791
|
return;
|
|
701
792
|
}
|
|
702
793
|
const hostOrigin = container.ownerDocument.defaultView?.location.origin ?? "";
|
|
794
|
+
// The run's time covers locating too: a backend that never answers is a timeout.
|
|
795
|
+
const began = Date.now();
|
|
796
|
+
let settled = false;
|
|
797
|
+
const late = setTimeout(() => {
|
|
798
|
+
if (!settled && mine === generation && !destroyed) {
|
|
799
|
+
settled = true;
|
|
800
|
+
controller.abort();
|
|
801
|
+
hostError("The host's backend didn't give a location in time", "locate");
|
|
802
|
+
emit("outcome", { state: "timeout" });
|
|
803
|
+
}
|
|
804
|
+
}, timeLeft);
|
|
805
|
+
// A run stopped (destroyed, started again) stops its clock too.
|
|
806
|
+
controller.signal.addEventListener("abort", () => clearTimeout(late), { once: true });
|
|
703
807
|
locateServed(locator, instance, config, hostOrigin, controller.signal).then(
|
|
704
808
|
(source) => {
|
|
705
|
-
|
|
706
|
-
|
|
809
|
+
clearTimeout(late);
|
|
810
|
+
if (!settled && mine === generation && !destroyed) {
|
|
811
|
+
settled = true;
|
|
812
|
+
if (source.kind === "url") {
|
|
813
|
+
const seen = [source.url, ...(source.door === undefined ? [] : [source.door])];
|
|
814
|
+
if (seen.some((each) => locatedAt.has(each))) {
|
|
815
|
+
hostError(REUSED_LOCATION, "locate");
|
|
816
|
+
}
|
|
817
|
+
for (const each of seen) {
|
|
818
|
+
locatedAt.add(each);
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
enter(source, Math.max(0, timeLeft - (Date.now() - began)));
|
|
707
822
|
}
|
|
708
823
|
},
|
|
709
824
|
(error: unknown) => {
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
825
|
+
clearTimeout(late);
|
|
826
|
+
if (settled || mine !== generation || controller.signal.aborted) {
|
|
827
|
+
return;
|
|
828
|
+
}
|
|
829
|
+
settled = true;
|
|
830
|
+
// The host's own issue endpoint refused (signed out, denied, not found, P125): its
|
|
831
|
+
// word, before any frame, never the content's. Anything else is the host's own failure
|
|
832
|
+
// (its backend down, a network error, a malformed answer): `locate`, never `denied`.
|
|
833
|
+
const refused = outcomeOfRefusal(error);
|
|
834
|
+
if (refused !== null) {
|
|
835
|
+
emit("outcome", refused);
|
|
836
|
+
return;
|
|
714
837
|
}
|
|
838
|
+
hostError(error instanceof Error ? error.message : String(error), "locate");
|
|
839
|
+
emit("outcome", { state: "blocked", reason: "locate" });
|
|
715
840
|
},
|
|
716
841
|
);
|
|
717
842
|
};
|
|
@@ -754,6 +879,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
754
879
|
},
|
|
755
880
|
reload() {
|
|
756
881
|
restarts = 0;
|
|
882
|
+
episodeBegan = null;
|
|
757
883
|
run();
|
|
758
884
|
},
|
|
759
885
|
focus() {
|