@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.
Files changed (76) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/check/page.js +5 -1
  4. package/dist/compile/policy.d.ts +6 -0
  5. package/dist/compile/policy.js +6 -0
  6. package/dist/conformance/entry.d.ts +25 -6
  7. package/dist/conformance/entry.js +69 -18
  8. package/dist/conformance/harness/page.d.ts +12 -0
  9. package/dist/conformance/harness/page.js +95 -51
  10. package/dist/conformance/harness-source.js +1 -1
  11. package/dist/conformance/host-kit.js +39 -13
  12. package/dist/conformance/served.js +148 -0
  13. package/dist/files/paths.d.ts +2 -2
  14. package/dist/files/paths.js +12 -2
  15. package/dist/host/client.d.ts +8 -0
  16. package/dist/host/client.js +47 -17
  17. package/dist/host/create-host.d.ts +10 -0
  18. package/dist/host/create-host.js +124 -10
  19. package/dist/host/door.d.ts +41 -0
  20. package/dist/host/door.js +55 -0
  21. package/dist/host/locate.js +2 -0
  22. package/dist/host/locator.d.ts +55 -3
  23. package/dist/host/locator.js +152 -42
  24. package/dist/host/outcome.d.ts +54 -1
  25. package/dist/host/outcome.js +33 -8
  26. package/dist/host/types.d.ts +10 -2
  27. package/dist/isolation/served.d.ts +1 -1
  28. package/dist/isolation/served.js +35 -0
  29. package/dist/isolation/types.d.ts +20 -2
  30. package/dist/isolation/types.js +2 -0
  31. package/dist/platform/types.d.ts +22 -0
  32. package/dist/platform/web.js +55 -12
  33. package/dist/react/view.d.ts +13 -0
  34. package/dist/react/view.js +101 -2
  35. package/dist/server/files.d.ts +11 -0
  36. package/dist/server/files.js +26 -4
  37. package/dist/server/host.js +106 -28
  38. package/dist/server/index.d.ts +2 -1
  39. package/dist/server/index.js +7 -1
  40. package/dist/server/pages.d.ts +32 -0
  41. package/dist/server/pages.js +82 -6
  42. package/dist/server/server.js +194 -16
  43. package/dist/server/types.d.ts +38 -1
  44. package/dist/transport/post-message.d.ts +1 -9
  45. package/dist/transport/post-message.js +2 -8
  46. package/docs/ADOPTING.md +73 -4
  47. package/docs/DECISIONS.md +245 -0
  48. package/docs/DESIGN.md +24 -18
  49. package/docs/THREAT_MODEL.md +79 -13
  50. package/package.json +1 -1
  51. package/src/check/page.ts +6 -1
  52. package/src/compile/policy.ts +7 -0
  53. package/src/conformance/entry.ts +129 -24
  54. package/src/conformance/harness/page.ts +112 -49
  55. package/src/conformance/host-kit.ts +53 -16
  56. package/src/conformance/served.ts +184 -0
  57. package/src/files/paths.ts +11 -2
  58. package/src/host/client.ts +59 -22
  59. package/src/host/create-host.ts +144 -18
  60. package/src/host/door.ts +97 -0
  61. package/src/host/locate.ts +2 -0
  62. package/src/host/locator.ts +208 -57
  63. package/src/host/outcome.ts +41 -9
  64. package/src/host/types.ts +10 -2
  65. package/src/isolation/served.ts +40 -1
  66. package/src/isolation/types.ts +19 -2
  67. package/src/platform/types.ts +21 -0
  68. package/src/platform/web.ts +55 -20
  69. package/src/react/view.tsx +149 -2
  70. package/src/server/files.ts +37 -5
  71. package/src/server/host.ts +131 -46
  72. package/src/server/index.ts +7 -1
  73. package/src/server/pages.ts +101 -6
  74. package/src/server/server.ts +266 -32
  75. package/src/server/types.ts +41 -1
  76. package/src/transport/post-message.ts +1 -9
@@ -1,3 +1,4 @@
1
+ import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
1
2
  import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
2
3
  import type { FrameBlock } from "../host/types.ts";
3
4
  import { base64url, sha256, utf8 } from "./crypto.ts";
@@ -142,15 +143,16 @@ export function enterPage(
142
143
  return new Response(body, { status: 200, headers });
143
144
  }
144
145
 
145
- /** The status script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
146
- let statusHash: string | null = null;
147
- const hashOfStatus = (): string => {
148
- statusHash ??= base64url(sha256(utf8(STATUS_SCRIPT)))
146
+ /** A script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
147
+ const hashOf = (script: string): string => {
148
+ const hash = base64url(sha256(utf8(script)))
149
149
  .replace(/-/gu, "+")
150
150
  .replace(/_/gu, "/");
151
- const padding = (4 - (statusHash.length % 4)) % 4;
152
- return `'sha256-${statusHash}${"=".repeat(padding)}'`;
151
+ const padding = (4 - (hash.length % 4)) % 4;
152
+ return `'sha256-${hash}${"=".repeat(padding)}'`;
153
153
  };
154
+ let statusHash: string | null = null;
155
+ const hashOfStatus = (): string => (statusHash ??= hashOf(STATUS_SCRIPT));
154
156
 
155
157
  /**
156
158
  * A redirect entry's page on the app's own origin (P068): why it shows nothing, told to the page
@@ -212,3 +214,96 @@ export function statusPageOf(options: {
212
214
  options.method,
213
215
  );
214
216
  }
217
+
218
+ /** A door's word that its display may be framed (P125), from the page's data attributes. */
219
+ const DOOR_SCRIPT = `(() => {
220
+ const main = document.querySelector("[data-porthole-door]");
221
+ if (main === null) return;
222
+ const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
223
+ ${say()}
224
+ say({ state: "open" });
225
+ })();`;
226
+ let doorHash: string | null = null;
227
+ const hashOfDoor = (): string => (doorHash ??= hashOf(DOOR_SCRIPT));
228
+
229
+ /**
230
+ * A door's headers (P125): its one script by its hash (an opaque document has no `'self'` to load
231
+ * one from), nothing else loads, sandboxed with scripts alone in its header too (opaque on a tab, and
232
+ * in a frame whose attribute a host's own platform forgot), framed by the host origins, never
233
+ * cached, never sent on, no cookie.
234
+ */
235
+ const doorHeaders = (script: string, frameAncestors: string): Headers =>
236
+ new Headers({
237
+ "content-type": "text/html; charset=utf-8",
238
+ "cache-control": "no-store",
239
+ "content-security-policy": `default-src 'none'; script-src ${script}; base-uri 'none'; form-action 'none'; sandbox ${DOOR_SANDBOX_TOKENS.join(" ")}; frame-ancestors ${frameAncestors}`,
240
+ "referrer-policy": "no-referrer",
241
+ "x-content-type-options": "nosniff",
242
+ "x-robots-tag": "noindex, nofollow",
243
+ });
244
+
245
+ /** What a door is given: the host origins it tells, and who may frame it (default, those). */
246
+ export interface DoorOptions {
247
+ readonly hostOrigins: readonly string[];
248
+ readonly frameAncestors?: string;
249
+ readonly method?: string;
250
+ }
251
+
252
+ /**
253
+ * A door that opens (P125): its display may be framed. It says `open` to the page that frames it,
254
+ * at each web host origin and (a desktop scheme among them) to its parent (P070), once, as it
255
+ * parses. For a content Worker of a host's own: answer it at `DOOR_PATH<key>` only once the door's
256
+ * own ticket was taken and the checks the content's address runs passed for the same grant.
257
+ */
258
+ export function doorResponse(options: DoorOptions): Response {
259
+ const hosts = escape(JSON.stringify(options.hostOrigins));
260
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Opening</title></head><body><main data-porthole-door="" data-porthole-hosts="${hosts}"></main><script>${DOOR_SCRIPT}</script></body></html>`;
261
+ return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
262
+ status: 200,
263
+ headers: doorHeaders(hashOfDoor(), options.frameAncestors ?? options.hostOrigins.join(" ")),
264
+ });
265
+ }
266
+
267
+ /**
268
+ * A door that doesn't open (P125): why, said `blocked` to the page that frames it, as a content
269
+ * origin's status page says it (`session` 401: no ticket, or one used, ended, or not a door's of
270
+ * this instance on this origin; `denied` 403 with the host's code; `not-found` 404: no document, or
271
+ * a file set whose entry isn't a page; `error` 500).
272
+ */
273
+ export function doorStatusResponse(
274
+ options: DoorOptions & {
275
+ readonly status: number;
276
+ readonly reason: FrameBlock;
277
+ readonly code?: string;
278
+ },
279
+ ): Response {
280
+ const { status, reason, code } = options;
281
+ const hosts = escape(JSON.stringify(options.hostOrigins));
282
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Not shown</title></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} data-porthole-hosts="${hosts}"></main><script>${STATUS_SCRIPT}</script></body></html>`;
283
+ return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
284
+ status,
285
+ headers: doorHeaders(hashOfStatus(), options.frameAncestors ?? options.hostOrigins.join(" ")),
286
+ });
287
+ }
288
+
289
+ /**
290
+ * What a clean address answers in a frame (P125): a clean address is for a tab of its own, so in a
291
+ * frame it never goes to the app (no authorize, no sign-in, no refusal page of the app's) and says
292
+ * nothing to the page that frames it: no script at all, under the status pages' policy without
293
+ * `script-src` (so `default-src 'none'` forbids every script), framed by the host origins only. A
294
+ * host frames what a clean address names by resolving it through `issue` (`client.resolve`).
295
+ */
296
+ export function tabOnlyPage(frameAncestors: string, method = "GET"): Response {
297
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Open this in a new tab</title><style>${STYLE}</style></head><body><main data-porthole-tab-only=""><h1>Open this in a new tab</h1><p>This address opens in a tab of its own, not inside a frame.</p></main></body></html>`;
298
+ return new Response(method.toUpperCase() === "HEAD" ? null : body, {
299
+ status: 403,
300
+ headers: {
301
+ "content-type": "text/html; charset=utf-8",
302
+ "cache-control": "no-store",
303
+ "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
304
+ "referrer-policy": "no-referrer",
305
+ "x-content-type-options": "nosniff",
306
+ "x-robots-tag": "noindex, nofollow",
307
+ },
308
+ });
309
+ }
@@ -6,14 +6,27 @@ import {
6
6
  originMatchesSource,
7
7
  parseOrigin,
8
8
  } from "../isolation/served.ts";
9
- import type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
9
+ import {
10
+ DOOR_PATH,
11
+ type FrameLocation,
12
+ type InstanceRef,
13
+ type ServedDocument,
14
+ } from "../isolation/types.ts";
10
15
  import { sandboxProxyDocument } from "../mcp/proxy.ts";
11
16
  import { base32, createKeys, newTicket, ticketId } from "./keys.ts";
12
17
  import { randomBytes } from "./crypto.ts";
13
18
  import { isHostLabel, reservedLabels } from "./naming.ts";
14
- import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
19
+ import {
20
+ doorResponse,
21
+ doorStatusResponse,
22
+ enterPage,
23
+ pageScript,
24
+ SESSION_PATH,
25
+ statusPage,
26
+ tabOnlyPage,
27
+ } from "./pages.ts";
15
28
  import { libraryFile } from "./libraries.ts";
16
- import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.ts";
29
+ import { isNavigation, ownLoad, serveAsset, serveFile, ticketPage } from "./files.ts";
17
30
  import {
18
31
  isNestedLabel,
19
32
  nestedAncestors,
@@ -23,6 +36,7 @@ import {
23
36
  PORTHOLE_LABEL_PREFIX,
24
37
  } from "./nested.ts";
25
38
  import { DEFAULT_ENTRY } from "../files/paths.ts";
39
+ import { isPagePath } from "../files/types.ts";
26
40
  import { isPortholeCookie, setsPortholeCookie } from "./proxy.ts";
27
41
  import {
28
42
  assetCodeRuns,
@@ -54,6 +68,8 @@ import type {
54
68
  const PREFIX = "/__porthole/";
55
69
  /** A served document (shell, artifact page, sandbox proxy), by its instance's key. */
56
70
  const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
71
+ /** A served display's door (P125), by its instance's key: `DOOR_PATH<key>`. */
72
+ const DOOR_ROUTE = /^\/__porthole\/door\/([a-z2-7]{16})$/u;
57
73
  /**
58
74
  * A file set's files in a frame (P083): `/__porthole/f/<sealed access>/<path>`. The access is
59
75
  * in the path, so a frame whose engine keeps no cookie (WebKit, P025) loads them too.
@@ -159,6 +175,12 @@ interface FilesAt {
159
175
  const isRecord = (value: unknown): value is Record<string, unknown> =>
160
176
  value !== null && typeof value === "object" && !Array.isArray(value);
161
177
 
178
+ /** Whether a file set opens at a page of its own (P125, P124-2): its entry is a file, and a page. */
179
+ const entryIsPage = (set: StoredFiles): boolean => {
180
+ const entry = set.entry ?? DEFAULT_ENTRY;
181
+ return Object.hasOwn(set.files, entry) && isPagePath(entry);
182
+ };
183
+
162
184
  const isStoredFiles = (stored: StoredVersion): stored is StoredFiles =>
163
185
  isRecord(stored) &&
164
186
  isRecord((stored as Partial<StoredFiles>).files) &&
@@ -453,6 +475,24 @@ export function createServer(options: ServerOptions): PortholeServer {
453
475
  * page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
454
476
  */
455
477
  async function denied(request: Request, access: Access): Promise<Response | null> {
478
+ const refused = await refusalOf(request, access);
479
+ return refused === null
480
+ ? null
481
+ : page(
482
+ 403,
483
+ "You can't open this anymore",
484
+ "The app that showed it no longer lets you see it here.",
485
+ request.method.toUpperCase(),
486
+ "denied",
487
+ refused.code,
488
+ );
489
+ }
490
+
491
+ /** The host's check (P050): null to go on, or its refusal and the host's code, if a good one. */
492
+ async function refusalOf(
493
+ request: Request,
494
+ access: Access,
495
+ ): Promise<{ readonly code?: string } | null> {
456
496
  if (authorize === undefined) {
457
497
  return null;
458
498
  }
@@ -497,14 +537,7 @@ export function createServer(options: ServerOptions): PortholeServer {
497
537
  return null;
498
538
  }
499
539
  const code = typeof given?.code === "string" && CODE.test(given.code) ? given.code : undefined;
500
- return page(
501
- 403,
502
- "You can't open this anymore",
503
- "The app that showed it no longer lets you see it here.",
504
- request.method.toUpperCase(),
505
- "denied",
506
- code,
507
- );
540
+ return code === undefined ? {} : { code };
508
541
  }
509
542
 
510
543
  /** The config a served document is served under, checked to fit it and this server. */
@@ -1058,9 +1091,11 @@ export function createServer(options: ServerOptions): PortholeServer {
1058
1091
  // still shows it. The cookie serves what follows (a reload), where the engine keeps it.
1059
1092
  const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
1060
1093
  // An entry code opens its clean address alone, through its own browser's nonce (P068, P114).
1094
+ // A door's ticket is the door's alone (P125): here it is no ticket.
1061
1095
  if (
1062
1096
  record !== null &&
1063
1097
  record.entry === undefined &&
1098
+ record.door !== true &&
1064
1099
  record.instance.document.kind !== "external" &&
1065
1100
  keys.instanceKey(record.instance) === key
1066
1101
  ) {
@@ -1090,6 +1125,102 @@ export function createServer(options: ServerOptions): PortholeServer {
1090
1125
  return serveAccess(request, access, cookie, undefined, rest);
1091
1126
  }
1092
1127
 
1128
+ /** A door that doesn't open (P125): its status, reason and the host's code, if any. */
1129
+ const doorSays = (status: number, reason: FrameBlock, method: string, code?: string): Response =>
1130
+ doorStatusResponse({
1131
+ status,
1132
+ reason,
1133
+ ...(code === undefined ? {} : { code }),
1134
+ hostOrigins: options.hostOrigins,
1135
+ frameAncestors,
1136
+ method,
1137
+ });
1138
+
1139
+ /**
1140
+ * A served display's door (P125): its own ticket's, taken once, for this instance on this
1141
+ * origin; then the door's answer for that ticket's grant (`answerDoor`, the one `doorAnswer`
1142
+ * gives, P126). No other ticket opens it, and a nested page's shell's label serves none
1143
+ * (`serveShellLabel`).
1144
+ */
1145
+ async function serveDoor(
1146
+ request: Request,
1147
+ url: URL,
1148
+ label: string,
1149
+ key: string,
1150
+ ): Promise<Response> {
1151
+ const method = request.method.toUpperCase();
1152
+ if (method !== "GET" && method !== "HEAD") {
1153
+ return doorSays(405, "error", method);
1154
+ }
1155
+ let record: TicketRecord | null;
1156
+ try {
1157
+ record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
1158
+ if (
1159
+ record === null ||
1160
+ record.door !== true ||
1161
+ record.entry !== undefined ||
1162
+ record.instance.document.kind === "external" ||
1163
+ keys.instanceKey(record.instance) !== key ||
1164
+ compiledFor(record.instance)?.config.nested === true
1165
+ ) {
1166
+ return doorSays(401, "session", method);
1167
+ }
1168
+ } catch {
1169
+ return doorSays(500, "error", method);
1170
+ }
1171
+ return answerDoor(
1172
+ request,
1173
+ {
1174
+ instance: record.instance,
1175
+ viewer: record.viewer,
1176
+ origin: originOfLabel(label),
1177
+ expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
1178
+ ...(record.anonymous === true ? { anonymous: true } : {}),
1179
+ ...(record.subject === undefined ? {} : { subject: record.subject }),
1180
+ },
1181
+ isPageRest(record.page) ? record.page : undefined,
1182
+ );
1183
+ }
1184
+
1185
+ /**
1186
+ * The door's answer for an access already admitted (P125, P126): the checks the content's
1187
+ * address runs for the same grant (the host's check, the document, its entry, the page it opens
1188
+ * at), so the door says what the content's address would: `open`, or `blocked` and why. It sets
1189
+ * no cookie and serves nothing of the content; the content's address takes its own ticket and
1190
+ * checks again (P050), so the door only tells. `serveDoor` answers with it once its ticket is
1191
+ * taken, and `doorAnswer` for a host that admitted the request itself: one answer for both.
1192
+ */
1193
+ async function answerDoor(
1194
+ request: Request,
1195
+ access: Access,
1196
+ /** A page below a file set's base its frame opens at (P125). */
1197
+ below: string | undefined,
1198
+ ): Promise<Response> {
1199
+ const method = request.method.toUpperCase();
1200
+ if (method !== "GET" && method !== "HEAD") {
1201
+ return doorSays(405, "error", method);
1202
+ }
1203
+ try {
1204
+ const refused = await refusalOf(request, access);
1205
+ if (refused !== null) {
1206
+ return doorSays(403, "denied", method, refused.code);
1207
+ }
1208
+ const served = await documentOf(access.instance);
1209
+ // The same document, entry and page checks the content's address runs (`serveAccess`).
1210
+ if (
1211
+ served === null ||
1212
+ ("files" in served
1213
+ ? !entryIsPage(served.files) || ticketPage(served.files, below) === null
1214
+ : below !== undefined)
1215
+ ) {
1216
+ return doorSays(404, "not-found", method);
1217
+ }
1218
+ return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
1219
+ } catch {
1220
+ return doorSays(500, "error", method);
1221
+ }
1222
+ }
1223
+
1093
1224
  /**
1094
1225
  * The document an access opens, once the host's check lets it in: at its document's path, or
1095
1226
  * (`at`) a path under a file set's base (P081).
@@ -1111,6 +1242,20 @@ export function createServer(options: ServerOptions): PortholeServer {
1111
1242
  if (served === null) {
1112
1243
  return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1113
1244
  }
1245
+ // A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
1246
+ // stored before that was checked shows Porthole's word, never an inert file that says nothing.
1247
+ if ("files" in served && at === undefined && !entryIsPage(served.files)) {
1248
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1249
+ }
1250
+ // A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
1251
+ // the page the frame opens at (its entry, or the page it was issued for) must be one of its
1252
+ // pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
1253
+ if (
1254
+ at === undefined &&
1255
+ ("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)
1256
+ ) {
1257
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1258
+ }
1114
1259
  // A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
1115
1260
  // one's) answers Porthole's shell, which frames the page at its sealed files' address; only
1116
1261
  // that address, below the sealed prefix, answers the page and its files, without a cookie.
@@ -1189,7 +1334,7 @@ export function createServer(options: ServerOptions): PortholeServer {
1189
1334
  compiled: served.compiled,
1190
1335
  hostOrigins: options.hostOrigins,
1191
1336
  frameAncestors,
1192
- ticket: { expires: sealed.expires },
1337
+ ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
1193
1338
  ...versionOf(access.instance),
1194
1339
  });
1195
1340
  }
@@ -1418,6 +1563,13 @@ export function createServer(options: ServerOptions): PortholeServer {
1418
1563
  */
1419
1564
  async function beginEntry(request: Request, url: URL, label: string, to: URL): Promise<Response> {
1420
1565
  const method = request.method.toUpperCase();
1566
+ // A clean address is for a tab (P125): in a frame it never goes to the app (no authorize, no
1567
+ // sign-in, no refusal of the app's) and says nothing to the page that frames it, whatever it
1568
+ // names. A host frames what a clean address names by resolving it through `issue`.
1569
+ const framedAs = request.headers.get("sec-fetch-dest");
1570
+ if (framedAs === "iframe" || framedAs === "frame") {
1571
+ return tabOnlyPage(frameAncestors, method);
1572
+ }
1421
1573
  // An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
1422
1574
  const scopeOf = content.name?.scopeOf;
1423
1575
  const named = options.entry?.named;
@@ -1715,14 +1867,11 @@ export function createServer(options: ServerOptions): PortholeServer {
1715
1867
  return page(404, "Nothing here", "This address names no content.", method);
1716
1868
  }
1717
1869
 
1718
- /** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
1719
- async function mint(
1720
- instance: InstanceRef,
1870
+ /** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
1871
+ function checkGrant(
1872
+ clean: InstanceRef,
1721
1873
  grant: Grant,
1722
- entry?: TicketRecord["entry"],
1723
- ): Promise<{ readonly clean: InstanceRef; readonly key: string; readonly ticket: string }> {
1724
- const clean = cleanInstance(instance);
1725
- check(clean);
1874
+ ): { readonly anonymous: boolean; readonly viewer: string } {
1726
1875
  const anonymous = grant.anonymous === true;
1727
1876
  if (anonymous) {
1728
1877
  if (grant.viewer !== undefined) {
@@ -1744,15 +1893,33 @@ export function createServer(options: ServerOptions): PortholeServer {
1744
1893
  ) {
1745
1894
  throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
1746
1895
  }
1896
+ return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
1897
+ }
1898
+
1899
+ /** How long a grant's session lasts, checked (`sessionSeconds`). */
1900
+ const sessionOf = (grant: Grant): number =>
1901
+ seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
1902
+
1903
+ /** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
1904
+ async function mint(
1905
+ instance: InstanceRef,
1906
+ grant: Grant,
1907
+ entry?: TicketRecord["entry"],
1908
+ /** A page below a file set's base its frame opens at (P125: a clean address's file). */
1909
+ below?: string,
1910
+ ): Promise<{
1911
+ readonly clean: InstanceRef;
1912
+ readonly key: string;
1913
+ readonly ticket: string;
1914
+ /** The door's own ticket (P125), for a display framed on its scope's origin. */
1915
+ readonly door: string | null;
1916
+ }> {
1917
+ const clean = cleanInstance(instance);
1918
+ check(clean);
1919
+ const { anonymous, viewer } = checkGrant(clean, grant);
1747
1920
  const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
1748
- const sessionSeconds = seconds(
1749
- grant.sessionSeconds,
1750
- DEFAULT_SESSION_SECONDS,
1751
- MAX_SESSION_SECONDS,
1752
- "sessionSeconds",
1753
- );
1921
+ const sessionSeconds = sessionOf(grant);
1754
1922
  const key = keys.instanceKey(clean);
1755
- const viewer = anonymous ? "" : grant.viewer;
1756
1923
  const probe = keys.sign({
1757
1924
  i: clean,
1758
1925
  w: viewer,
@@ -1768,7 +1935,7 @@ export function createServer(options: ServerOptions): PortholeServer {
1768
1935
  throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
1769
1936
  }
1770
1937
  const ticket = newTicket();
1771
- await tickets.put(ticketId(ticket), {
1938
+ const record: TicketRecord = {
1772
1939
  instance: clean,
1773
1940
  viewer,
1774
1941
  expiresAt: Date.now() + ttl * 1_000,
@@ -1776,8 +1943,25 @@ export function createServer(options: ServerOptions): PortholeServer {
1776
1943
  ...(anonymous ? { anonymous: true } : {}),
1777
1944
  ...(grant.subject === undefined ? {} : { subject: grant.subject }),
1778
1945
  ...(entry === undefined ? {} : { entry }),
1779
- });
1780
- return { clean, key, ticket };
1946
+ ...(below === undefined ? {} : { page: below }),
1947
+ };
1948
+ await tickets.put(ticketId(ticket), record);
1949
+ // A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
1950
+ let door: string | null = null;
1951
+ if (entry === undefined && hasDoor(clean)) {
1952
+ door = newTicket();
1953
+ await tickets.put(ticketId(door), { ...record, door: true });
1954
+ }
1955
+ return { clean, key, ticket, door };
1956
+ }
1957
+
1958
+ /**
1959
+ * Whether an instance's frame has a door (P125): a document framed on its scope's origin, where
1960
+ * the scope's other displays run content (a served shell, a page that isn't nested, the sandbox
1961
+ * proxy). A nested page's frame is its shell, on a label of its own; a url-mode app has none.
1962
+ */
1963
+ function hasDoor(instance: InstanceRef): boolean {
1964
+ return instance.document.kind !== "external" && compiledFor(instance)?.config.nested !== true;
1781
1965
  }
1782
1966
 
1783
1967
  const underDomain = (host: string): boolean => host === domain || host.endsWith(`.${domain}`);
@@ -1832,8 +2016,15 @@ export function createServer(options: ServerOptions): PortholeServer {
1832
2016
 
1833
2017
  originFor: (scope) => originOfLabel(nameOf(scope)),
1834
2018
 
1835
- async issue(instance, grant): Promise<FrameLocation> {
1836
- const { clean, key, ticket } = await mint(instance, grant);
2019
+ async issue(instance, grant, at = {}): Promise<FrameLocation> {
2020
+ // A page below a file set's base (P125: what a clean address names, resolved for a frame).
2021
+ const below = at.page;
2022
+ if (below !== undefined && (!isPageRest(below) || instance.document?.kind !== "artifact")) {
2023
+ throw new TypeError(
2024
+ "A frame's page is a relative path below an artifact's files (no . or ..)",
2025
+ );
2026
+ }
2027
+ const { clean, key, ticket, door } = await mint(instance, grant, undefined, below);
1837
2028
  // A nested page's frame is its shell, on the shell's own label (P114).
1838
2029
  const origin = originOfLabel(labelFor(clean));
1839
2030
  const path =
@@ -1842,7 +2033,46 @@ export function createServer(options: ServerOptions): PortholeServer {
1842
2033
  : `${PREFIX}d/${key}?ticket=${ticket}`;
1843
2034
  // The viewer's level, as the host's access decided it now (P087): for the display's bridge.
1844
2035
  const viewer = viewerOfGrant(grant);
1845
- return { url: `${origin}${path}`, origin, reports: true, ...(viewer ? { viewer } : {}) };
2036
+ return {
2037
+ url: `${origin}${path}`,
2038
+ origin,
2039
+ reports: true,
2040
+ ...(viewer ? { viewer } : {}),
2041
+ // Its door (P125): the host frames it first, and takes its word alone.
2042
+ ...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
2043
+ };
2044
+ },
2045
+
2046
+ async doorAnswer(instance, grant, request, at = {}): Promise<Response> {
2047
+ // A host that admitted the request itself (P126): no ticket here, the grant is its word.
2048
+ const clean = cleanInstance(instance);
2049
+ check(clean);
2050
+ if (!hasDoor(clean)) {
2051
+ throw new TypeError(
2052
+ "This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none",
2053
+ );
2054
+ }
2055
+ const below = at.page;
2056
+ if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
2057
+ throw new TypeError(
2058
+ "A frame's page is a relative path below an artifact's files (no . or ..)",
2059
+ );
2060
+ }
2061
+ const { anonymous, viewer } = checkGrant(clean, grant);
2062
+ const sessionSeconds = sessionOf(grant);
2063
+ const origin = originOfLabel(labelFor(clean));
2064
+ return answerDoor(
2065
+ request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`),
2066
+ {
2067
+ instance: clean,
2068
+ viewer,
2069
+ origin,
2070
+ expiresAt: Date.now() + sessionSeconds * 1_000,
2071
+ ...(anonymous ? { anonymous: true } : {}),
2072
+ ...(grant.subject === undefined ? {} : { subject: grant.subject }),
2073
+ },
2074
+ below,
2075
+ );
1846
2076
  },
1847
2077
 
1848
2078
  forget(filter = {}) {
@@ -2004,6 +2234,10 @@ export function createServer(options: ServerOptions): PortholeServer {
2004
2234
  if (asset?.[1] !== undefined) {
2005
2235
  return await serveAssetAt(request, label, asset[1]);
2006
2236
  }
2237
+ const door = DOOR_ROUTE.exec(url.pathname);
2238
+ if (door?.[1] !== undefined) {
2239
+ return await serveDoor(request, url, label, door[1]);
2240
+ }
2007
2241
  const document = DOCUMENT_PATH.exec(url.pathname);
2008
2242
  if (document?.[1] !== undefined) {
2009
2243
  return await serveDocument(request, url, label, document[1]);
@@ -106,6 +106,13 @@ export interface TicketRecord {
106
106
  * its files' base the shell opens (the entry page when absent).
107
107
  */
108
108
  readonly page?: string;
109
+ /**
110
+ * A door's ticket (P125): `issue` mints one beside the content's, for the same grant and as
111
+ * long, for a display whose frame is on its scope's origin (a served shell, a page that isn't
112
+ * nested, the sandbox proxy). Taken only at the door (`/__porthole/door/<key>`), never at the
113
+ * content's address; the door takes no other.
114
+ */
115
+ readonly door?: true;
109
116
  }
110
117
 
111
118
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
@@ -326,7 +333,40 @@ export interface PortholeServer {
326
333
  * Mints a one-time ticket for `instance` and returns the URL its frame loads. Call it from the
327
334
  * host's own authenticated API, once the host has decided the viewer may see the instance.
328
335
  */
329
- issue(instance: InstanceRef, grant: Grant): Promise<FrameLocation>;
336
+ issue(
337
+ instance: InstanceRef,
338
+ grant: Grant,
339
+ /**
340
+ * Where in the instance its frame opens (P125): a page below a file set's base (what a clean
341
+ * address names, resolved by `issue` given `{ address }`). Default: its entry.
342
+ */
343
+ at?: { readonly page?: string },
344
+ ): Promise<FrameLocation>;
345
+ /**
346
+ * A served display's door answer for a grant the host has already admitted (P126): exactly the
347
+ * Response its door (`DOOR_PATH<key>`, P125) answers once it has taken its own ticket for that
348
+ * instance and grant. The content's address's checks for that grant run here: the host's
349
+ * `authorize` check (`denied`, with its code), the document and its version (`not-found`), a file
350
+ * set's entry being a page and the page `at` names (`not-found`). The answer is `doorResponse`
351
+ * (open) or `doorStatusResponse` (blocked: reason, status, code), with the door's CSP (`sandbox
352
+ * allow-scripts`, `frame-ancestors` the host origins), `no-store`, and no cookie.
353
+ *
354
+ * It is a function, not a route, and it never takes a ticket: it is for a host that signs its own
355
+ * tickets (a content Worker that verifies them itself) and answers its door with it. The caller
356
+ * must have authenticated the request and established the grant itself, as it does before
357
+ * `issue`; Porthole's own door route takes its door ticket and then answers with this. `request`
358
+ * is what `authorize.check` is handed (and gives the method: HEAD has no body, a method other
359
+ * than GET or HEAD is 405); default, a GET of the door on the instance's origin. Throws, as
360
+ * `issue` does, for an instance or grant `issue` would refuse, and for an instance with no door
361
+ * (a nested page, a url-mode app).
362
+ */
363
+ doorAnswer(
364
+ instance: InstanceRef,
365
+ grant: Grant,
366
+ request?: Request,
367
+ /** The page below a file set's base the frame opens at, as `issue`'s `at` (P125). */
368
+ at?: { readonly page?: string },
369
+ ): Promise<Response>;
330
370
  /**
331
371
  * The access a request's cookie carries for a url-mode app on the request's origin, or null
332
372
  * (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
@@ -12,11 +12,6 @@ export function postMessageTransport(
12
12
  frameWindow: () => Window | null,
13
13
  expectedOrigin: string,
14
14
  host: Window = window,
15
- /**
16
- * Another origin the frame's window may say some things from: the host's own, whose pages a
17
- * served frame passes through on a redirect entry (P068), for their frame status only.
18
- */
19
- also?: { readonly origin: string; readonly accept: (data: unknown) => boolean },
20
15
  ): Transport {
21
16
  const listeners = new Set<(message: unknown) => void>();
22
17
  let closed = false;
@@ -25,10 +20,7 @@ export function postMessageTransport(
25
20
  if (closed || source === null || event.source !== source) {
26
21
  return;
27
22
  }
28
- if (
29
- event.origin !== expectedOrigin &&
30
- (also === undefined || event.origin !== also.origin || !also.accept(event.data))
31
- ) {
23
+ if (event.origin !== expectedOrigin) {
32
24
  return;
33
25
  }
34
26
  for (const listener of listeners) {