@botiverse/porthole 0.5.0 → 0.6.0

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 (90) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.d.ts +12 -4
  3. package/dist/bridge/bridge.js +62 -27
  4. package/dist/bridge/navigation.d.ts +6 -0
  5. package/dist/bridge/navigation.js +41 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +7 -0
  9. package/dist/check/check.d.ts +12 -3
  10. package/dist/check/check.js +54 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/lint.js +27 -10
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/page.js +5 -0
  16. package/dist/check/tools.d.ts +23 -0
  17. package/dist/check/tools.js +25 -0
  18. package/dist/compile/policy.d.ts +15 -0
  19. package/dist/compile/policy.js +32 -0
  20. package/dist/config/capabilities.d.ts +5 -0
  21. package/dist/config/schema.d.ts +8 -0
  22. package/dist/config/validate.js +8 -1
  23. package/dist/conformance/harness-source.js +1 -1
  24. package/dist/files/paths.d.ts +99 -0
  25. package/dist/files/paths.js +263 -0
  26. package/dist/files/types.d.ts +24 -0
  27. package/dist/files/types.js +83 -0
  28. package/dist/guide/guide.js +25 -5
  29. package/dist/host/create-host.js +36 -4
  30. package/dist/host/types.d.ts +15 -2
  31. package/dist/index.d.ts +7 -3
  32. package/dist/index.js +10 -3
  33. package/dist/mcp/adapter.js +22 -7
  34. package/dist/protocol/adapter.d.ts +4 -0
  35. package/dist/protocol/mcp-apps.d.ts +12 -0
  36. package/dist/protocol/mcp-apps.js +12 -0
  37. package/dist/protocol/shell-adapter.js +18 -2
  38. package/dist/react/frame.d.ts +19 -4
  39. package/dist/react/frame.js +37 -9
  40. package/dist/server/files.d.ts +44 -0
  41. package/dist/server/files.js +244 -0
  42. package/dist/server/host.d.ts +38 -1
  43. package/dist/server/host.js +37 -2
  44. package/dist/server/index.d.ts +4 -2
  45. package/dist/server/index.js +4 -1
  46. package/dist/server/keys.d.ts +8 -0
  47. package/dist/server/keys.js +34 -0
  48. package/dist/server/server.js +287 -22
  49. package/dist/server/types.d.ts +49 -5
  50. package/dist/shell/document.d.ts +19 -0
  51. package/dist/shell/document.js +30 -0
  52. package/dist/shell/runtime.d.ts +2 -1
  53. package/dist/shell/runtime.js +117 -10
  54. package/docs/ADOPTING.md +95 -13
  55. package/docs/ARCHITECTURE.md +13 -3
  56. package/docs/DECISIONS.md +396 -4
  57. package/docs/DESIGN.md +43 -10
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +74 -23
  60. package/src/bridge/navigation.ts +46 -0
  61. package/src/bridge/refusal.ts +151 -0
  62. package/src/bridge/types.ts +12 -1
  63. package/src/check/check.ts +92 -14
  64. package/src/check/files.ts +384 -0
  65. package/src/check/lint.ts +29 -10
  66. package/src/check/page.ts +7 -0
  67. package/src/check/tools.ts +50 -0
  68. package/src/compile/policy.ts +38 -0
  69. package/src/config/capabilities.ts +5 -1
  70. package/src/config/schema.ts +8 -0
  71. package/src/config/validate.ts +8 -1
  72. package/src/files/paths.ts +323 -0
  73. package/src/files/types.ts +101 -0
  74. package/src/guide/guide.ts +38 -4
  75. package/src/host/create-host.ts +37 -4
  76. package/src/host/types.ts +13 -2
  77. package/src/index.ts +41 -0
  78. package/src/mcp/adapter.ts +26 -6
  79. package/src/protocol/adapter.ts +3 -1
  80. package/src/protocol/mcp-apps.ts +14 -0
  81. package/src/protocol/shell-adapter.ts +20 -2
  82. package/src/react/frame.tsx +53 -14
  83. package/src/server/files.ts +312 -0
  84. package/src/server/host.ts +72 -3
  85. package/src/server/index.ts +19 -0
  86. package/src/server/keys.ts +53 -0
  87. package/src/server/server.ts +353 -24
  88. package/src/server/types.ts +56 -4
  89. package/src/shell/document.ts +53 -0
  90. package/src/shell/runtime.ts +117 -10
@@ -6,6 +6,8 @@ import { randomBytes } from "./crypto.js";
6
6
  import { isHostLabel, reservedLabels } from "./naming.js";
7
7
  import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
8
8
  import { libraryFile } from "./libraries.js";
9
+ import { ownLoad, serveFile } from "./files.js";
10
+ import { INERT_FILE_CSP } from "../compile/policy.js";
9
11
  import { memoryTicketStore } from "./tickets.js";
10
12
  /**
11
13
  * Paths on a content origin. Porthole's own live under `/__porthole/`; on a url-mode app's origin
@@ -14,6 +16,21 @@ import { memoryTicketStore } from "./tickets.js";
14
16
  const PREFIX = "/__porthole/";
15
17
  /** A served document (shell, artifact page, sandbox proxy), by its instance's key. */
16
18
  const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
19
+ /**
20
+ * A file set's files in a frame (P083): `/__porthole/f/<sealed access>/<path>`. The access is
21
+ * in the path, so a frame whose engine keeps no cookie (WebKit, P025) loads them too.
22
+ */
23
+ const FILES_PATH = /^\/__porthole\/f\/([A-Za-z0-9_-]{40,4096})(\/.*)?$/u;
24
+ const FILES_PREFIX = "/__porthole/f/";
25
+ /** How long a sealed files' address opens a page's files on its own (P083); the shell renews it. */
26
+ const FILES_ADDRESS_MS = 3_600_000;
27
+ /** Below a sealed address: where the page's shell renews it (no file has a `__porthole/` path). */
28
+ const RENEW_PATH = "/__porthole/renew";
29
+ /**
30
+ * A clean address's base (P081): a path ending in `/`, each segment of letters, digits and
31
+ * `. _ : ~ -` (nothing a CSP source or a header would read otherwise), never `.` or `..`.
32
+ */
33
+ const BASE = /^\/(?:(?!\.{1,2}\/)[A-Za-z0-9._:~-]{1,200}\/){0,16}$/u;
17
34
  /** Where a url-mode app's ticket is taken, before the app's own landing path. */
18
35
  const ENTER_PATH = "/__porthole/enter";
19
36
  /** Where a redirect entry's code is redeemed, before its clean address (P068). */
@@ -49,6 +66,9 @@ function normalHost(value, protocol) {
49
66
  : host;
50
67
  }
51
68
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
69
+ const isStoredFiles = (stored) => isRecord(stored) &&
70
+ isRecord(stored.files) &&
71
+ typeof stored.read === "function";
52
72
  /** Which configs a kind of served document may be served under. */
53
73
  const MODES = {
54
74
  shell: ["inline", "artifact"],
@@ -357,7 +377,14 @@ export function createServer(options) {
357
377
  return { html: config.shellDocument({ origins, cspMeta: false }), csp: config.csp };
358
378
  case "artifact": {
359
379
  const stored = await options.artifacts?.get(document.id, document.version);
360
- if (stored === null || stored === undefined || typeof stored.html !== "string") {
380
+ if (stored === null || stored === undefined) {
381
+ return null;
382
+ }
383
+ // A version made of files (P081): served file by file under its base.
384
+ if (isStoredFiles(stored)) {
385
+ return { files: stored, compiled: config };
386
+ }
387
+ if (typeof stored.html !== "string") {
361
388
  return null;
362
389
  }
363
390
  return {
@@ -379,7 +406,7 @@ export function createServer(options) {
379
406
  * page that frames it; on a tab of its own, `Lax`. (Engines that keep no cookie in a cross-site
380
407
  * frame, measured: WebKit, still get the document, which comes with the ticket's answer.)
381
408
  */
382
- function sessionCookie(request, record, path) {
409
+ function sessionCookie(request, record, at = {}) {
383
410
  const sessionSeconds = record.sessionSeconds ?? DEFAULT_SESSION_SECONDS;
384
411
  const session = {
385
412
  i: record.instance,
@@ -387,7 +414,9 @@ export function createServer(options) {
387
414
  x: Date.now() + sessionSeconds * 1_000,
388
415
  ...(record.anonymous === true ? { a: 1 } : {}),
389
416
  ...(record.subject === undefined ? {} : { s: record.subject }),
390
- ...(path === undefined ? {} : { p: path }),
417
+ ...(at.p === undefined ? {} : { p: at.p }),
418
+ ...(at.b === undefined ? {} : { b: at.b }),
419
+ ...(at.k === undefined ? {} : { k: at.k }),
391
420
  };
392
421
  return [
393
422
  `${cookieName(keys.instanceKey(record.instance))}=${keys.sign(session)}`,
@@ -454,16 +483,26 @@ export function createServer(options) {
454
483
  }
455
484
  return best;
456
485
  }
457
- /** The access a request's cookies give to the document entered at `pathname` (P068). */
458
- function accessAtPath(request, label, pathname) {
486
+ /**
487
+ * The access a request's cookies give to the document entered at `pathname` (P068), or to a
488
+ * file set's path under the base it was entered at (P081): with where the path falls under the
489
+ * base, or the base itself to go to (`/v/3` → `/v/3/`).
490
+ */
491
+ function accessAtPath(request, label, url) {
492
+ const { pathname } = url;
459
493
  let best = null;
460
494
  for (const [name, value] of cookiesOf(request)) {
461
495
  if (!ourCookie(name)) {
462
496
  continue;
463
497
  }
464
498
  const session = keys.verify(value);
465
- if (!isRecord(session) ||
466
- session.p !== pathname ||
499
+ if (!isRecord(session)) {
500
+ continue;
501
+ }
502
+ const base = typeof session.b === "string" && BASE.test(session.b) ? session.b : null;
503
+ const under = base !== null && pathname.startsWith(base);
504
+ const atBase = base !== null && `${pathname}/` === base;
505
+ if ((session.p !== pathname && !under && !atBase) ||
467
506
  typeof session.w !== "string" ||
468
507
  typeof session.x !== "number" ||
469
508
  session.x <= Date.now() ||
@@ -480,14 +519,37 @@ export function createServer(options) {
480
519
  catch {
481
520
  continue;
482
521
  }
483
- if (best === null || session.x > best.expiresAt) {
522
+ // The most specific first: the path entered itself, then the longest base, then the
523
+ // latest to end.
524
+ const rank = session.p === pathname ? Number.MAX_SAFE_INTEGER : (base?.length ?? 0);
525
+ if (best === null ||
526
+ rank > best.rank ||
527
+ (rank === best.rank && session.x > best.access.expiresAt)) {
528
+ const origin = originOfLabel(label);
484
529
  best = {
485
- instance,
486
- viewer: session.w,
487
- origin: originOfLabel(label),
488
- expiresAt: session.x,
489
- ...(session.a === 1 ? { anonymous: true } : {}),
490
- ...(typeof session.s === "string" ? { subject: session.s } : {}),
530
+ rank,
531
+ access: {
532
+ instance,
533
+ viewer: session.w,
534
+ origin,
535
+ expiresAt: session.x,
536
+ ...(session.a === 1 ? { anonymous: true } : {}),
537
+ ...(typeof session.s === "string" ? { subject: session.s } : {}),
538
+ },
539
+ ...(base !== null && under
540
+ ? {
541
+ at: {
542
+ base,
543
+ rest: pathname.slice(base.length),
544
+ search: url.search,
545
+ pinned: session.k === 1,
546
+ source: new URL(base, origin).href,
547
+ },
548
+ }
549
+ : {}),
550
+ ...(base !== null && atBase && session.p !== pathname
551
+ ? { redirect: `${origin}${base}${url.search}` }
552
+ : {}),
491
553
  };
492
554
  }
493
555
  }
@@ -520,6 +582,103 @@ export function createServer(options) {
520
582
  "x-robots-tag": "noindex, nofollow",
521
583
  });
522
584
  }
585
+ /**
586
+ * A file set's file in a frame (P083): the sealed access in its path opens it, once it holds
587
+ * for this origin and the host's check lets it in; every path under it is the same version's.
588
+ */
589
+ /** A files' address for an access (P083): sealed, its own end within the session's. */
590
+ async function sealFiles(access) {
591
+ const expires = Math.min(access.expiresAt, Date.now() + FILES_ADDRESS_MS);
592
+ const token = await keys.seal({
593
+ i: access.instance,
594
+ w: access.viewer,
595
+ x: expires,
596
+ e: access.expiresAt,
597
+ ...(access.anonymous === true ? { a: 1 } : {}),
598
+ ...(access.subject === undefined ? {} : { s: access.subject }),
599
+ });
600
+ return { base: `${FILES_PREFIX}${token}/`, expires };
601
+ }
602
+ /**
603
+ * A file set's file in a frame (P083): the sealed access in its path opens it, once it holds
604
+ * for this origin and the host's check lets it in; every path under it is the same version's.
605
+ * The address opens on its own for an hour (its `x`); after that, until the session's end (its
606
+ * `e`), only the running page's own loads (same-origin, not a navigation), from addresses it
607
+ * already holds, while its shell renews the address (`__porthole/renew`).
608
+ */
609
+ async function serveSealed(request, url, label, token, rest) {
610
+ const method = request.method.toUpperCase();
611
+ const origin = originOfLabel(label);
612
+ const base = `${FILES_PREFIX}${token}/`;
613
+ if (rest === undefined) {
614
+ return new Response(null, {
615
+ status: 307,
616
+ headers: { location: `${origin}${base}${url.search}`, "cache-control": "no-store" },
617
+ });
618
+ }
619
+ const session = await keys.unseal(token);
620
+ const now = Date.now();
621
+ let instance = null;
622
+ let end = 0;
623
+ if (isRecord(session) &&
624
+ typeof session.w === "string" &&
625
+ typeof session.x === "number" &&
626
+ typeof session.e === "number" &&
627
+ (session.s === undefined || typeof session.s === "string")) {
628
+ end = session.e;
629
+ const open = session.x > now || (session.e > now && ownLoad(request));
630
+ try {
631
+ const clean = cleanInstance(session.i);
632
+ instance =
633
+ open && clean.document.kind === "artifact" && nameOf(clean.scope) === label
634
+ ? clean
635
+ : null;
636
+ }
637
+ catch {
638
+ instance = null;
639
+ }
640
+ }
641
+ if (instance === null || !isRecord(session)) {
642
+ return page(401, "This has ended", "Content here opens for a while. Open it again from the app that showed it.", method, "session");
643
+ }
644
+ const access = {
645
+ instance,
646
+ viewer: session.w,
647
+ origin,
648
+ expiresAt: end,
649
+ ...(session.a === 1 ? { anonymous: true } : {}),
650
+ ...(typeof session.s === "string" ? { subject: session.s } : {}),
651
+ };
652
+ if (rest === RENEW_PATH) {
653
+ // Only the page itself renews its address, while its session lasts and the host lets it.
654
+ if (method !== "GET" || !ownLoad(request)) {
655
+ return page(403, "Not allowed", "Only the page renews its own address.", method);
656
+ }
657
+ const refusal = await denied(request, access);
658
+ if (refusal !== null) {
659
+ return refusal;
660
+ }
661
+ const renewed = await sealFiles(access);
662
+ return Response.json({ base: `${origin}${renewed.base}`, expires: renewed.expires }, {
663
+ headers: {
664
+ "cache-control": "no-store",
665
+ "x-content-type-options": "nosniff",
666
+ "cross-origin-resource-policy": "same-origin",
667
+ "content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${frameAncestors}`,
668
+ "referrer-policy": "no-referrer",
669
+ },
670
+ });
671
+ }
672
+ return serveAccess(request, access, null, {
673
+ base,
674
+ rest: rest.slice(1),
675
+ search: url.search,
676
+ pinned: true,
677
+ // Every frame's files on this origin share the prefix (the scope's, P082): a page knows
678
+ // only its own access.
679
+ source: `${origin}${FILES_PREFIX}`,
680
+ });
681
+ }
523
682
  async function serveDocument(request, url, label, key) {
524
683
  const method = request.method.toUpperCase();
525
684
  if (method !== "GET" && method !== "HEAD") {
@@ -549,8 +708,11 @@ export function createServer(options) {
549
708
  }
550
709
  return serveAccess(request, access, cookie);
551
710
  }
552
- /** The document an access opens, once the host's check lets it in. */
553
- async function serveAccess(request, access, cookie) {
711
+ /**
712
+ * The document an access opens, once the host's check lets it in: at its document's path, or
713
+ * (`at`) a path under a file set's base (P081).
714
+ */
715
+ async function serveAccess(request, access, cookie, at) {
554
716
  const method = request.method.toUpperCase();
555
717
  const refusal = await denied(request, access);
556
718
  if (refusal !== null) {
@@ -560,6 +722,45 @@ export function createServer(options) {
560
722
  if (served === null) {
561
723
  return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
562
724
  }
725
+ if ("files" in served) {
726
+ if (at !== undefined) {
727
+ return serveFile({
728
+ request,
729
+ set: served.files,
730
+ rest: at.rest,
731
+ search: at.search,
732
+ base: at.base,
733
+ origin: access.origin,
734
+ pinned: at.pinned,
735
+ source: at.source,
736
+ compiled: served.compiled,
737
+ hostOrigins: options.hostOrigins,
738
+ frameAncestors,
739
+ });
740
+ }
741
+ // A frame's document (a ticket's): its files carry its access in their path (P083). The
742
+ // entry comes in the ticket's own answer (P025), its shell moving the frame to its address
743
+ // there before anything loads, and renewing it before it ends.
744
+ const sealed = await sealFiles(access);
745
+ return serveFile({
746
+ request,
747
+ set: served.files,
748
+ rest: "",
749
+ search: "",
750
+ base: sealed.base,
751
+ origin: access.origin,
752
+ pinned: true,
753
+ source: `${access.origin}${FILES_PREFIX}`,
754
+ compiled: served.compiled,
755
+ hostOrigins: options.hostOrigins,
756
+ frameAncestors,
757
+ ticket: { expires: sealed.expires },
758
+ });
759
+ }
760
+ // One page at a file set's base (P081): its base is the page, nothing under it is.
761
+ if (at !== undefined && at.rest !== "") {
762
+ return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
763
+ }
563
764
  const headers = documentHeaders(served.csp);
564
765
  if (cookie !== null) {
565
766
  headers.set("set-cookie", cookie);
@@ -580,6 +781,22 @@ export function createServer(options) {
580
781
  (named !== undefined && !(await named(label, url.pathname, request)))) {
581
782
  return page(404, "Nothing here", "This address names no content.", method);
582
783
  }
784
+ // Only a page opening is sent to sign in (a browser's navigation; a client that sends no fetch
785
+ // metadata may be one): a browser's subresource without a session is refused here, with no
786
+ // state of its own (no nonce cookie, nothing cached).
787
+ const mode = request.headers.get("sec-fetch-mode");
788
+ const dest = request.headers.get("sec-fetch-dest") ?? "";
789
+ if (mode !== null && mode !== "navigate" && !["document", "iframe", "frame"].includes(dest)) {
790
+ return new Response(method === "HEAD" ? null : "Open this address in a browser.", {
791
+ status: 401,
792
+ headers: {
793
+ "content-type": "text/plain; charset=utf-8",
794
+ "cache-control": "no-store",
795
+ "x-content-type-options": "nosniff",
796
+ "x-robots-tag": "noindex, nofollow",
797
+ },
798
+ });
799
+ }
583
800
  if (method !== "GET" && method !== "HEAD") {
584
801
  return page(401, "Open this from the app", "Open this address in a browser.", method, "session");
585
802
  }
@@ -634,7 +851,7 @@ export function createServer(options) {
634
851
  if (record?.entry === undefined) {
635
852
  return page(403, "This sign-in link has been used", "It works once, for a short time. Open the address again.", method, "session");
636
853
  }
637
- const { nonce, path } = record.entry;
854
+ const { nonce, path, base, pinned } = record.entry;
638
855
  const named = nonceCookie(nonce);
639
856
  if (!cookiesOf(request).some(([name, value]) => name === named && value === "1")) {
640
857
  return page(401, "Open this in a new tab", "This browser keeps no sign-in for it inside a frame.", method, "cookies");
@@ -660,7 +877,13 @@ export function createServer(options) {
660
877
  "referrer-policy": "no-referrer",
661
878
  "x-robots-tag": "noindex, nofollow",
662
879
  });
663
- headers.append("set-cookie", sessionCookie(request, record, external ? undefined : target.pathname));
880
+ // A file set's address (P081): the session serves every path under its base, the version's
881
+ // own address. Else the path it was entered at, alone (P068).
882
+ headers.append("set-cookie", sessionCookie(request, record, external
883
+ ? {}
884
+ : base !== undefined
885
+ ? { b: base, ...(pinned === true ? { k: 1 } : {}) }
886
+ : { p: target.pathname }));
664
887
  headers.append("set-cookie", [
665
888
  `${named}=${enteredMark(target.pathname)}`,
666
889
  "Path=/",
@@ -792,6 +1015,9 @@ export function createServer(options) {
792
1015
  ...(anonymous ? { a: 1 } : {}),
793
1016
  ...(grant.subject === undefined ? {} : { s: grant.subject }),
794
1017
  ...(entry === undefined ? {} : { p: entry.path }),
1018
+ ...(entry?.base === undefined
1019
+ ? {}
1020
+ : { b: entry.base, ...(entry.pinned === true ? { k: 1 } : {}) }),
795
1021
  });
796
1022
  if (cookieName(key).length + probe.length + 120 > MAX_COOKIE_BYTES) {
797
1023
  throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
@@ -897,7 +1123,7 @@ export function createServer(options) {
897
1123
  expired: state.x <= Date.now(),
898
1124
  };
899
1125
  },
900
- async enterBy(state, instance, grant) {
1126
+ async enterBy(state, instance, grant, address) {
901
1127
  if (state.expired) {
902
1128
  throw new TypeError("This entry's state has expired: start again from the clean address");
903
1129
  }
@@ -905,9 +1131,38 @@ export function createServer(options) {
905
1131
  if (nameOf(clean.scope) !== state.label) {
906
1132
  throw new TypeError("The instance isn't served on the address the entry began at");
907
1133
  }
1134
+ let path = state.path;
1135
+ if (address !== undefined) {
1136
+ // A file set's own address (P081): a path ending in /, not Porthole's own. An address
1137
+ // that isn't under it (the latest's) goes to the same file under it, which must stay
1138
+ // under it: no dot segment, no backslash, nothing the URL parser would resolve away.
1139
+ const { base, file = "" } = address;
1140
+ const segments = typeof file === "string" ? file.split("/") : [];
1141
+ if (typeof base !== "string" ||
1142
+ !BASE.test(base) ||
1143
+ base.startsWith(PREFIX) ||
1144
+ typeof file !== "string" ||
1145
+ file.length > MAX_PATH ||
1146
+ file.startsWith("/") ||
1147
+ // oxlint-disable-next-line no-control-regex -- control characters are what it refuses
1148
+ /[?#\\\u0000-\u001f\u007f]/u.test(file) ||
1149
+ segments.some((each) => /^(?:\.|%2e){1,2}$/iu.test(each))) {
1150
+ throw new TypeError("An entry's base is a path ending in / (not Porthole's own), its file a relative path below it");
1151
+ }
1152
+ const asked = new URL(state.path, "https://x.invalid");
1153
+ if (!asked.pathname.startsWith(base)) {
1154
+ path = `${base}${file}${asked.search}`;
1155
+ }
1156
+ if (!new URL(path, "https://x.invalid").pathname.startsWith(base)) {
1157
+ throw new TypeError("An entry's file must stay below its base");
1158
+ }
1159
+ }
908
1160
  const { ticket } = await mint(clean, { ...grant, ttlSeconds: ENTRY_CODE_SECONDS }, {
909
- path: state.path,
1161
+ path,
910
1162
  nonce: state.nonce,
1163
+ ...(address === undefined
1164
+ ? {}
1165
+ : { base: address.base, ...(address.pinned === true ? { pinned: true } : {}) }),
911
1166
  });
912
1167
  return `${originOfLabel(state.label)}${ENTRY_PATH}?code=${ticket}`;
913
1168
  },
@@ -953,14 +1208,24 @@ export function createServer(options) {
953
1208
  if (document?.[1] !== undefined) {
954
1209
  return await serveDocument(request, url, label, document[1]);
955
1210
  }
1211
+ const sealed = FILES_PATH.exec(url.pathname);
1212
+ if (sealed?.[1] !== undefined) {
1213
+ return await serveSealed(request, url, label, sealed[1], sealed[2]);
1214
+ }
956
1215
  if (url.pathname.startsWith(PREFIX)) {
957
1216
  return page(404, "Nothing here", "This address names no content.", method);
958
1217
  }
959
1218
  // A clean address (P068): the document entered here, else the app, else entry.
960
1219
  if (authorizeUrl !== null) {
961
- const entered = accessAtPath(request, label, url.pathname);
1220
+ const entered = accessAtPath(request, label, url);
1221
+ if (entered?.redirect !== undefined) {
1222
+ return new Response(null, {
1223
+ status: 307,
1224
+ headers: { location: entered.redirect, "cache-control": "no-store" },
1225
+ });
1226
+ }
962
1227
  if (entered !== null) {
963
- return await serveAccess(request, entered, null);
1228
+ return await serveAccess(request, entered.access, null, entered.at);
964
1229
  }
965
1230
  if (options.upstream === undefined || accessOf(request, label, null) === null) {
966
1231
  return await beginEntry(request, url, label, authorizeUrl);
@@ -75,6 +75,10 @@ export interface TicketRecord {
75
75
  readonly entry?: {
76
76
  readonly path: string;
77
77
  readonly nonce: string;
78
+ /** A file set's version's own address (P081): the session serves every path under it. */
79
+ readonly base?: string;
80
+ /** Whether that address names this version and no other: its files are immutable there. */
81
+ readonly pinned?: boolean;
78
82
  };
79
83
  }
80
84
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
@@ -83,11 +87,44 @@ export interface TicketStore {
83
87
  /** Returns the ticket once and never again (atomically), or null if unknown or expired. */
84
88
  take(id: string): Promise<TicketRecord | null>;
85
89
  }
90
+ /** One file of a version (P081), as the host stored it when the version was published. */
91
+ export interface StoredFile {
92
+ /** Its length, bytes. */
93
+ readonly size: number;
94
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
95
+ readonly sha256: string;
96
+ /**
97
+ * The type it was published with, for the host's own use (a file list): never served. A file
98
+ * is served with the type Porthole's table gives its extension (`fileTypeOf`), never sniffed.
99
+ */
100
+ readonly type?: string;
101
+ }
102
+ /** A file's bytes, whole: `/server` cuts the range a request asks for. */
103
+ export type FileBody = Uint8Array | ReadableStream<Uint8Array>;
104
+ /**
105
+ * A version made of files (P081): a manifest, and the bytes of each file by its path. Paths
106
+ * follow `checkFileSet`'s rules (check them when the version is published); a request is looked
107
+ * up in `files` only, and `read` is asked only for a path in it.
108
+ */
109
+ export interface StoredFiles {
110
+ readonly files: Readonly<Record<string, StoredFile>>;
111
+ /** The page the version opens at: one of `files` (default `index.html`). */
112
+ readonly entry?: string;
113
+ /**
114
+ * A single-page app's routes: a navigation whose path finds no file answers the entry, where
115
+ * it would get the nearest `404.html` (default false). Subresources still 404.
116
+ */
117
+ readonly spa?: boolean;
118
+ /** The bytes of a file in `files`; null if they are gone (a 404). */
119
+ read(path: string): Promise<FileBody | null>;
120
+ }
121
+ /** A stored version: one page (`{ html }`, as in 0.5), or a set of files (P081). */
122
+ export type StoredVersion = {
123
+ readonly html: string;
124
+ } | StoredFiles;
86
125
  /** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
87
126
  export interface ArtifactStore {
88
- get(id: string, version: string): Promise<{
89
- readonly html: string;
90
- } | null>;
127
+ get(id: string, version: string): Promise<StoredVersion | null>;
91
128
  }
92
129
  /** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
93
130
  export interface Access {
@@ -219,7 +256,14 @@ export interface PortholeServer {
219
256
  entryState(token: string): EntryState | null;
220
257
  /**
221
258
  * Once the host decided (its authorize route): a one-time code for `instance`, which must be
222
- * served on the state's label, and the URL that redeems it there (`/__porthole/entry`).
259
+ * served on the state's label, and the URL that redeems it there (`/__porthole/entry`). With an
260
+ * `address` (a file set's, P081: `entry.at`'s `base` and `file`), the session it buys serves
261
+ * every path under `base`, and the redeem goes to `base` + `file` when the state's path isn't
262
+ * under it (a "latest" address goes to the version's own).
223
263
  */
224
- enterBy(state: EntryState, instance: InstanceRef, grant: Grant): Promise<string>;
264
+ enterBy(state: EntryState, instance: InstanceRef, grant: Grant, address?: {
265
+ readonly base: string;
266
+ readonly file?: string;
267
+ readonly pinned?: boolean;
268
+ }): Promise<string>;
225
269
  }
@@ -27,6 +27,25 @@ export interface ShellDocumentOptions {
27
27
  * every script the shell runs for the content. The frame can read it.
28
28
  */
29
29
  readonly nonce?: string;
30
+ /**
31
+ * A page that comes with files (P081, P084): the absolute URL its version's files are under
32
+ * (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
33
+ * other pages there, and to nothing else.
34
+ */
35
+ readonly files?: {
36
+ readonly base: string;
37
+ /**
38
+ * The page's own address under `base`, where the request's isn't it (a ticket's answer, P083):
39
+ * the shell puts it in the frame's history first, before anything loads, so the page's
40
+ * relative addresses are its files' and the spent ticket leaves the address.
41
+ */
42
+ readonly address?: string;
43
+ /**
44
+ * When a sealed address stops opening the page's files on its own (epoch ms, P083): the shell
45
+ * renews it before then, at `<base>__porthole/renew`, and moves the page there.
46
+ */
47
+ readonly expires?: number;
48
+ };
30
49
  }
31
50
  /**
32
51
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
@@ -1,6 +1,20 @@
1
1
  import { hostOriginProblem } from "../isolation/served.js";
2
2
  import { ANNOTATE_RUNTIME } from "./annotate.js";
3
3
  import { SHELL_RUNTIME } from "./runtime.js";
4
+ /** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
5
+ function filesBaseOk(base) {
6
+ try {
7
+ const url = new URL(base);
8
+ return ((url.protocol === "https:" || url.protocol === "http:") &&
9
+ url.href === base &&
10
+ base.endsWith("/") &&
11
+ url.search === "" &&
12
+ url.hash === "");
13
+ }
14
+ catch {
15
+ return false;
16
+ }
17
+ }
4
18
  /** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
5
19
  const NONCE = /^[A-Za-z0-9+/_=-]{8,256}$/u;
6
20
  const escapeAttribute = (value) => value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
@@ -58,6 +72,13 @@ export function shellDocument(plan, csp, options) {
58
72
  if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
59
73
  throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
60
74
  }
75
+ if (options.files !== undefined && !filesBaseOk(options.files.base)) {
76
+ throw new TypeError("shellDocument: files.base is an http(s) URL ending in /, with no query");
77
+ }
78
+ if (options.files?.address !== undefined &&
79
+ (!options.files.address.startsWith(options.files.base) || /[?#]/u.test(options.files.address))) {
80
+ throw new TypeError("shellDocument: files.address is under files.base, with no query");
81
+ }
61
82
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
62
83
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
63
84
  // any text (a document) and must not be searched.
@@ -65,6 +86,15 @@ export function shellDocument(plan, csp, options) {
65
86
  ...plan,
66
87
  origins: options.origins,
67
88
  ...(options.document === undefined ? {} : { document: options.document }),
89
+ ...(options.files === undefined
90
+ ? {}
91
+ : {
92
+ files: {
93
+ base: options.files.base,
94
+ ...(options.files.address === undefined ? {} : { address: options.files.address }),
95
+ ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
96
+ },
97
+ }),
68
98
  }));
69
99
  const head = [
70
100
  '<meta charset="utf-8">',
@@ -20,7 +20,8 @@
20
20
  * 6. cancels every navigation the frame starts to another document (P079), before it sends a
21
21
  * request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
22
22
  * the wall for that, must let served frames reach their own content origins. (Opaque frames
23
- * get no navigate events: there `frame-src` is the wall.)
23
+ * get no navigate events: there `frame-src` is the wall.) A page that comes with files may
24
+ * open its set's other pages, under its version's own address, and nothing else (P084).
24
25
  * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
25
26
  * imported, and its scripts run in order, as a fragment's are.
26
27
  *