@botiverse/porthole 0.14.4 → 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.
Files changed (78) hide show
  1. package/CHANGELOG.md +71 -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 +140 -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 +126 -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 +58 -1
  25. package/dist/host/outcome.js +74 -6
  26. package/dist/host/types.d.ts +20 -4
  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/frame.d.ts +2 -1
  34. package/dist/react/view.d.ts +13 -0
  35. package/dist/react/view.js +101 -2
  36. package/dist/server/files.d.ts +11 -0
  37. package/dist/server/files.js +26 -4
  38. package/dist/server/host.js +106 -28
  39. package/dist/server/index.d.ts +2 -1
  40. package/dist/server/index.js +6 -1
  41. package/dist/server/pages.d.ts +32 -0
  42. package/dist/server/pages.js +82 -6
  43. package/dist/server/server.js +140 -11
  44. package/dist/server/types.d.ts +15 -1
  45. package/dist/transport/post-message.d.ts +1 -9
  46. package/dist/transport/post-message.js +2 -8
  47. package/docs/ADOPTING.md +58 -0
  48. package/docs/DECISIONS.md +290 -0
  49. package/docs/DESIGN.md +24 -16
  50. package/docs/THREAT_MODEL.md +98 -3
  51. package/package.json +1 -1
  52. package/src/check/page.ts +6 -1
  53. package/src/compile/policy.ts +7 -0
  54. package/src/conformance/entry.ts +129 -24
  55. package/src/conformance/harness/page.ts +112 -49
  56. package/src/conformance/host-kit.ts +53 -16
  57. package/src/conformance/served.ts +175 -0
  58. package/src/files/paths.ts +11 -2
  59. package/src/host/client.ts +59 -22
  60. package/src/host/create-host.ts +146 -18
  61. package/src/host/door.ts +97 -0
  62. package/src/host/locate.ts +2 -0
  63. package/src/host/locator.ts +208 -57
  64. package/src/host/outcome.ts +88 -7
  65. package/src/host/types.ts +20 -4
  66. package/src/isolation/served.ts +40 -1
  67. package/src/isolation/types.ts +19 -2
  68. package/src/platform/types.ts +21 -0
  69. package/src/platform/web.ts +55 -20
  70. package/src/react/frame.tsx +2 -1
  71. package/src/react/view.tsx +149 -2
  72. package/src/server/files.ts +37 -5
  73. package/src/server/host.ts +131 -46
  74. package/src/server/index.ts +6 -1
  75. package/src/server/pages.ts +101 -6
  76. package/src/server/server.ts +186 -19
  77. package/src/server/types.ts +16 -1
  78. package/src/transport/post-message.ts +1 -9
@@ -1,14 +1,16 @@
1
1
  import { compile } from "../compile/compile.js";
2
2
  import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
3
+ import { DOOR_PATH, } from "../isolation/types.js";
3
4
  import { sandboxProxyDocument } from "../mcp/proxy.js";
4
5
  import { base32, createKeys, newTicket, ticketId } from "./keys.js";
5
6
  import { randomBytes } from "./crypto.js";
6
7
  import { isHostLabel, reservedLabels } from "./naming.js";
7
- import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
8
+ import { doorResponse, doorStatusResponse, enterPage, pageScript, SESSION_PATH, statusPage, tabOnlyPage, } from "./pages.js";
8
9
  import { libraryFile } from "./libraries.js";
9
- import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.js";
10
+ import { isNavigation, ownLoad, serveAsset, serveFile, ticketPage } from "./files.js";
10
11
  import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedFileCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
11
12
  import { DEFAULT_ENTRY } from "../files/paths.js";
13
+ import { isPagePath } from "../files/types.js";
12
14
  import { isPortholeCookie, setsPortholeCookie } from "./proxy.js";
13
15
  import { assetCodeRuns, assetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, } from "../compile/policy.js";
14
16
  import { parseViewer } from "../runtime/levels.js";
@@ -20,6 +22,8 @@ import { memoryTicketStore } from "./tickets.js";
20
22
  const PREFIX = "/__porthole/";
21
23
  /** A served document (shell, artifact page, sandbox proxy), by its instance's key. */
22
24
  const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
25
+ /** A served display's door (P125), by its instance's key: `DOOR_PATH<key>`. */
26
+ const DOOR_ROUTE = /^\/__porthole\/door\/([a-z2-7]{16})$/u;
23
27
  /**
24
28
  * A file set's files in a frame (P083): `/__porthole/f/<sealed access>/<path>`. The access is
25
29
  * in the path, so a frame whose engine keeps no cookie (WebKit, P025) loads them too.
@@ -87,6 +91,11 @@ function normalHost(value, protocol) {
87
91
  : host;
88
92
  }
89
93
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
94
+ /** Whether a file set opens at a page of its own (P125, P124-2): its entry is a file, and a page. */
95
+ const entryIsPage = (set) => {
96
+ const entry = set.entry ?? DEFAULT_ENTRY;
97
+ return Object.hasOwn(set.files, entry) && isPagePath(entry);
98
+ };
90
99
  const isStoredFiles = (stored) => isRecord(stored) &&
91
100
  isRecord(stored.files) &&
92
101
  typeof stored.read === "function";
@@ -334,6 +343,13 @@ export function createServer(options) {
334
343
  * page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
335
344
  */
336
345
  async function denied(request, access) {
346
+ const refused = await refusalOf(request, access);
347
+ return refused === null
348
+ ? null
349
+ : page(403, "You can't open this anymore", "The app that showed it no longer lets you see it here.", request.method.toUpperCase(), "denied", refused.code);
350
+ }
351
+ /** The host's check (P050): null to go on, or its refusal and the host's code, if a good one. */
352
+ async function refusalOf(request, access) {
337
353
  if (authorize === undefined) {
338
354
  return null;
339
355
  }
@@ -379,7 +395,7 @@ export function createServer(options) {
379
395
  return null;
380
396
  }
381
397
  const code = typeof given?.code === "string" && CODE.test(given.code) ? given.code : undefined;
382
- return page(403, "You can't open this anymore", "The app that showed it no longer lets you see it here.", request.method.toUpperCase(), "denied", code);
398
+ return code === undefined ? {} : { code };
383
399
  }
384
400
  /** The config a served document is served under, checked to fit it and this server. */
385
401
  function configFor(name, kind) {
@@ -838,8 +854,10 @@ export function createServer(options) {
838
854
  // still shows it. The cookie serves what follows (a reload), where the engine keeps it.
839
855
  const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
840
856
  // An entry code opens its clean address alone, through its own browser's nonce (P068, P114).
857
+ // A door's ticket is the door's alone (P125): here it is no ticket.
841
858
  if (record !== null &&
842
859
  record.entry === undefined &&
860
+ record.door !== true &&
843
861
  record.instance.document.kind !== "external" &&
844
862
  keys.instanceKey(record.instance) === key) {
845
863
  cookie = sessionCookie(request, record);
@@ -861,6 +879,64 @@ export function createServer(options) {
861
879
  const rest = isPageRest(asked) ? asked : undefined;
862
880
  return serveAccess(request, access, cookie, undefined, rest);
863
881
  }
882
+ /**
883
+ * A served display's door (P125): its own ticket's, taken once, for this instance on this
884
+ * origin, and the checks the content's address runs for the same grant (the host's check, the
885
+ * document, its entry), so the door says what the content's address would: `open`, or `blocked`
886
+ * and why. It sets no cookie and serves nothing of the content; the content's address takes its
887
+ * own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
888
+ * nested page's shell's label serves none (`serveShellLabel`).
889
+ */
890
+ async function serveDoor(request, url, label, key) {
891
+ const method = request.method.toUpperCase();
892
+ const say = (status, reason, code) => doorStatusResponse({
893
+ status,
894
+ reason,
895
+ ...(code === undefined ? {} : { code }),
896
+ hostOrigins: options.hostOrigins,
897
+ frameAncestors,
898
+ method,
899
+ });
900
+ if (method !== "GET" && method !== "HEAD") {
901
+ return say(405, "error");
902
+ }
903
+ try {
904
+ const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
905
+ if (record === null ||
906
+ record.door !== true ||
907
+ record.entry !== undefined ||
908
+ record.instance.document.kind === "external" ||
909
+ keys.instanceKey(record.instance) !== key ||
910
+ compiledFor(record.instance)?.config.nested === true) {
911
+ return say(401, "session");
912
+ }
913
+ const access = {
914
+ instance: record.instance,
915
+ viewer: record.viewer,
916
+ origin: originOfLabel(label),
917
+ expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
918
+ ...(record.anonymous === true ? { anonymous: true } : {}),
919
+ ...(record.subject === undefined ? {} : { subject: record.subject }),
920
+ };
921
+ const refused = await refusalOf(request, access);
922
+ if (refused !== null) {
923
+ return say(403, "denied", refused.code);
924
+ }
925
+ const served = await documentOf(access.instance);
926
+ // The same document, entry and page checks the content's address runs (`serveAccess`).
927
+ const below = isPageRest(record.page) ? record.page : undefined;
928
+ if (served === null ||
929
+ ("files" in served
930
+ ? !entryIsPage(served.files) || ticketPage(served.files, below) === null
931
+ : below !== undefined)) {
932
+ return say(404, "not-found");
933
+ }
934
+ return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
935
+ }
936
+ catch {
937
+ return say(500, "error");
938
+ }
939
+ }
864
940
  /**
865
941
  * The document an access opens, once the host's check lets it in: at its document's path, or
866
942
  * (`at`) a path under a file set's base (P081).
@@ -877,6 +953,18 @@ export function createServer(options) {
877
953
  if (served === null) {
878
954
  return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
879
955
  }
956
+ // A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
957
+ // stored before that was checked shows Porthole's word, never an inert file that says nothing.
958
+ if ("files" in served && at === undefined && !entryIsPage(served.files)) {
959
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
960
+ }
961
+ // A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
962
+ // the page the frame opens at (its entry, or the page it was issued for) must be one of its
963
+ // pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
964
+ if (at === undefined &&
965
+ ("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)) {
966
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
967
+ }
880
968
  // A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
881
969
  // one's) answers Porthole's shell, which frames the page at its sealed files' address; only
882
970
  // that address, below the sealed prefix, answers the page and its files, without a cookie.
@@ -955,7 +1043,7 @@ export function createServer(options) {
955
1043
  compiled: served.compiled,
956
1044
  hostOrigins: options.hostOrigins,
957
1045
  frameAncestors,
958
- ticket: { expires: sealed.expires },
1046
+ ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
959
1047
  ...versionOf(access.instance),
960
1048
  });
961
1049
  }
@@ -1167,6 +1255,13 @@ export function createServer(options) {
1167
1255
  */
1168
1256
  async function beginEntry(request, url, label, to) {
1169
1257
  const method = request.method.toUpperCase();
1258
+ // A clean address is for a tab (P125): in a frame it never goes to the app (no authorize, no
1259
+ // sign-in, no refusal of the app's) and says nothing to the page that frames it, whatever it
1260
+ // names. A host frames what a clean address names by resolving it through `issue`.
1261
+ const framedAs = request.headers.get("sec-fetch-dest");
1262
+ if (framedAs === "iframe" || framedAs === "frame") {
1263
+ return tabOnlyPage(frameAncestors, method);
1264
+ }
1170
1265
  // An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
1171
1266
  const scopeOf = content.name?.scopeOf;
1172
1267
  const named = options.entry?.named;
@@ -1402,7 +1497,9 @@ export function createServer(options) {
1402
1497
  return page(404, "Nothing here", "This address names no content.", method);
1403
1498
  }
1404
1499
  /** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
1405
- async function mint(instance, grant, entry) {
1500
+ async function mint(instance, grant, entry,
1501
+ /** A page below a file set's base its frame opens at (P125: a clean address's file). */
1502
+ below) {
1406
1503
  const clean = cleanInstance(instance);
1407
1504
  check(clean);
1408
1505
  const anonymous = grant.anonymous === true;
@@ -1442,7 +1539,7 @@ export function createServer(options) {
1442
1539
  throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
1443
1540
  }
1444
1541
  const ticket = newTicket();
1445
- await tickets.put(ticketId(ticket), {
1542
+ const record = {
1446
1543
  instance: clean,
1447
1544
  viewer,
1448
1545
  expiresAt: Date.now() + ttl * 1_000,
@@ -1450,8 +1547,24 @@ export function createServer(options) {
1450
1547
  ...(anonymous ? { anonymous: true } : {}),
1451
1548
  ...(grant.subject === undefined ? {} : { subject: grant.subject }),
1452
1549
  ...(entry === undefined ? {} : { entry }),
1453
- });
1454
- return { clean, key, ticket };
1550
+ ...(below === undefined ? {} : { page: below }),
1551
+ };
1552
+ await tickets.put(ticketId(ticket), record);
1553
+ // A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
1554
+ let door = null;
1555
+ if (entry === undefined && hasDoor(clean)) {
1556
+ door = newTicket();
1557
+ await tickets.put(ticketId(door), { ...record, door: true });
1558
+ }
1559
+ return { clean, key, ticket, door };
1560
+ }
1561
+ /**
1562
+ * Whether an instance's frame has a door (P125): a document framed on its scope's origin, where
1563
+ * the scope's other displays run content (a served shell, a page that isn't nested, the sandbox
1564
+ * proxy). A nested page's frame is its shell, on a label of its own; a url-mode app has none.
1565
+ */
1566
+ function hasDoor(instance) {
1567
+ return instance.document.kind !== "external" && compiledFor(instance)?.config.nested !== true;
1455
1568
  }
1456
1569
  const underDomain = (host) => host === domain || host.endsWith(`.${domain}`);
1457
1570
  /**
@@ -1498,8 +1611,13 @@ export function createServer(options) {
1498
1611
  return {
1499
1612
  contentSource,
1500
1613
  originFor: (scope) => originOfLabel(nameOf(scope)),
1501
- async issue(instance, grant) {
1502
- const { clean, key, ticket } = await mint(instance, grant);
1614
+ async issue(instance, grant, at = {}) {
1615
+ // A page below a file set's base (P125: what a clean address names, resolved for a frame).
1616
+ const below = at.page;
1617
+ if (below !== undefined && (!isPageRest(below) || instance.document?.kind !== "artifact")) {
1618
+ throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
1619
+ }
1620
+ const { clean, key, ticket, door } = await mint(instance, grant, undefined, below);
1503
1621
  // A nested page's frame is its shell, on the shell's own label (P114).
1504
1622
  const origin = originOfLabel(labelFor(clean));
1505
1623
  const path = clean.document.kind === "external"
@@ -1507,7 +1625,14 @@ export function createServer(options) {
1507
1625
  : `${PREFIX}d/${key}?ticket=${ticket}`;
1508
1626
  // The viewer's level, as the host's access decided it now (P087): for the display's bridge.
1509
1627
  const viewer = viewerOfGrant(grant);
1510
- return { url: `${origin}${path}`, origin, reports: true, ...(viewer ? { viewer } : {}) };
1628
+ return {
1629
+ url: `${origin}${path}`,
1630
+ origin,
1631
+ reports: true,
1632
+ ...(viewer ? { viewer } : {}),
1633
+ // Its door (P125): the host frames it first, and takes its word alone.
1634
+ ...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
1635
+ };
1511
1636
  },
1512
1637
  forget(filter = {}) {
1513
1638
  for (const [key, each] of answers) {
@@ -1643,6 +1768,10 @@ export function createServer(options) {
1643
1768
  if (asset?.[1] !== undefined) {
1644
1769
  return await serveAssetAt(request, label, asset[1]);
1645
1770
  }
1771
+ const door = DOOR_ROUTE.exec(url.pathname);
1772
+ if (door?.[1] !== undefined) {
1773
+ return await serveDoor(request, url, label, door[1]);
1774
+ }
1646
1775
  const document = DOCUMENT_PATH.exec(url.pathname);
1647
1776
  if (document?.[1] !== undefined) {
1648
1777
  return await serveDocument(request, url, label, document[1]);
@@ -103,6 +103,13 @@ export interface TicketRecord {
103
103
  * its files' base the shell opens (the entry page when absent).
104
104
  */
105
105
  readonly page?: string;
106
+ /**
107
+ * A door's ticket (P125): `issue` mints one beside the content's, for the same grant and as
108
+ * long, for a display whose frame is on its scope's origin (a served shell, a page that isn't
109
+ * nested, the sandbox proxy). Taken only at the door (`/__porthole/door/<key>`), never at the
110
+ * content's address; the door takes no other.
111
+ */
112
+ readonly door?: true;
106
113
  }
107
114
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
108
115
  export interface TicketStore {
@@ -309,7 +316,14 @@ export interface PortholeServer {
309
316
  * Mints a one-time ticket for `instance` and returns the URL its frame loads. Call it from the
310
317
  * host's own authenticated API, once the host has decided the viewer may see the instance.
311
318
  */
312
- issue(instance: InstanceRef, grant: Grant): Promise<FrameLocation>;
319
+ issue(instance: InstanceRef, grant: Grant,
320
+ /**
321
+ * Where in the instance its frame opens (P125): a page below a file set's base (what a clean
322
+ * address names, resolved by `issue` given `{ address }`). Default: its entry.
323
+ */
324
+ at?: {
325
+ readonly page?: string;
326
+ }): Promise<FrameLocation>;
313
327
  /**
314
328
  * The access a request's cookie carries for a url-mode app on the request's origin, or null
315
329
  * (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
@@ -6,12 +6,4 @@ import type { Transport } from "./types.ts";
6
6
  * Messages go to the frame's window addressed to that origin; an opaque frame can only be
7
7
  * addressed as `"*"`, so nothing secret is ever sent.
8
8
  */
9
- export declare function postMessageTransport(frameWindow: () => Window | null, expectedOrigin: string, host?: Window,
10
- /**
11
- * Another origin the frame's window may say some things from: the host's own, whose pages a
12
- * served frame passes through on a redirect entry (P068), for their frame status only.
13
- */
14
- also?: {
15
- readonly origin: string;
16
- readonly accept: (data: unknown) => boolean;
17
- }): Transport;
9
+ export declare function postMessageTransport(frameWindow: () => Window | null, expectedOrigin: string, host?: Window): Transport;
@@ -5,12 +5,7 @@
5
5
  * Messages go to the frame's window addressed to that origin; an opaque frame can only be
6
6
  * addressed as `"*"`, so nothing secret is ever sent.
7
7
  */
8
- export function postMessageTransport(frameWindow, expectedOrigin, host = window,
9
- /**
10
- * Another origin the frame's window may say some things from: the host's own, whose pages a
11
- * served frame passes through on a redirect entry (P068), for their frame status only.
12
- */
13
- also) {
8
+ export function postMessageTransport(frameWindow, expectedOrigin, host = window) {
14
9
  const listeners = new Set();
15
10
  let closed = false;
16
11
  const onMessage = (event) => {
@@ -18,8 +13,7 @@ also) {
18
13
  if (closed || source === null || event.source !== source) {
19
14
  return;
20
15
  }
21
- if (event.origin !== expectedOrigin &&
22
- (also === undefined || event.origin !== also.origin || !also.accept(event.data))) {
16
+ if (event.origin !== expectedOrigin) {
23
17
  return;
24
18
  }
25
19
  for (const listener of listeners) {
package/docs/ADOPTING.md CHANGED
@@ -816,6 +816,64 @@ display.on("outcome", (outcome) => {
816
816
  openButton.onclick = () => porthole.openInTab(instance); // the clean address
817
817
  ```
818
818
 
819
+ A `blocked` outcome is the word of Porthole's own pages, never of the content (P124, P125): an
820
+ opaque frame's frame status is never taken, nor one a frame says after its first word; the host
821
+ hears those as a `hostError` of kind `"frame-status"` (log it, show nothing for it). Draw the
822
+ fallback from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL
823
+ S6).
824
+
825
+ **The door (P125).** A served display that isn't nested (a served shell, a page, a view through the
826
+ sandbox proxy) is framed on its scope's origin, where the scope's other displays run content: its
827
+ own frame can't be trusted for how loading went (a same-scope sibling could speak for it). So
828
+ `createHost` first frames a **door** — a page of Porthole's on the display's origin, in a hidden
829
+ opaque frame it can't reach — and takes the door's word (`FrameLocation.door`, which `issue` returns
830
+ for those kinds). The content frame's own frame status is then never taken, and its silence is a
831
+ `timeout`, never a fallback. You don't wire anything: `createHost` and `/server` do it. Two
832
+ requirements:
833
+
834
+ - **Deploy the server (or your content Worker) before the host.** The door is minted and served by
835
+ the server; a host given a served non-nested location with no door (from a server that doesn't
836
+ yet mint one) builds no frame for it: `blocked: locate`, and a `hostError` of kind `"door"`
837
+ naming the fix. Upgrade the server/Worker first, then the host. This is a hard requirement, not a
838
+ preference.
839
+ - **A custom locator must pass `door` through, and issue anew for every run.** If you rebuild
840
+ `FrameLocation` yourself (a locator of your own rather than `httpLocator`), carry `door` from your
841
+ issue endpoint unchanged; `httpLocator` and the host kit's client already do. Dropping it refuses
842
+ every served non-nested display, as above. And `locate` is called again on every run (a reload,
843
+ a restart after the content navigated its frame away): answer each call with a fresh issue (a new
844
+ ticket, a new door ticket). A location reused from an earlier run carries tickets already taken,
845
+ so its door says `blocked: session` ("this link has been used"), and `createHost` tells you
846
+ with a `hostError` of kind `"locate"`. (A sibling of the scope could force that by reloading the
847
+ display.)
848
+ - **A platform of your own makes the web's doors.** A `PlatformHost` that wraps
849
+ `webPlatform.createSurface` must also give `createDoor` (delegate to `webPlatform.createDoor`):
850
+ a platform without doors frames no served display that isn't nested (`blocked: locate`, a `door`
851
+ host error).
852
+ - **The door sits in the display's container while it decides**, a hidden 0×0 frame
853
+ (`data-porthole-door`), removed once it says its word. Code that grabs
854
+ `container.querySelector("iframe")` just after mounting may get the door: select
855
+ `iframe:not([data-porthole-door])`.
856
+ - **A clean address is for a tab.** Never give `createHost` a clean address (`urlOf`, `link`) as a
857
+ frame's location: it has no door, so it is refused before any frame, as above, and the content
858
+ origin answers it in a frame with a page that has no script and goes nowhere. To frame what a
859
+ clean address names, resolve it through your issue endpoint first: `client.resolve(address)` (or
860
+ `<PortholeView address>`) posts `{ address }`, and the endpoint answers the location for what it
861
+ names (with its door; a file set's page below its version opens at that page), or the refusal its
862
+ tab would get. A refusal is the display's outcome with no frame built: 401 `blocked: sign-in`,
863
+ 403 `blocked: denied` (with your reason code if your answer gives `error.reason`), 404 `blocked:
864
+ not-found`; any other failure is `blocked: locate` with a `locate` host error, and a backend that
865
+ never answers is a `timeout`. That mapping holds for every locate, an instance's too.
866
+
867
+ A **content Worker of your own** (one that answers the content origins itself, instead of
868
+ `/server`) serves the door too: `issue` mints the door ticket and returns `door: { url }`, and the
869
+ Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label — take the door ticket
870
+ (`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
871
+ checks the content route runs for that grant, then answer `doorResponse({ hostOrigins })` (open) or
872
+ `doorStatusResponse({ status, reason, code?, hostOrigins })` (401 `session` / 403 `denied` / 404
873
+ `not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
874
+ page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
875
+ `@botiverse/porthole/server`.
876
+
819
877
  `porthole.config(kind)` is the served config while frames are served, the opaque one while they
820
878
  aren't, and null until the meta is known, so a frame never starts opaque and then restarts
821
879
  served. The client's functions take no `this`: pass them bare