@botiverse/porthole 0.14.5 → 0.14.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +53 -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 +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 +6 -1
  40. package/dist/server/pages.d.ts +32 -0
  41. package/dist/server/pages.js +82 -6
  42. package/dist/server/server.js +140 -11
  43. package/dist/server/types.d.ts +15 -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 +57 -4
  47. package/docs/DECISIONS.md +198 -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 +175 -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 +6 -1
  73. package/src/server/pages.ts +101 -6
  74. package/src/server/server.ts +186 -19
  75. package/src/server/types.ts +16 -1
  76. package/src/transport/post-message.ts +1 -9
@@ -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,74 @@ export function createServer(options: ServerOptions): PortholeServer {
1090
1125
  return serveAccess(request, access, cookie, undefined, rest);
1091
1126
  }
1092
1127
 
1128
+ /**
1129
+ * A served display's door (P125): its own ticket's, taken once, for this instance on this
1130
+ * origin, and the checks the content's address runs for the same grant (the host's check, the
1131
+ * document, its entry), so the door says what the content's address would: `open`, or `blocked`
1132
+ * and why. It sets no cookie and serves nothing of the content; the content's address takes its
1133
+ * own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
1134
+ * nested page's shell's label serves none (`serveShellLabel`).
1135
+ */
1136
+ async function serveDoor(
1137
+ request: Request,
1138
+ url: URL,
1139
+ label: string,
1140
+ key: string,
1141
+ ): Promise<Response> {
1142
+ const method = request.method.toUpperCase();
1143
+ const say = (status: number, reason: FrameBlock, code?: string): Response =>
1144
+ doorStatusResponse({
1145
+ status,
1146
+ reason,
1147
+ ...(code === undefined ? {} : { code }),
1148
+ hostOrigins: options.hostOrigins,
1149
+ frameAncestors,
1150
+ method,
1151
+ });
1152
+ if (method !== "GET" && method !== "HEAD") {
1153
+ return say(405, "error");
1154
+ }
1155
+ try {
1156
+ const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
1157
+ if (
1158
+ record === null ||
1159
+ record.door !== true ||
1160
+ record.entry !== undefined ||
1161
+ record.instance.document.kind === "external" ||
1162
+ keys.instanceKey(record.instance) !== key ||
1163
+ compiledFor(record.instance)?.config.nested === true
1164
+ ) {
1165
+ return say(401, "session");
1166
+ }
1167
+ const access: Access = {
1168
+ instance: record.instance,
1169
+ viewer: record.viewer,
1170
+ origin: originOfLabel(label),
1171
+ expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
1172
+ ...(record.anonymous === true ? { anonymous: true } : {}),
1173
+ ...(record.subject === undefined ? {} : { subject: record.subject }),
1174
+ };
1175
+ const refused = await refusalOf(request, access);
1176
+ if (refused !== null) {
1177
+ return say(403, "denied", refused.code);
1178
+ }
1179
+ const served = await documentOf(access.instance);
1180
+ // The same document, entry and page checks the content's address runs (`serveAccess`).
1181
+ const below = isPageRest(record.page) ? record.page : undefined;
1182
+ if (
1183
+ served === null ||
1184
+ ("files" in served
1185
+ ? !entryIsPage(served.files) || ticketPage(served.files, below) === null
1186
+ : below !== undefined)
1187
+ ) {
1188
+ return say(404, "not-found");
1189
+ }
1190
+ return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
1191
+ } catch {
1192
+ return say(500, "error");
1193
+ }
1194
+ }
1195
+
1093
1196
  /**
1094
1197
  * The document an access opens, once the host's check lets it in: at its document's path, or
1095
1198
  * (`at`) a path under a file set's base (P081).
@@ -1111,6 +1214,20 @@ export function createServer(options: ServerOptions): PortholeServer {
1111
1214
  if (served === null) {
1112
1215
  return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1113
1216
  }
1217
+ // A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
1218
+ // stored before that was checked shows Porthole's word, never an inert file that says nothing.
1219
+ if ("files" in served && at === undefined && !entryIsPage(served.files)) {
1220
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1221
+ }
1222
+ // A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
1223
+ // the page the frame opens at (its entry, or the page it was issued for) must be one of its
1224
+ // pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
1225
+ if (
1226
+ at === undefined &&
1227
+ ("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)
1228
+ ) {
1229
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1230
+ }
1114
1231
  // A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
1115
1232
  // one's) answers Porthole's shell, which frames the page at its sealed files' address; only
1116
1233
  // that address, below the sealed prefix, answers the page and its files, without a cookie.
@@ -1189,7 +1306,7 @@ export function createServer(options: ServerOptions): PortholeServer {
1189
1306
  compiled: served.compiled,
1190
1307
  hostOrigins: options.hostOrigins,
1191
1308
  frameAncestors,
1192
- ticket: { expires: sealed.expires },
1309
+ ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
1193
1310
  ...versionOf(access.instance),
1194
1311
  });
1195
1312
  }
@@ -1418,6 +1535,13 @@ export function createServer(options: ServerOptions): PortholeServer {
1418
1535
  */
1419
1536
  async function beginEntry(request: Request, url: URL, label: string, to: URL): Promise<Response> {
1420
1537
  const method = request.method.toUpperCase();
1538
+ // A clean address is for a tab (P125): in a frame it never goes to the app (no authorize, no
1539
+ // sign-in, no refusal of the app's) and says nothing to the page that frames it, whatever it
1540
+ // names. A host frames what a clean address names by resolving it through `issue`.
1541
+ const framedAs = request.headers.get("sec-fetch-dest");
1542
+ if (framedAs === "iframe" || framedAs === "frame") {
1543
+ return tabOnlyPage(frameAncestors, method);
1544
+ }
1421
1545
  // An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
1422
1546
  const scopeOf = content.name?.scopeOf;
1423
1547
  const named = options.entry?.named;
@@ -1720,7 +1844,15 @@ export function createServer(options: ServerOptions): PortholeServer {
1720
1844
  instance: InstanceRef,
1721
1845
  grant: Grant,
1722
1846
  entry?: TicketRecord["entry"],
1723
- ): Promise<{ readonly clean: InstanceRef; readonly key: string; readonly ticket: string }> {
1847
+ /** A page below a file set's base its frame opens at (P125: a clean address's file). */
1848
+ below?: string,
1849
+ ): Promise<{
1850
+ readonly clean: InstanceRef;
1851
+ readonly key: string;
1852
+ readonly ticket: string;
1853
+ /** The door's own ticket (P125), for a display framed on its scope's origin. */
1854
+ readonly door: string | null;
1855
+ }> {
1724
1856
  const clean = cleanInstance(instance);
1725
1857
  check(clean);
1726
1858
  const anonymous = grant.anonymous === true;
@@ -1768,7 +1900,7 @@ export function createServer(options: ServerOptions): PortholeServer {
1768
1900
  throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
1769
1901
  }
1770
1902
  const ticket = newTicket();
1771
- await tickets.put(ticketId(ticket), {
1903
+ const record: TicketRecord = {
1772
1904
  instance: clean,
1773
1905
  viewer,
1774
1906
  expiresAt: Date.now() + ttl * 1_000,
@@ -1776,8 +1908,25 @@ export function createServer(options: ServerOptions): PortholeServer {
1776
1908
  ...(anonymous ? { anonymous: true } : {}),
1777
1909
  ...(grant.subject === undefined ? {} : { subject: grant.subject }),
1778
1910
  ...(entry === undefined ? {} : { entry }),
1779
- });
1780
- return { clean, key, ticket };
1911
+ ...(below === undefined ? {} : { page: below }),
1912
+ };
1913
+ await tickets.put(ticketId(ticket), record);
1914
+ // A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
1915
+ let door: string | null = null;
1916
+ if (entry === undefined && hasDoor(clean)) {
1917
+ door = newTicket();
1918
+ await tickets.put(ticketId(door), { ...record, door: true });
1919
+ }
1920
+ return { clean, key, ticket, door };
1921
+ }
1922
+
1923
+ /**
1924
+ * Whether an instance's frame has a door (P125): a document framed on its scope's origin, where
1925
+ * the scope's other displays run content (a served shell, a page that isn't nested, the sandbox
1926
+ * proxy). A nested page's frame is its shell, on a label of its own; a url-mode app has none.
1927
+ */
1928
+ function hasDoor(instance: InstanceRef): boolean {
1929
+ return instance.document.kind !== "external" && compiledFor(instance)?.config.nested !== true;
1781
1930
  }
1782
1931
 
1783
1932
  const underDomain = (host: string): boolean => host === domain || host.endsWith(`.${domain}`);
@@ -1832,8 +1981,15 @@ export function createServer(options: ServerOptions): PortholeServer {
1832
1981
 
1833
1982
  originFor: (scope) => originOfLabel(nameOf(scope)),
1834
1983
 
1835
- async issue(instance, grant): Promise<FrameLocation> {
1836
- const { clean, key, ticket } = await mint(instance, grant);
1984
+ async issue(instance, grant, at = {}): Promise<FrameLocation> {
1985
+ // A page below a file set's base (P125: what a clean address names, resolved for a frame).
1986
+ const below = at.page;
1987
+ if (below !== undefined && (!isPageRest(below) || instance.document?.kind !== "artifact")) {
1988
+ throw new TypeError(
1989
+ "A frame's page is a relative path below an artifact's files (no . or ..)",
1990
+ );
1991
+ }
1992
+ const { clean, key, ticket, door } = await mint(instance, grant, undefined, below);
1837
1993
  // A nested page's frame is its shell, on the shell's own label (P114).
1838
1994
  const origin = originOfLabel(labelFor(clean));
1839
1995
  const path =
@@ -1842,7 +1998,14 @@ export function createServer(options: ServerOptions): PortholeServer {
1842
1998
  : `${PREFIX}d/${key}?ticket=${ticket}`;
1843
1999
  // The viewer's level, as the host's access decided it now (P087): for the display's bridge.
1844
2000
  const viewer = viewerOfGrant(grant);
1845
- return { url: `${origin}${path}`, origin, reports: true, ...(viewer ? { viewer } : {}) };
2001
+ return {
2002
+ url: `${origin}${path}`,
2003
+ origin,
2004
+ reports: true,
2005
+ ...(viewer ? { viewer } : {}),
2006
+ // Its door (P125): the host frames it first, and takes its word alone.
2007
+ ...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
2008
+ };
1846
2009
  },
1847
2010
 
1848
2011
  forget(filter = {}) {
@@ -2004,6 +2167,10 @@ export function createServer(options: ServerOptions): PortholeServer {
2004
2167
  if (asset?.[1] !== undefined) {
2005
2168
  return await serveAssetAt(request, label, asset[1]);
2006
2169
  }
2170
+ const door = DOOR_ROUTE.exec(url.pathname);
2171
+ if (door?.[1] !== undefined) {
2172
+ return await serveDoor(request, url, label, door[1]);
2173
+ }
2007
2174
  const document = DOCUMENT_PATH.exec(url.pathname);
2008
2175
  if (document?.[1] !== undefined) {
2009
2176
  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,15 @@ 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>;
330
345
  /**
331
346
  * The access a request's cookie carries for a url-mode app on the request's origin, or null
332
347
  * (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) {