@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
@@ -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 : "";
@@ -85,7 +93,34 @@ export const SHELL_RUNTIME = String.raw`(() => {
85
93
  // own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
86
94
  // anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
87
95
  // srcdoc frame), which history can change only within that origin. The host's own (a new
88
- // frame) are none of this document's.
96
+ // frame) are none of this document's. Each one stopped is told to the host (P080), as an error
97
+ // report: below, once the shell can speak.
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
+ };
89
124
  const navigationApi = window.navigation;
90
125
  const getterOf = (proto, name) => {
91
126
  const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
@@ -94,13 +129,22 @@ export const SHELL_RUNTIME = String.raw`(() => {
94
129
  const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
95
130
  const destinationOf = getterOf(navigateProto, "destination");
96
131
  const navigationTypeOf = getterOf(navigateProto, "navigationType");
97
- const sameDocumentOf = getterOf(typeof NavigationDestination === "function" ? NavigationDestination.prototype : null, "sameDocument");
132
+ const destinationProto = typeof NavigationDestination === "function" ? NavigationDestination.prototype : null;
133
+ const sameDocumentOf = getterOf(destinationProto, "sameDocument");
134
+ const urlOf = getterOf(destinationProto, "url");
98
135
  const preventNavigation = Event.prototype.preventDefault;
99
136
  const applyOf = Reflect.apply;
100
137
  if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
101
138
  navigationApi.addEventListener("navigate", (event) => {
102
- if (!applyOf(sameDocumentOf, applyOf(destinationOf, event, []), []) && applyOf(navigationTypeOf, event, []) !== "reload") {
139
+ const destination = applyOf(destinationOf, event, []);
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
+ }
103
146
  applyOf(preventNavigation, event, []);
147
+ navigationBlocked(url);
104
148
  }
105
149
  }, true);
106
150
  }
@@ -473,15 +517,62 @@ export const SHELL_RUNTIME = String.raw`(() => {
473
517
  return;
474
518
  }
475
519
  reported += 1;
476
- 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) } });
477
521
  };
478
- const send = (message) => {
479
- if (plan.protocol === "shell" && window.parent !== window) {
480
- // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
481
- // content's word, which the host gates before it acts on it.
522
+ // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
523
+ // content's word, which the host gates before it acts on it.
524
+ const post = (message) => {
525
+ if (window.parent !== window) {
482
526
  window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
483
527
  }
484
528
  };
529
+ const send = (message) => {
530
+ if (plan.protocol === "shell") {
531
+ post(message);
532
+ }
533
+ };
534
+ // A navigation the guard above stopped (P080): one of the run's error reports, told even where
535
+ // the content speaks for itself (an MCP Apps view), in Porthole's own notification.
536
+ navigationBlocked = (url) => {
537
+ if (!declared("reportError") || reported >= plan.maxErrorReports || url === "") {
538
+ return;
539
+ }
540
+ reported += 1;
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) } });
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
+ }
485
576
 
486
577
  // A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
487
578
  // as the page's parser would run them: each made again, live, in its marker's place, and each
@@ -903,6 +994,16 @@ export const SHELL_RUNTIME = String.raw`(() => {
903
994
  try {
904
995
  url = new URL(href, document.baseURI).href;
905
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
+ }
906
1007
  if (/^https?:/i.test(url) && typeof window.openLink === "function") {
907
1008
  window.openLink(url).catch(() => {});
908
1009
  }
@@ -1020,7 +1121,13 @@ export const SHELL_RUNTIME = String.raw`(() => {
1020
1121
  if (waiting !== undefined) {
1021
1122
  pending.delete(data.id);
1022
1123
  if (data.error) {
1023
- waiting.reject(new Error(String(data.error.message || "refused")));
1124
+ // A refusal says why (P080): its code, and a sentence to show the person.
1125
+ const why = data.error.data !== null && typeof data.error.data === "object" ? data.error.data : {};
1126
+ const error = new Error(String(typeof why.message === "string" && why.message !== "" ? why.message : data.error.message || "refused"));
1127
+ if (typeof why.code === "string") {
1128
+ error.code = why.code;
1129
+ }
1130
+ waiting.reject(error);
1024
1131
  } else {
1025
1132
  waiting.resolve(data.result);
1026
1133
  }