@botiverse/porthole 0.5.1 → 0.7.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 (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
@@ -1,5 +1,6 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
3
+ import type { ViewerLevel } from "../runtime/levels.ts";
3
4
  import type { Naming } from "./naming.ts";
4
5
  export interface ContentDomain {
5
6
  /**
@@ -57,6 +58,23 @@ export type Grant = ({
57
58
  * url-mode app's every request, rides on.
58
59
  */
59
60
  readonly sessionSeconds?: number;
61
+ /**
62
+ * The viewer's level on this instance (P087), as the host decided it now: carried in the
63
+ * issue's answer (`FrameLocation.viewer`) to the display's bridge, which checks each runtime
64
+ * method's level against it. Never in the ticket or the cookie, never shown to content but by
65
+ * the `user` capability.
66
+ */
67
+ readonly level?: ViewerLevel;
68
+ /**
69
+ * Who the viewer is to pages that declare `user` (P087): the host's public id for them (whose
70
+ * per-user data, `data/users/<id>`, the page reaches: one path segment, never `me`) and a name.
71
+ * Never `viewer`, unless the host means it to be seen; `pseudonymFor(secret, artifact, person)`
72
+ * gives an id per artifact, so pages can't link a person across artifacts. Only with `level`.
73
+ */
74
+ readonly user?: {
75
+ readonly id: string;
76
+ readonly name?: string;
77
+ };
60
78
  };
61
79
  export interface TicketRecord {
62
80
  readonly instance: InstanceRef;
@@ -75,6 +93,10 @@ export interface TicketRecord {
75
93
  readonly entry?: {
76
94
  readonly path: string;
77
95
  readonly nonce: string;
96
+ /** A file set's version's own address (P081): the session serves every path under it. */
97
+ readonly base?: string;
98
+ /** Whether that address names this version and no other: its files are immutable there. */
99
+ readonly pinned?: boolean;
78
100
  };
79
101
  }
80
102
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
@@ -83,11 +105,88 @@ export interface TicketStore {
83
105
  /** Returns the ticket once and never again (atomically), or null if unknown or expired. */
84
106
  take(id: string): Promise<TicketRecord | null>;
85
107
  }
108
+ /** One file of a version (P081), as the host stored it when the version was published. */
109
+ export interface StoredFile {
110
+ /** Its length, bytes. */
111
+ readonly size: number;
112
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
113
+ readonly sha256: string;
114
+ /**
115
+ * The type it was published with, for the host's own use (a file list): never served. A file
116
+ * is served with the type Porthole's table gives its extension (`fileTypeOf`), never sniffed.
117
+ */
118
+ readonly type?: string;
119
+ }
120
+ /** A file's bytes, whole: `/server` cuts the range a request asks for. */
121
+ export type FileBody = Uint8Array | ReadableStream<Uint8Array>;
122
+ /**
123
+ * A version made of files (P081): a manifest, and the bytes of each file by its path. Paths
124
+ * follow `checkFileSet`'s rules (check them when the version is published); a request is looked
125
+ * up in `files` only, and `read` is asked only for a path in it.
126
+ */
127
+ export interface StoredFiles {
128
+ readonly files: Readonly<Record<string, StoredFile>>;
129
+ /** The page the version opens at: one of `files` (default `index.html`). */
130
+ readonly entry?: string;
131
+ /**
132
+ * A single-page app's routes: a navigation whose path finds no file answers the entry, where
133
+ * it would get the nearest `404.html` (default false). Subresources still 404.
134
+ */
135
+ readonly spa?: boolean;
136
+ /** The bytes of a file in `files`; null if they are gone (a 404). */
137
+ read(path: string): Promise<FileBody | null>;
138
+ }
139
+ /** A stored version: one page (`{ html }`, as in 0.5), or a set of files (P081). */
140
+ export type StoredVersion = {
141
+ readonly html: string;
142
+ } | StoredFiles;
143
+ /**
144
+ * One asset of an artifact's library (P089), as the host stored it: served at `/_blob/<id>` on
145
+ * the origin of `scope`, and nowhere else. Its type is Porthole's for `name`'s extension, never
146
+ * the uploader's; it is never served as a page.
147
+ */
148
+ export interface StoredAsset {
149
+ /** The storage scope whose origin serves it (the artifact's). */
150
+ readonly scope: string;
151
+ /**
152
+ * The artifact whose library holds it (`ServedDocument`'s `id`, after the review): served only
153
+ * to an access for that artifact, never another one sharing the scope.
154
+ */
155
+ readonly artifact: string;
156
+ /**
157
+ * Whether it may run as code (P089, after the review): a script, stylesheet or WebAssembly an
158
+ * admin uploaded where uploaded code may run (the upload's `trusted`). Any other code-typed
159
+ * asset is served as a download, whatever the config says now.
160
+ */
161
+ readonly trusted?: boolean;
162
+ /** Its file name (its extension types it). */
163
+ readonly name: string;
164
+ readonly size: number;
165
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
166
+ readonly sha256: string;
167
+ read(): Promise<FileBody | null>;
168
+ }
169
+ /**
170
+ * Where an artifact's assets are kept (P089): the host's library, by id. Ids are the host's, 32
171
+ * lowercase hex characters made at random (`ASSET_ID`): an asset's address is known only to those
172
+ * shown it; Porthole serves one only on its own scope's origin.
173
+ */
174
+ export interface AssetStore {
175
+ /**
176
+ * The asset, for `access` (who asks, for which artifact: the host decides, and its check runs
177
+ * after); null if it isn't there for them. `access` is null only in bearer mode.
178
+ */
179
+ get(id: string, access: Access | null): Promise<StoredAsset | null>;
180
+ /**
181
+ * Bearer mode, an explicit opt-in (after the review): serve an asset to anyone holding its id,
182
+ * with no access and no host check (a public artifact's library). Its id is then a capability:
183
+ * whoever saw it keeps it until the asset is removed.
184
+ */
185
+ readonly bearer?: boolean;
186
+ }
86
187
  /** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
87
188
  export interface ArtifactStore {
88
- get(id: string, version: string): Promise<{
89
- readonly html: string;
90
- } | null>;
189
+ get(id: string, version: string): Promise<StoredVersion | null>;
91
190
  }
92
191
  /** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
93
192
  export interface Access {
@@ -151,6 +250,13 @@ export interface ServerOptions {
151
250
  */
152
251
  readonly configs: Readonly<Record<string, PortholeConfig>>;
153
252
  readonly artifacts?: ArtifactStore;
253
+ /**
254
+ * Artifacts' asset libraries (P089): `/_blob/<id>` on each content origin, for a request that
255
+ * carries an access to the asset's own artifact (a frame's sealed files' address as its
256
+ * `Referer`, or a session cookie), after the host's check. Absent: `/_blob/` is a clean address
257
+ * like any other.
258
+ */
259
+ readonly assets?: AssetStore;
154
260
  readonly tickets?: TicketStore;
155
261
  /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
156
262
  readonly upstream?: Upstream;
@@ -219,7 +325,14 @@ export interface PortholeServer {
219
325
  entryState(token: string): EntryState | null;
220
326
  /**
221
327
  * 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`).
328
+ * served on the state's label, and the URL that redeems it there (`/__porthole/entry`). With an
329
+ * `address` (a file set's, P081: `entry.at`'s `base` and `file`), the session it buys serves
330
+ * every path under `base`, and the redeem goes to `base` + `file` when the state's path isn't
331
+ * under it (a "latest" address goes to the version's own).
223
332
  */
224
- enterBy(state: EntryState, instance: InstanceRef, grant: Grant): Promise<string>;
333
+ enterBy(state: EntryState, instance: InstanceRef, grant: Grant, address?: {
334
+ readonly base: string;
335
+ readonly file?: string;
336
+ readonly pinned?: boolean;
337
+ }): Promise<string>;
225
338
  }
@@ -27,9 +27,36 @@ 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
+ /** `same-origin`: the document's loads tell its own origin its address (P091); else none. */
36
+ readonly referrer?: "same-origin";
37
+ readonly files?: {
38
+ readonly base: string;
39
+ /**
40
+ * The page's own address under `base`, where the request's isn't it (a ticket's answer, P083):
41
+ * the shell puts it in the frame's history first, before anything loads, so the page's
42
+ * relative addresses are its files' and the spent ticket leaves the address.
43
+ */
44
+ readonly address?: string;
45
+ /**
46
+ * When a sealed address stops opening the page's files on its own (epoch ms, P083): the shell
47
+ * renews it before then, at `<base>__porthole/renew`, and moves the page there.
48
+ */
49
+ readonly expires?: number;
50
+ };
30
51
  }
31
52
  /**
32
53
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
33
54
  * A given `document` travels in the runtime's plan, as data.
34
55
  */
56
+ /**
57
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
58
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
59
+ * the config has one.
60
+ */
61
+ export declare function composedRuntime(plan: ShellPlan): string;
35
62
  export declare function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string;
@@ -1,6 +1,22 @@
1
1
  import { hostOriginProblem } from "../isolation/served.js";
2
2
  import { ANNOTATE_RUNTIME } from "./annotate.js";
3
+ import { LEGACY_GLOBALS_RUNTIME } from "./legacy.js";
3
4
  import { SHELL_RUNTIME } from "./runtime.js";
5
+ import { USE_RUNTIME } from "./use.js";
6
+ /** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
7
+ function filesBaseOk(base) {
8
+ try {
9
+ const url = new URL(base);
10
+ return ((url.protocol === "https:" || url.protocol === "http:") &&
11
+ url.href === base &&
12
+ base.endsWith("/") &&
13
+ url.search === "" &&
14
+ url.hash === "");
15
+ }
16
+ catch {
17
+ return false;
18
+ }
19
+ }
4
20
  /** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
5
21
  const NONCE = /^[A-Za-z0-9+/_=-]{8,256}$/u;
6
22
  const escapeAttribute = (value) => value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
@@ -48,6 +64,16 @@ body {
48
64
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
49
65
  * A given `document` travels in the runtime's plan, as data.
50
66
  */
67
+ /**
68
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
69
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
70
+ * the config has one.
71
+ */
72
+ export function composedRuntime(plan) {
73
+ return SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME)
74
+ .replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
75
+ .replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
76
+ }
51
77
  export function shellDocument(plan, csp, options) {
52
78
  for (const origin of options.origins) {
53
79
  const problem = hostOriginProblem(origin);
@@ -58,20 +84,38 @@ export function shellDocument(plan, csp, options) {
58
84
  if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
59
85
  throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
60
86
  }
87
+ if (options.files !== undefined && !filesBaseOk(options.files.base)) {
88
+ throw new TypeError("shellDocument: files.base is an http(s) URL ending in /, with no query");
89
+ }
90
+ if (options.files?.address !== undefined &&
91
+ (!options.files.address.startsWith(options.files.base) || /[?#]/u.test(options.files.address))) {
92
+ throw new TypeError("shellDocument: files.address is under files.base, with no query");
93
+ }
61
94
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
62
95
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
63
96
  // any text (a document) and must not be searched.
64
- const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME).replace("__PLAN__", () => scriptJson({
97
+ const runtime = composedRuntime(plan).replace("__PLAN__", () => scriptJson({
65
98
  ...plan,
66
99
  origins: options.origins,
67
100
  ...(options.document === undefined ? {} : { document: options.document }),
101
+ ...(options.files === undefined
102
+ ? {}
103
+ : {
104
+ files: {
105
+ base: options.files.base,
106
+ ...(options.files.address === undefined ? {} : { address: options.files.address }),
107
+ ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
108
+ },
109
+ }),
68
110
  }));
69
111
  const head = [
70
112
  '<meta charset="utf-8">',
71
113
  options.cspMeta === false
72
114
  ? null
73
115
  : `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
74
- '<meta name="referrer" content="no-referrer">',
116
+ // A framed page of files whose config serves assets says its sealed address to its own
117
+ // origin only, which its asset loads carry (P091); every other document says nothing.
118
+ `<meta name="referrer" content="${options.referrer === "same-origin" ? "same-origin" : "no-referrer"}">`,
75
119
  // Off for good: an engine may prefetch names it sees in links, outside the CSP.
76
120
  '<meta http-equiv="x-dns-prefetch-control" content="off">',
77
121
  ].filter((line) => line !== null);
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
3
+ * (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
4
+ * runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
5
+ * capability runtime reaches the same host functions through `porthole.use` instead; the bridge
6
+ * gates both paths alike, and holds a page that declared capabilities to its declaration on
7
+ * either (P086).
8
+ *
9
+ * Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
10
+ * pages' calls to `porthole.use`); until then the manual teaches these only where the config has
11
+ * no runtime.
12
+ */
13
+ export declare const LEGACY_GLOBALS_RUNTIME: string;
14
+ /** The globals the legacy path defines, by the capability that defines each. */
15
+ export declare const LEGACY_GLOBALS: {
16
+ readonly sendPrompt: "sendPrompt";
17
+ readonly copyText: "copyText";
18
+ readonly openLink: "openLink";
19
+ readonly readData: "readData";
20
+ readonly subscribeData: "subscribeData";
21
+ };
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
3
+ * (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
4
+ * runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
5
+ * capability runtime reaches the same host functions through `porthole.use` instead; the bridge
6
+ * gates both paths alike, and holds a page that declared capabilities to its declaration on
7
+ * either (P086).
8
+ *
9
+ * Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
10
+ * pages' calls to `porthole.use`); until then the manual teaches these only where the config has
11
+ * no runtime.
12
+ */
13
+ export const LEGACY_GLOBALS_RUNTIME = String.raw `
14
+ if (declared("sendPrompt")) {
15
+ lock(window, "sendPrompt", (text) => {
16
+ if (!gestured("sendPrompt")) {
17
+ return refuse("sendPrompt needs a click: call it from a button's handler");
18
+ }
19
+ const words = String(text);
20
+ if (words.trim() === "" || words.length > plan.maxPromptChars) {
21
+ return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
22
+ }
23
+ return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
24
+ (result) => !(result && result.isError),
25
+ );
26
+ });
27
+ }
28
+ if (declared("copyText")) {
29
+ lock(window, "copyText", (text) => {
30
+ if (!gestured("copyText")) {
31
+ return refuse("copyText needs a click: call it from a button's handler");
32
+ }
33
+ const words = String(text);
34
+ if (words === "" || words.length > plan.maxCopyChars) {
35
+ return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
36
+ }
37
+ return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
38
+ });
39
+ }
40
+ if (declared("openLink")) {
41
+ lock(window, "openLink", (url) => {
42
+ if (!gestured("openLink")) {
43
+ return refuse("openLink needs a click: call it from a link's or button's handler");
44
+ }
45
+ return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
46
+ });
47
+ }
48
+
49
+ if (declared("readData")) {
50
+ lock(window, "readData", readValue);
51
+ }
52
+ if (follow !== null) {
53
+ lock(window, "subscribeData", follow);
54
+ }
55
+ `;
56
+ /** The globals the legacy path defines, by the capability that defines each. */
57
+ export const LEGACY_GLOBALS = {
58
+ sendPrompt: "sendPrompt",
59
+ copyText: "copyText",
60
+ openLink: "openLink",
61
+ readData: "readData",
62
+ subscribeData: "subscribeData",
63
+ };
@@ -1,5 +1,6 @@
1
1
  import { type CapabilityName } from "../config/capabilities.ts";
2
2
  import type { PortholeConfig } from "../config/schema.ts";
3
+ import { type RuntimeVersion } from "../runtime/contract.ts";
3
4
  /**
4
5
  * What the shell wires, derived from the config: the JSON the shell's runtime is given. The
5
6
  * agreement test reads it against the CSP and the manual, so it lists everything the shell
@@ -20,8 +21,23 @@ export interface ShellPlan {
20
21
  readonly userActivation: boolean;
21
22
  };
22
23
  };
23
- /** The globals the shell defines on `window` (sugar over the protocol's requests). */
24
+ /**
25
+ * The globals the shell defines on `window` and the manual teaches: `porthole` where the config
26
+ * has the capability runtime (P085), else 0.6's (sugar over the protocol's requests).
27
+ */
24
28
  readonly globals: readonly string[];
29
+ /**
30
+ * 0.6's globals the shell still defines under the runtime, for pages written before it (the
31
+ * legacy path, `shell/legacy.ts`), which the manual no longer teaches. Empty without a runtime.
32
+ */
33
+ readonly legacyGlobals: readonly string[];
34
+ /** The capability runtime's contract version, where the config has one (`porthole.use`). */
35
+ readonly runtime?: RuntimeVersion;
36
+ /**
37
+ * The runtime methods whose own gates want a gesture (`capability.method`: `artifact.publish`,
38
+ * `assets.delete`): the shell refuses them without one, as it does a host function's.
39
+ */
40
+ readonly methodActivation?: readonly string[];
25
41
  /** The theme variables the shell applies; it drops any other name the host sends. */
26
42
  readonly themeVariables: readonly string[];
27
43
  /** The window event fired after a theme change. */
@@ -1,6 +1,7 @@
1
1
  import { MAX_COPY_CHARS, capabilitySpec } from "../config/capabilities.js";
2
2
  import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
3
3
  import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.js";
4
+ import { RUNTIME_GLOBAL, methodGates, offeredCapabilities, runtimeCapability, } from "../runtime/contract.js";
4
5
  export function shellPlan(config) {
5
6
  if (config.mode === "url") {
6
7
  return null;
@@ -13,17 +14,27 @@ export function shellPlan(config) {
13
14
  userActivation: effectiveGates(config, name).includes("user-activation"),
14
15
  };
15
16
  }
16
- const globals = protocol === "shell"
17
+ const legacy = protocol === "shell"
17
18
  ? declared.flatMap((name) => {
18
19
  const spec = capabilitySpec(name);
19
20
  return spec.global === undefined ? [] : [spec.global];
20
21
  })
21
22
  : [];
23
+ const runtime = protocol === "shell" ? config.runtime : undefined;
22
24
  return {
23
25
  protocol,
24
26
  content: config.mode === "artifact" ? "document" : "fragment",
25
27
  capabilities,
26
- globals,
28
+ globals: runtime === undefined ? legacy : [RUNTIME_GLOBAL],
29
+ legacyGlobals: runtime === undefined ? [] : legacy,
30
+ ...(runtime === undefined
31
+ ? {}
32
+ : {
33
+ runtime,
34
+ methodActivation: offeredCapabilities(config).flatMap((family) => Object.keys(runtimeCapability(family).methods)
35
+ .filter((method) => methodGates(config, family, method).includes("user-activation"))
36
+ .map((method) => `${family}.${method}`)),
37
+ }),
27
38
  themeVariables: Object.keys(config.theme.variables),
28
39
  themeEvent: config.theme.event,
29
40
  themeDocuments: config.theme.documents ?? "declared",
@@ -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
  *