@botiverse/porthole 0.5.1 → 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 (73) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.js +8 -5
  3. package/dist/bridge/navigation.d.ts +1 -6
  4. package/dist/bridge/navigation.js +11 -0
  5. package/dist/check/check.d.ts +12 -3
  6. package/dist/check/check.js +54 -8
  7. package/dist/check/files.d.ts +26 -0
  8. package/dist/check/files.js +307 -0
  9. package/dist/check/lint.js +27 -10
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/tools.d.ts +23 -0
  12. package/dist/check/tools.js +25 -0
  13. package/dist/compile/policy.d.ts +15 -0
  14. package/dist/compile/policy.js +32 -0
  15. package/dist/config/schema.d.ts +8 -0
  16. package/dist/config/validate.js +8 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/files/paths.d.ts +99 -0
  19. package/dist/files/paths.js +263 -0
  20. package/dist/files/types.d.ts +24 -0
  21. package/dist/files/types.js +83 -0
  22. package/dist/guide/guide.js +11 -1
  23. package/dist/host/create-host.js +21 -0
  24. package/dist/index.d.ts +6 -3
  25. package/dist/index.js +8 -3
  26. package/dist/protocol/adapter.d.ts +4 -0
  27. package/dist/protocol/mcp-apps.d.ts +6 -0
  28. package/dist/protocol/mcp-apps.js +6 -0
  29. package/dist/protocol/shell-adapter.js +5 -1
  30. package/dist/server/files.d.ts +44 -0
  31. package/dist/server/files.js +244 -0
  32. package/dist/server/host.d.ts +38 -1
  33. package/dist/server/host.js +37 -2
  34. package/dist/server/index.d.ts +4 -2
  35. package/dist/server/index.js +4 -1
  36. package/dist/server/keys.d.ts +8 -0
  37. package/dist/server/keys.js +34 -0
  38. package/dist/server/server.js +287 -22
  39. package/dist/server/types.d.ts +49 -5
  40. package/dist/shell/document.d.ts +19 -0
  41. package/dist/shell/document.js +30 -0
  42. package/dist/shell/runtime.d.ts +2 -1
  43. package/dist/shell/runtime.js +85 -4
  44. package/docs/ADOPTING.md +56 -4
  45. package/docs/ARCHITECTURE.md +13 -3
  46. package/docs/DECISIONS.md +304 -4
  47. package/docs/DESIGN.md +31 -3
  48. package/package.json +1 -1
  49. package/src/bridge/bridge.ts +8 -5
  50. package/src/bridge/navigation.ts +12 -0
  51. package/src/check/check.ts +92 -14
  52. package/src/check/files.ts +384 -0
  53. package/src/check/lint.ts +29 -10
  54. package/src/check/tools.ts +50 -0
  55. package/src/compile/policy.ts +38 -0
  56. package/src/config/schema.ts +8 -0
  57. package/src/config/validate.ts +8 -1
  58. package/src/files/paths.ts +323 -0
  59. package/src/files/types.ts +101 -0
  60. package/src/guide/guide.ts +20 -0
  61. package/src/host/create-host.ts +21 -0
  62. package/src/index.ts +32 -0
  63. package/src/protocol/adapter.ts +3 -1
  64. package/src/protocol/mcp-apps.ts +7 -0
  65. package/src/protocol/shell-adapter.ts +5 -0
  66. package/src/server/files.ts +312 -0
  67. package/src/server/host.ts +72 -3
  68. package/src/server/index.ts +19 -0
  69. package/src/server/keys.ts +53 -0
  70. package/src/server/server.ts +353 -24
  71. package/src/server/types.ts +56 -4
  72. package/src/shell/document.ts +53 -0
  73. package/src/shell/runtime.ts +85 -4
@@ -31,6 +31,41 @@ export interface ShellDocumentOptions {
31
31
  * every script the shell runs for the content. The frame can read it.
32
32
  */
33
33
  readonly nonce?: string;
34
+ /**
35
+ * A page that comes with files (P081, P084): the absolute URL its version's files are under
36
+ * (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
37
+ * other pages there, and to nothing else.
38
+ */
39
+ readonly files?: {
40
+ readonly base: string;
41
+ /**
42
+ * The page's own address under `base`, where the request's isn't it (a ticket's answer, P083):
43
+ * the shell puts it in the frame's history first, before anything loads, so the page's
44
+ * relative addresses are its files' and the spent ticket leaves the address.
45
+ */
46
+ readonly address?: string;
47
+ /**
48
+ * When a sealed address stops opening the page's files on its own (epoch ms, P083): the shell
49
+ * renews it before then, at `<base>__porthole/renew`, and moves the page there.
50
+ */
51
+ readonly expires?: number;
52
+ };
53
+ }
54
+
55
+ /** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
56
+ function filesBaseOk(base: string): boolean {
57
+ try {
58
+ const url = new URL(base);
59
+ return (
60
+ (url.protocol === "https:" || url.protocol === "http:") &&
61
+ url.href === base &&
62
+ base.endsWith("/") &&
63
+ url.search === "" &&
64
+ url.hash === ""
65
+ );
66
+ } catch {
67
+ return false;
68
+ }
34
69
  }
35
70
 
36
71
  /** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
@@ -98,6 +133,15 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
98
133
  if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
99
134
  throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
100
135
  }
136
+ if (options.files !== undefined && !filesBaseOk(options.files.base)) {
137
+ throw new TypeError("shellDocument: files.base is an http(s) URL ending in /, with no query");
138
+ }
139
+ if (
140
+ options.files?.address !== undefined &&
141
+ (!options.files.address.startsWith(options.files.base) || /[?#]/u.test(options.files.address))
142
+ ) {
143
+ throw new TypeError("shellDocument: files.address is under files.base, with no query");
144
+ }
101
145
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
102
146
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
103
147
  // any text (a document) and must not be searched.
@@ -108,6 +152,15 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
108
152
  ...plan,
109
153
  origins: options.origins,
110
154
  ...(options.document === undefined ? {} : { document: options.document }),
155
+ ...(options.files === undefined
156
+ ? {}
157
+ : {
158
+ files: {
159
+ base: options.files.base,
160
+ ...(options.files.address === undefined ? {} : { address: options.files.address }),
161
+ ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
162
+ },
163
+ }),
111
164
  }),
112
165
  );
113
166
  const head = [
@@ -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
  *
@@ -35,6 +36,13 @@
35
36
  export const SHELL_RUNTIME = String.raw`(() => {
36
37
  "use strict";
37
38
  const plan = __PLAN__;
39
+ // A page that came with files, answered at its ticket's address (P083): its own address first,
40
+ // before anything loads, so its relative addresses are its files' (and the ticket leaves).
41
+ if (plan.files && typeof plan.files.address === "string" && location.href !== plan.files.address) {
42
+ try {
43
+ history.replaceState(null, "", plan.files.address);
44
+ } catch (_) {}
45
+ }
38
46
  // The embedding page's nonce, where it gave one (a srcdoc frame inherits its policy): every
39
47
  // script the shell runs for the content carries it.
40
48
  const nonce = document.currentScript && document.currentScript.nonce ? document.currentScript.nonce : "";
@@ -88,6 +96,31 @@ export const SHELL_RUNTIME = String.raw`(() => {
88
96
  // frame) are none of this document's. Each one stopped is told to the host (P080), as an error
89
97
  // report: below, once the shell can speak.
90
98
  let navigationBlocked = (_url) => {};
99
+ // A page that comes with files (P084): another page of its own set, under the version's own
100
+ // address, is a page of the same content and opens in the frame (the host is told first, so it
101
+ // takes the next load for that page, not for content that left). Anything else stays stopped:
102
+ // another path of the origin, a file that isn't a page, another origin.
103
+ let navigating = (_url) => {};
104
+ let filesBase = plan.files && typeof plan.files.base === "string" ? plan.files.base : null;
105
+ // Every address the page's files had (P083: a sealed one is renewed): what reports say as "./".
106
+ const filesBases = filesBase === null ? [] : [filesBase];
107
+ // A frame's sealed files' address is its access: nothing the shell reports names it (P083).
108
+ const SEALED = /(?:https?:\/\/[^\s"'<>\/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//g;
109
+ const ownAddresses = (text) => {
110
+ let out = String(text);
111
+ for (const base of filesBases) {
112
+ out = out.split(base).join("./");
113
+ }
114
+ return out.replace(SEALED, "./");
115
+ };
116
+ const ownPage = (url) => {
117
+ if (filesBase === null || typeof url !== "string" || url.indexOf(filesBase) !== 0) {
118
+ return false;
119
+ }
120
+ const path = url.slice(filesBase.length).split("#")[0].split("?")[0];
121
+ const last = path.slice(path.lastIndexOf("/") + 1);
122
+ return last === "" || last.indexOf(".") < 0 || /\.html?$/i.test(last);
123
+ };
91
124
  const navigationApi = window.navigation;
92
125
  const getterOf = (proto, name) => {
93
126
  const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
@@ -105,8 +138,13 @@ export const SHELL_RUNTIME = String.raw`(() => {
105
138
  navigationApi.addEventListener("navigate", (event) => {
106
139
  const destination = applyOf(destinationOf, event, []);
107
140
  if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
141
+ const url = urlOf === null ? "" : String(applyOf(urlOf, destination, []));
142
+ if (ownPage(url)) {
143
+ navigating(url);
144
+ return;
145
+ }
108
146
  applyOf(preventNavigation, event, []);
109
- navigationBlocked(urlOf === null ? "" : String(applyOf(urlOf, destination, [])));
147
+ navigationBlocked(url);
110
148
  }
111
149
  }, true);
112
150
  }
@@ -479,7 +517,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
479
517
  return;
480
518
  }
481
519
  reported += 1;
482
- send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: String(message).slice(0, 2000) } });
520
+ send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
483
521
  };
484
522
  // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
485
523
  // content's word, which the host gates before it acts on it.
@@ -500,8 +538,41 @@ export const SHELL_RUNTIME = String.raw`(() => {
500
538
  return;
501
539
  }
502
540
  reported += 1;
503
- post({ method: "porthole/navigation-blocked", params: { url: url.slice(0, 4096) } });
541
+ post({ method: "porthole/navigation-blocked", params: { url: ownAddresses(url).slice(0, 4096) } });
542
+ };
543
+ // Another page of the set opening in the frame (P084): the host takes the next load for it.
544
+ navigating = (url) => {
545
+ post({ method: "porthole/navigating", params: { url: ownAddresses(url).slice(0, 4096) } });
504
546
  };
547
+ // A sealed files' address opens the page's files on its own for a while (P083): renewed before
548
+ // it ends, the page moved to the new one in place (the same page, the same history entry). Its
549
+ // modules keep the address they loaded from; the server serves their own loads till the session
550
+ // ends.
551
+ if (filesBase !== null && typeof plan.files.expires === "number") {
552
+ const nativeFetch = window.fetch.bind(window);
553
+ const replace = History.prototype.replaceState;
554
+ const renewIn = (expires) => Math.max(30000, expires - Date.now() - 300000);
555
+ const renew = () => {
556
+ nativeFetch(filesBase + "__porthole/renew", { credentials: "omit", cache: "no-store" })
557
+ .then((answer) => (answer.ok ? answer.json() : null))
558
+ .then((renewed) => {
559
+ if (!renewed || typeof renewed.base !== "string" || typeof renewed.expires !== "number" || renewed.base.indexOf(location.origin + "/__porthole/f/") !== 0 || renewed.base.slice(-1) !== "/") {
560
+ return;
561
+ }
562
+ const here = location.href;
563
+ if (here.indexOf(filesBase) === 0) {
564
+ try {
565
+ applyOf(replace, history, [history.state, "", renewed.base + here.slice(filesBase.length)]);
566
+ } catch (_) {}
567
+ }
568
+ filesBase = renewed.base;
569
+ filesBases.push(renewed.base);
570
+ setTimeout(renew, renewIn(renewed.expires));
571
+ })
572
+ .catch(() => setTimeout(renew, 60000));
573
+ };
574
+ setTimeout(renew, renewIn(plan.files.expires));
575
+ }
505
576
 
506
577
  // A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
507
578
  // as the page's parser would run them: each made again, live, in its marker's place, and each
@@ -923,6 +994,16 @@ export const SHELL_RUNTIME = String.raw`(() => {
923
994
  try {
924
995
  url = new URL(href, document.baseURI).href;
925
996
  } catch (_) {}
997
+ // A page of the set opens in the frame, whatever its target (P084); any other file of the
998
+ // set never opens: its address carries the frame's access.
999
+ if (ownPage(url)) {
1000
+ location.assign(url);
1001
+ return;
1002
+ }
1003
+ if (filesBase !== null && url.indexOf(filesBase) === 0) {
1004
+ navigationBlocked(url);
1005
+ return;
1006
+ }
926
1007
  if (/^https?:/i.test(url) && typeof window.openLink === "function") {
927
1008
  window.openLink(url).catch(() => {});
928
1009
  }