@botiverse/porthole 0.6.0 → 0.8.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 (208) hide show
  1. package/README.md +25 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +38 -5
  6. package/dist/bridge/bridge.js +469 -39
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.d.ts +5 -1
  12. package/dist/bridge/refusal.js +17 -0
  13. package/dist/bridge/types.d.ts +73 -5
  14. package/dist/check/check.d.ts +7 -0
  15. package/dist/check/check.js +1 -0
  16. package/dist/check/instrument.d.ts +3 -0
  17. package/dist/check/lint.js +4 -2
  18. package/dist/check/page-source.js +1 -1
  19. package/dist/check/page.js +16 -0
  20. package/dist/check/tools.js +2 -3
  21. package/dist/compile/compile.d.ts +6 -0
  22. package/dist/compile/compile.js +3 -1
  23. package/dist/compile/policy.d.ts +55 -0
  24. package/dist/compile/policy.js +157 -0
  25. package/dist/config/capabilities.d.ts +85 -7
  26. package/dist/config/capabilities.js +32 -2
  27. package/dist/config/schema.d.ts +35 -0
  28. package/dist/config/validate.d.ts +9 -3
  29. package/dist/config/validate.js +92 -8
  30. package/dist/config/warnings.d.ts +20 -0
  31. package/dist/config/warnings.js +25 -0
  32. package/dist/conformance/behavior.js +46 -1
  33. package/dist/conformance/cookies.d.ts +15 -0
  34. package/dist/conformance/cookies.js +80 -0
  35. package/dist/conformance/harness/page.d.ts +1 -0
  36. package/dist/conformance/harness/page.js +9 -2
  37. package/dist/conformance/harness-source.js +1 -1
  38. package/dist/conformance/host-kit.js +5 -1
  39. package/dist/conformance/index.d.ts +11 -0
  40. package/dist/conformance/index.js +2 -0
  41. package/dist/conformance/limits.js +38 -1
  42. package/dist/conformance/runtime.d.ts +58 -0
  43. package/dist/conformance/runtime.js +324 -0
  44. package/dist/conformance/served.d.ts +2 -0
  45. package/dist/conformance/served.js +737 -4
  46. package/dist/files/paths.js +4 -0
  47. package/dist/guide/gates.d.ts +9 -0
  48. package/dist/guide/gates.js +31 -0
  49. package/dist/guide/guide.d.ts +2 -0
  50. package/dist/guide/guide.js +35 -33
  51. package/dist/guide/limits.js +4 -4
  52. package/dist/guide/runtime.d.ts +13 -0
  53. package/dist/guide/runtime.js +210 -0
  54. package/dist/host/create-host.js +73 -37
  55. package/dist/host/locate.js +8 -0
  56. package/dist/host/locator.js +7 -0
  57. package/dist/host/pages-of-set.d.ts +43 -0
  58. package/dist/host/pages-of-set.js +196 -0
  59. package/dist/host/types.d.ts +26 -1
  60. package/dist/index.d.ts +11 -4
  61. package/dist/index.js +11 -2
  62. package/dist/isolation/types.d.ts +8 -0
  63. package/dist/mcp/adapter.js +11 -15
  64. package/dist/node/index.d.ts +36 -4
  65. package/dist/node/index.js +402 -101
  66. package/dist/presets/presets.d.ts +22 -8
  67. package/dist/presets/presets.js +40 -8
  68. package/dist/protocol/live-data.d.ts +6 -2
  69. package/dist/protocol/live-data.js +20 -1
  70. package/dist/protocol/mcp-apps.d.ts +13 -2
  71. package/dist/protocol/mcp-apps.js +10 -2
  72. package/dist/protocol/message-text.d.ts +8 -0
  73. package/dist/protocol/message-text.js +29 -0
  74. package/dist/protocol/runtime-calls.d.ts +28 -0
  75. package/dist/protocol/runtime-calls.js +116 -0
  76. package/dist/protocol/shell-adapter.js +64 -25
  77. package/dist/react/context-notice.d.ts +32 -0
  78. package/dist/react/context-notice.js +28 -0
  79. package/dist/react/dialog.js +91 -16
  80. package/dist/react/frame.d.ts +25 -1
  81. package/dist/react/frame.js +85 -2
  82. package/dist/react/index.d.ts +2 -1
  83. package/dist/react/index.js +2 -1
  84. package/dist/runtime/contract.d.ts +201 -0
  85. package/dist/runtime/contract.js +245 -0
  86. package/dist/runtime/db.d.ts +188 -0
  87. package/dist/runtime/db.js +502 -0
  88. package/dist/runtime/declaration.d.ts +100 -0
  89. package/dist/runtime/declaration.js +363 -0
  90. package/dist/runtime/levels.d.ts +33 -0
  91. package/dist/runtime/levels.js +41 -0
  92. package/dist/runtime/requests.d.ts +125 -0
  93. package/dist/runtime/requests.js +215 -0
  94. package/dist/runtime/segments.d.ts +8 -0
  95. package/dist/runtime/segments.js +14 -0
  96. package/dist/runtime/types.generated.d.ts +1 -0
  97. package/dist/runtime/types.generated.js +19 -0
  98. package/dist/server/files.d.ts +19 -1
  99. package/dist/server/files.js +115 -6
  100. package/dist/server/host.d.ts +24 -2
  101. package/dist/server/host.js +137 -2
  102. package/dist/server/index.d.ts +3 -2
  103. package/dist/server/index.js +2 -1
  104. package/dist/server/peer.d.ts +4 -0
  105. package/dist/server/peer.js +19 -0
  106. package/dist/server/proxy.d.ts +6 -0
  107. package/dist/server/proxy.js +12 -3
  108. package/dist/server/pseudonym.d.ts +9 -0
  109. package/dist/server/pseudonym.js +20 -0
  110. package/dist/server/server.d.ts +0 -5
  111. package/dist/server/server.js +318 -52
  112. package/dist/server/types.d.ts +74 -2
  113. package/dist/shell/document.d.ts +16 -0
  114. package/dist/shell/document.js +19 -2
  115. package/dist/shell/legacy.d.ts +21 -0
  116. package/dist/shell/legacy.js +63 -0
  117. package/dist/shell/plan.d.ts +17 -1
  118. package/dist/shell/plan.js +13 -2
  119. package/dist/shell/runtime.js +390 -56
  120. package/dist/shell/use.d.ts +15 -0
  121. package/dist/shell/use.js +235 -0
  122. package/docs/ADOPTING.md +205 -15
  123. package/docs/ARCHITECTURE.md +34 -5
  124. package/docs/DECISIONS.md +1867 -11
  125. package/docs/DESIGN.md +137 -17
  126. package/docs/THREAT_MODEL.md +616 -0
  127. package/package.json +16 -3
  128. package/src/bridge/bounded-text.ts +240 -0
  129. package/src/bridge/bridge.ts +601 -51
  130. package/src/bridge/json-data.ts +95 -0
  131. package/src/bridge/navigation.ts +10 -0
  132. package/src/bridge/refusal.ts +17 -0
  133. package/src/bridge/types.ts +76 -5
  134. package/src/check/check.ts +8 -0
  135. package/src/check/instrument.ts +3 -0
  136. package/src/check/lint.ts +4 -2
  137. package/src/check/page.ts +16 -0
  138. package/src/check/tools.ts +2 -3
  139. package/src/compile/compile.ts +9 -1
  140. package/src/compile/policy.ts +177 -0
  141. package/src/config/capabilities.ts +71 -5
  142. package/src/config/schema.ts +35 -0
  143. package/src/config/validate.ts +141 -8
  144. package/src/config/warnings.ts +42 -0
  145. package/src/conformance/behavior.ts +54 -1
  146. package/src/conformance/cookies.ts +93 -0
  147. package/src/conformance/harness/page.ts +11 -2
  148. package/src/conformance/host-kit.ts +10 -1
  149. package/src/conformance/index.ts +17 -0
  150. package/src/conformance/limits.ts +39 -1
  151. package/src/conformance/runtime.ts +594 -0
  152. package/src/conformance/served.ts +888 -4
  153. package/src/files/paths.ts +4 -0
  154. package/src/guide/gates.ts +37 -0
  155. package/src/guide/guide.ts +61 -55
  156. package/src/guide/limits.ts +4 -4
  157. package/src/guide/runtime.ts +253 -0
  158. package/src/host/create-host.ts +88 -36
  159. package/src/host/locate.ts +10 -0
  160. package/src/host/locator.ts +11 -0
  161. package/src/host/pages-of-set.ts +226 -0
  162. package/src/host/types.ts +33 -1
  163. package/src/index.ts +94 -0
  164. package/src/isolation/types.ts +8 -0
  165. package/src/mcp/adapter.ts +16 -20
  166. package/src/node/index.ts +507 -116
  167. package/src/presets/presets.ts +67 -17
  168. package/src/protocol/live-data.ts +31 -3
  169. package/src/protocol/mcp-apps.ts +11 -2
  170. package/src/protocol/message-text.ts +36 -0
  171. package/src/protocol/runtime-calls.ts +141 -0
  172. package/src/protocol/shell-adapter.ts +79 -26
  173. package/src/react/context-notice.tsx +95 -0
  174. package/src/react/dialog.tsx +108 -15
  175. package/src/react/frame.tsx +120 -0
  176. package/src/react/index.ts +8 -1
  177. package/src/runtime/contract.ts +339 -0
  178. package/src/runtime/db.ts +650 -0
  179. package/src/runtime/declaration.ts +516 -0
  180. package/src/runtime/levels.ts +69 -0
  181. package/src/runtime/requests.ts +355 -0
  182. package/src/runtime/segments.ts +17 -0
  183. package/src/runtime/types.generated.ts +19 -0
  184. package/src/server/files.ts +138 -7
  185. package/src/server/host.ts +170 -3
  186. package/src/server/index.ts +4 -0
  187. package/src/server/peer.ts +21 -0
  188. package/src/server/proxy.ts +13 -3
  189. package/src/server/pseudonym.ts +21 -0
  190. package/src/server/server.ts +370 -57
  191. package/src/server/types.ts +73 -2
  192. package/src/shell/document.ts +29 -4
  193. package/src/shell/legacy.ts +64 -0
  194. package/src/shell/plan.ts +37 -3
  195. package/src/shell/runtime.ts +390 -56
  196. package/src/shell/use.ts +235 -0
  197. package/types/runtime/v1/artifact.d.ts +50 -0
  198. package/types/runtime/v1/assets.d.ts +43 -0
  199. package/types/runtime/v1/chat.d.ts +13 -0
  200. package/types/runtime/v1/clipboard.d.ts +14 -0
  201. package/types/runtime/v1/comments.d.ts +24 -0
  202. package/types/runtime/v1/context.d.ts +27 -0
  203. package/types/runtime/v1/data.d.ts +29 -0
  204. package/types/runtime/v1/db.d.ts +110 -0
  205. package/types/runtime/v1/downloads.d.ts +22 -0
  206. package/types/runtime/v1/links.d.ts +13 -0
  207. package/types/runtime/v1/porthole.d.ts +44 -0
  208. package/types/runtime/v1/user.d.ts +19 -0
@@ -0,0 +1,235 @@
1
+ /**
2
+ * The capability runtime in the frame (P085), spliced into the shell's runtime (`__RUNTIME__`)
3
+ * where the config has one (`config.runtime`). Content gets one global, `porthole`, whose only
4
+ * member is `use(name)`: a promise of a frozen namespace of the capability's methods, or null when
5
+ * the capability isn't there for this page (not offered, not declared, no host): the reasons are
6
+ * indistinguishable. Permission problems come at call time, as a rejected promise whose error has
7
+ * a stable `code` (P080, P087) and a sentence to show.
8
+ *
9
+ * The host's offer comes in the handshake (MCP Apps' experimental host capabilities,
10
+ * `porthole/runtime`): which capabilities, which methods. Calls go as `porthole/call` (own-prefixed,
11
+ * P002), `data.read` and `data.subscribe` as MCP's own resource requests (the cache and the
12
+ * subscriptions of P079); a watch's updates come as `porthole/event`. The host's bridge decides
13
+ * every call: nothing here is a wall, since it shares the content's realm.
14
+ */
15
+ export const USE_RUNTIME = String.raw `
16
+ // The capability runtime (P085): porthole.use(name) -> a frozen namespace, or null.
17
+ // The host's offer: undefined until the handshake says (or gives up: null). A late answer is
18
+ // still taken, for the calls to use after it (after the review).
19
+ let offered = undefined;
20
+ const waiting = new Set();
21
+ runtimeOffer = (given) => {
22
+ const capabilities = given !== null && typeof given === "object" && given.capabilities !== null && typeof given.capabilities === "object" ? given.capabilities : null;
23
+ if (capabilities !== null || offered === undefined) {
24
+ offered = capabilities;
25
+ }
26
+ for (const wake of Array.from(waiting)) {
27
+ wake();
28
+ }
29
+ waiting.clear();
30
+ };
31
+ // A use waits for the handshake a few seconds at most, then is null (no host is answering).
32
+ const ready = () =>
33
+ offered !== undefined
34
+ ? Promise.resolve()
35
+ : new Promise((resolve) => {
36
+ waiting.add(resolve);
37
+ setTimeout(resolve, 3000);
38
+ });
39
+ // Framed by a page that isn't one of this frame's hosts: nothing will answer (where the engine
40
+ // says who framed it).
41
+ const framedByHost = () => {
42
+ const ancestors = location.ancestorOrigins;
43
+ // "null": the engine masks it (a no-referrer frame): unknown, not a stranger.
44
+ return !ancestors || ancestors.length === 0 || ancestors[0] === "null" || plan.origins.indexOf(ancestors[0]) !== -1;
45
+ };
46
+ const NativeBlob = typeof Blob === "function" ? Blob : null;
47
+ const NativeArrayBuffer = ArrayBuffer;
48
+ const coded = (code, message) => {
49
+ const error = new Error(message);
50
+ error.code = code;
51
+ return error;
52
+ };
53
+ // A call through the host; its value, or a rejection with the refusal's code.
54
+ const call = (capability, method, args) =>
55
+ request("porthole/call", { capability, method, args }).then((result) =>
56
+ result !== null && typeof result === "object" ? result.value : undefined,
57
+ );
58
+ // What needs a click, refused here before it goes (the host checks again: P021).
59
+ const clicked = (serves, what) => (gestured(serves) ? null : Promise.reject(coded("not_allowed", what + " needs a click: call it from a button's handler")));
60
+ // Bytes as base64, for what crosses the frame as JSON.
61
+ const bytesOf = (data) => {
62
+ if (NativeBlob !== null && data instanceof NativeBlob) {
63
+ return data.arrayBuffer().then((buffer) => new Uint8Array(buffer));
64
+ }
65
+ if (data instanceof NativeArrayBuffer) {
66
+ return Promise.resolve(new Uint8Array(data));
67
+ }
68
+ if (ArrayBuffer.isView(data)) {
69
+ return Promise.resolve(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
70
+ }
71
+ return null;
72
+ };
73
+ const base64Of = (bytes) => {
74
+ let text = "";
75
+ for (let at = 0; at < bytes.length; at += 32768) {
76
+ text += String.fromCharCode.apply(null, Array.from(bytes.subarray(at, at + 32768)));
77
+ }
78
+ return btoa(text);
79
+ };
80
+ // A file's content: text as it is, bytes as base64, null as null (a removal).
81
+ const fileOf = (value) => {
82
+ if (value === null || typeof value === "string") {
83
+ return Promise.resolve(value === null ? null : { text: value });
84
+ }
85
+ const bytes = bytesOf(value);
86
+ return bytes === null ? Promise.reject(coded("not_allowed", "A file is text, a Blob, an ArrayBuffer or bytes")) : bytes.then((each) => ({ base64: base64Of(each) }));
87
+ };
88
+ const record = (value) => (value !== null && typeof value === "object" ? value : {});
89
+ // Watches (db.onSnapshot): by the id this frame gives each, its listener.
90
+ const watchers = new Map();
91
+ // A watch's id is this page's own, at random: a page that follows another on the same
92
+ // transport can't be handed its watches (after the review).
93
+ const watchId = () => {
94
+ const bytes = new Uint8Array(8);
95
+ crypto.getRandomValues(bytes);
96
+ return "w" + Array.from(bytes, (each) => each.toString(16).padStart(2, "0")).join("");
97
+ };
98
+ runtimeEvent = (params) => {
99
+ const watcher = typeof params.watch === "string" ? watchers.get(params.watch) : undefined;
100
+ if (watcher === undefined) {
101
+ return;
102
+ }
103
+ try {
104
+ watcher.onData(params.data);
105
+ } catch (error) {
106
+ later(error);
107
+ }
108
+ };
109
+ const watch = (capability, method, args, onData, onError) => {
110
+ if (typeof onData !== "function") {
111
+ throw new TypeError(capability + "." + method + ": onData must be a function");
112
+ }
113
+ const id = watchId();
114
+ watchers.set(id, { onData });
115
+ request("porthole/call", { capability, method, args, watch: id }).catch((error) => {
116
+ watchers.delete(id);
117
+ if (typeof onError === "function") {
118
+ try {
119
+ onError(error);
120
+ } catch (thrown) {
121
+ later(thrown);
122
+ }
123
+ }
124
+ });
125
+ return () => {
126
+ if (watchers.delete(id)) {
127
+ notify("porthole/unwatch", { watch: id });
128
+ }
129
+ };
130
+ };
131
+ const METHODS = {
132
+ user: { get: () => call("user", "get", {}) },
133
+ comments: {
134
+ open: (anchor) => clicked("comments", "comments.open") || call("comments", "open", { anchor: typeof anchor === "string" ? { name: anchor } : record(anchor) }),
135
+ },
136
+ clipboard: { copy: (text) => clicked("copyText", "clipboard.copy") || call("clipboard", "copy", { text: String(text) }) },
137
+ links: { open: (url) => clicked("openLink", "links.open") || call("links", "open", { url: String(url) }) },
138
+ downloads: {
139
+ save: (file) => {
140
+ const given = record(file);
141
+ const waiting = clicked("downloadFile", "downloads.save");
142
+ if (waiting !== null) {
143
+ return waiting;
144
+ }
145
+ const content = given.data !== undefined ? given.data : given.text !== undefined ? String(given.text) : null;
146
+ return fileOf(content).then((body) => call("downloads", "save", { file: Object.assign({ name: given.name, type: given.type }, record(body)) }));
147
+ },
148
+ },
149
+ chat: { send: (text) => clicked("sendPrompt", "chat.send") || call("chat", "send", { text: String(text) }) },
150
+ data: {
151
+ read: (uri) => readValue(uri),
152
+ subscribe: (uri, onData, onError) => (follow === null ? null : follow(uri, onData, onError)),
153
+ call: (name, args) => call("data", "call", { name: String(name), arguments: args === undefined ? {} : args }),
154
+ },
155
+ context: { set: (update) => call("context", "set", record(update)) },
156
+ artifact: {
157
+ get: () => call("artifact", "get", {}),
158
+ publish: (change) => {
159
+ const given = record(change);
160
+ const files = record(given.files);
161
+ const names = Object.keys(files);
162
+ return Promise.all(names.map((name) => fileOf(files[name]))).then((bodies) => {
163
+ const out = {};
164
+ names.forEach((name, index) => {
165
+ out[name] = bodies[index];
166
+ });
167
+ return call("artifact", "publish", { base: given.base, files: out, entry: given.entry, label: given.label, note: given.note });
168
+ });
169
+ },
170
+ },
171
+ assets: {
172
+ list: () => call("assets", "list", {}),
173
+ upload: (file, options) => {
174
+ const name = record(options).name !== undefined ? record(options).name : file && typeof file.name === "string" ? file.name : undefined;
175
+ const bytes = bytesOf(file);
176
+ return bytes === null ? Promise.reject(coded("not_allowed", "assets.upload takes a File, a Blob or bytes")) : bytes.then((each) => call("assets", "upload", { name, base64: base64Of(each) }));
177
+ },
178
+ delete: (id) => call("assets", "delete", { id: String(id) }),
179
+ // The address that loads an asset in this page now (P091): in a frame, under its own sealed
180
+ // files' address, which every engine sends; elsewhere /_blob/<id>. Never stored: it carries
181
+ // this page's access.
182
+ url: (id) => {
183
+ const asset = String(id);
184
+ if (!/^[0-9a-f]{32}$/.test(asset)) {
185
+ throw new TypeError("assets.url(id): an asset's id is 32 lowercase hex characters");
186
+ }
187
+ return filesBase !== null && filesBase.indexOf("/__porthole/f/") !== -1 ? filesBase + "__porthole/blob/" + asset : "/_blob/" + asset;
188
+ },
189
+ },
190
+ db: {
191
+ get: (path) => call("db", "get", { path }),
192
+ set: (path, data, options) => call("db", "set", { path, data, ifVersion: record(options).ifVersion }),
193
+ update: (path, data, options) => call("db", "update", { path, data, ifVersion: record(options).ifVersion }),
194
+ delete: (path, options) => call("db", "delete", { path, ifVersion: record(options).ifVersion }),
195
+ query: (collection, query) => call("db", "query", Object.assign({ collection }, record(query))),
196
+ batch: (writes) => call("db", "batch", { writes }),
197
+ onSnapshot: (path, onData, onError) => watch("db", "watch", { path }, onData, onError),
198
+ },
199
+ };
200
+ // A runtime method's name in the namespace, where it differs from the contract's.
201
+ const RENAMED = { db: { watch: "onSnapshot" } };
202
+ const namespaces = new Map();
203
+ const use = (name) => {
204
+ if (window.parent === window || !framedByHost() || typeof name !== "string" || !Object.prototype.hasOwnProperty.call(METHODS, name)) {
205
+ return Promise.resolve(null);
206
+ }
207
+ return ready().then(() => {
208
+ const methods = offered !== undefined && offered !== null && Array.isArray(offered[name]) ? offered[name] : null;
209
+ if (methods === null) {
210
+ return null;
211
+ }
212
+ if (!namespaces.has(name)) {
213
+ const space = {};
214
+ const renamed = RENAMED[name] || {};
215
+ for (const each of methods) {
216
+ const key = Object.prototype.hasOwnProperty.call(renamed, each) ? renamed[each] : each;
217
+ if (typeof each === "string" && Object.prototype.hasOwnProperty.call(METHODS[name], key)) {
218
+ const call = METHODS[name][key];
219
+ // A method whose own gates want a gesture (after the review): refused here without one.
220
+ const gated = Array.isArray(plan.methodActivation) && plan.methodActivation.indexOf(name + "." + each) !== -1;
221
+ space[key] = gated
222
+ ? function () {
223
+ const activation = navigator.userActivation;
224
+ return activation && !activation.isActive ? Promise.reject(coded("not_allowed", name + "." + key + " needs a click: call it from a button's handler")) : call.apply(null, arguments);
225
+ }
226
+ : call;
227
+ }
228
+ }
229
+ namespaces.set(name, Object.freeze(space));
230
+ }
231
+ return namespaces.get(name);
232
+ }, () => null);
233
+ };
234
+ lock(window, "porthole", Object.freeze({ use }));
235
+ `;
package/docs/ADOPTING.md CHANGED
@@ -5,6 +5,9 @@ app that does everything below: `examples/app.mjs` is the app, runtime-agnostic;
5
5
  `examples/node/server.mjs` (`nodeServer`) and `examples/workers/` (`contentHostFor`) run it, as
6
6
  §4 and §5 recommend; `examples/mcp/server.mjs` gives the
7
7
  agent its tools. DESIGN.md says how it works and DECISIONS.md why (the P-numbers the code cites).
8
+ [THREAT_MODEL.md](THREAT_MODEL.md) says, for each use (chat widgets, live data, private and public
9
+ pages, MCP Apps, previews, several displays on one page), what Porthole guarantees, what you must
10
+ do, and what isn't covered: read your use's section before you show content that matters.
8
11
 
9
12
  ## 1. Choose how content is shown
10
13
 
@@ -50,10 +53,10 @@ data (fetch, WebSocket). Every preset starts closed, and a kind opens more only
50
53
 
51
54
  | Level | Config (`options`) | What it opens | The risk it re-opens | Typical host | The agent's manual says | Why | Tested by |
52
55
  | --- | --- | --- | --- | --- | --- | --- | --- |
53
- | **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
54
- | **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
56
+ | **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082-p089) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
57
+ | **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082-p089), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
55
58
  | **Passive from any https site** (`anyHttps`, on top of either) | `egress: { ...LIBRARY_CDNS, anyHttps: ["img"] }`; closed but for them: `egress: { anyHttps: ["img"] }` | The passive kinds you name (`img`, `media`, `font`) from any https site. Never scripts, styles, data, workers or frames, and never `http:`: a config naming another kind is refused. | Any site an image names learns that someone viewed the content, and from which address; content can send data out in an image URL to a server of its choosing (the channel P006 closes); whoever owns an image controls what it shows, inside the frame. | A host showing content that already exists, with hotlinked media: Raft's HTML attachment previews, reports whose `<img>` point at other sites (the case P059 was written for). | `images from any https site` (`fonts, images, audio and video from any https site` for all three) | [P059](DECISIONS.md#p059--2026-10-11--passive-content-may-load-from-any-https-site-by-the-hosts-explicit-choice--accepted), [P062](DECISIONS.md#p062--2026-10-11--serveddomainegress-holds-a-host-to-its-own-configs-egress--accepted) | `leak/cdn.spec.ts` (a hotlinked image loads; a script, a stylesheet and a fetch to the same site never reach it; without the flag, nothing does); served `served.domain.egress` (the image must reach an https canary; scripts, styles, fetches and frames never), `leak/served/any-https.spec.ts` |
56
- | **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
59
+ | **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084-p094-p103) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
57
60
 
58
61
  How to decide: **start closed; add `LIBRARY_CDNS` if agents use libraries; add passive `anyHttps`
59
62
  only for existing content with hotlinks**, and only the kinds it hotlinks (usually `img`). An
@@ -89,9 +92,11 @@ export const displays = defineDisplays({
89
92
  ### Live widgets: content that reads your data
90
93
 
91
94
  A live widget shows your data, current, read as the person viewing it, with no network of its own
92
- ([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084)).
95
+ ([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084-p094-p103)).
93
96
  Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeData` (MCP
94
- `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
97
+ `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`). No option opens
98
+ its network: `presets.liveWidget` refuses `egress`, and a capability's own `connect` or `resource`
99
+ origins (a `ConfigError` naming the option, P103); a display that needs an origin is another kind.
95
100
 
96
101
  ```js
97
102
  import { defineDisplays, Refused } from "@botiverse/porthole";
@@ -112,7 +117,8 @@ createHost(displays.configFor(instance, contentSource), {
112
117
  contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
113
118
  };
114
119
  },
115
- // Call changed() when it changes (the content reads it again), or changed(result) to send it.
120
+ // Call changed() when it changes (the content reads it again), or changed(result) to send it:
121
+ // the content's read of it then passes readData's gates, and counts against its rate (P094).
116
122
  subscribeData: ({ uri }, { changed, signal }) => {
117
123
  const stop = realtime.on(uri, () => changed());
118
124
  signal.addEventListener("abort", stop);
@@ -152,7 +158,9 @@ createHost(displays.configFor(instance, contentSource), {
152
158
  The manual tells the agent to draw the widget without the data, with that sentence. A handler's
153
159
  other errors are `failed` in Porthole's words: their messages stay yours.
154
160
  - **Rates stay gates**: 120 reads and 60 subscriptions a minute per display by default; change them
155
- with the capability's `gates` (keep `"consent"` in the list).
161
+ with the capability's `gates` (keep `"consent"` in the list). Every read counts, a read your
162
+ `changed(result)` answers too (P094): a widget that follows a resource changing faster than
163
+ twice a second needs a higher read rate.
156
164
  - **Your page's CSP**: send `displays.embedderCsp(source, …)` (`frame-src` of your content origins
157
165
  and the authorize route, nothing else). It keeps a frame from navigating to an outside site; the
158
166
  shell keeps a served frame from navigating to another content origin (P079), and tells you:
@@ -163,7 +171,8 @@ createHost(displays.configFor(instance, contentSource), {
163
171
  - **Keep live widgets off pages with frames that reach the network.** A frame can `postMessage` any
164
172
  frame on its page, and nothing in it can stop that: a url-mode app (a dev server's preview) or an
165
173
  `anyHttps` display beside a live widget could be handed what it read. Displays with closed egress
166
- or `LIBRARY_CDNS` are fine beside it.
174
+ or `LIBRARY_CDNS` are fine beside it. The rule for any page: its egress is the union of its
175
+ frames' ([THREAT_MODEL.md § S7](THREAT_MODEL.md#s7-several-displays-on-one-page)).
167
176
  - **Opaque live widgets** (no content domain) work, without libraries: the manual tells the agent
168
177
  to draw with SVG and CSS. An opaque frame's only wall against navigating itself away is your
169
178
  page's `frame-src` (the shell's guard gets no events in an opaque origin), so show them on pages
@@ -197,6 +206,46 @@ counts nor resets the count). The request names the display (`request.display`:
197
206
  `title`, and the `instance` you gave the frame, served or opaque), so the dialog can say what it
198
207
  is from your own records. It stays on your side: an opaque frame never gets the instance. `useRunAgain()` gives a "run again" button.
199
208
 
209
+ ### Context for the agent (`setModelContext`)
210
+
211
+ A widget or an MCP Apps view may tell the agent what the person is looking at
212
+ (`ui/update-model-context`, the App SDK's `app.updateModelContext`). That is the content's text,
213
+ in your model's next turn, so by default the person is shown every update first (the `show` gate,
214
+ [P100](DECISIONS.md#p100--2026-10-19--what-content-tells-the-model-the-person-is-shown-first-the-show-gate-on-by-default-for-setmodelcontext--accepted)): pass `show`. It gets the whole update (`request.args`: text blocks and
215
+ structured content, at most `MAX_CONTEXT_CHARS` together) and the display, before your handler,
216
+ and draws it outside the frame: the latest per display, since each replaces the last. Without
217
+ `show` every update is refused (fail closed). React: `PortholeProvider` draws `ContextNotice`
218
+ unless you pass your own `show`.
219
+
220
+ ```js
221
+ createHost(config, {
222
+ handlers: { setModelContext: (update, { displayId }) => modelContext.set(displayId, update) },
223
+ // Before the handler has it: the person sees what the agent will read.
224
+ show: ({ args, display }) => composer.contextChip(display.id, display.title, args),
225
+ });
226
+ ```
227
+
228
+ - **Give it to the model as the content's words** ("the view “Signups” says: …"), never as the
229
+ person's message or as instructions. The manual tells the agent the same.
230
+ - **Send it with the person's next message** (MCP Apps lets a host defer it), so they have seen it
231
+ before the model reads it. If your agent takes turns on its own, add `"confirm"` to the gates.
232
+ - **Opting out**: `setModelContext: { gates: [{ rateLimit: { perMinute: 30 } }], withoutShow: true }`
233
+ names the gates without `show`, and says so on purpose. Do it only where your handler itself puts
234
+ the text in front of the person (or the content is your own): otherwise the content writes into
235
+ your model's turns unseen. Gates named without `show` and without `withoutShow` (a 0.7 config
236
+ that set its own rate) earn the warning `model-context-unshown`, which you see only if you read
237
+ it: Porthole logs nothing, anywhere. Read `host.compiled.warnings` (or `compile(config).warnings`,
238
+ `configWarnings(config)`) at startup, or pass `validateConfig(config, { onWarning })`, and log
239
+ or fail on what you find; otherwise nothing tells you.
240
+ - **What can't be seen is refused**: an update with an invisible character (zero-width ones, bidi
241
+ controls, variation selectors, tag or private-use characters, controls other than new lines and
242
+ tabs), in its text or any string of its structured content, never reaches `show` or your
243
+ handler. Real emoji pass (☀️, 👨‍👩‍👧, 👩🏽‍💻, 1️⃣): a selector right after a pictograph or in a
244
+ keycap, a joiner between two pictographs. So do joiners that shape letters: U+200C or U+200D
245
+ between two letters or marks of Arabic, Syriac, N'Ko, Mongolian, the Indic scripts, Sinhala or
246
+ Myanmar (Persian's می‌خواهم). Subdivision flags (tag characters) don't. Your own `show` resolves only once that very update is visible: if a later update of
247
+ the display replaces it before it is drawn, reject, and it doesn't go.
248
+
200
249
  ## 4. Served pages: the host kit
201
250
 
202
251
  ### Local development
@@ -268,9 +317,35 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
268
317
  yourself as soon as you make it is fine too.
269
318
  - **`nodeHost(content, { request })`** is for an app that keeps its own `node:http` server (or a
270
319
  framework that owns one): put its `request` and `upgrade` listeners on your server, call
271
- `content.start()` once it listens and `content.close()` when it stops.
320
+ `content.start()` once it listens and `content.close()` when it stops. A fetch-style app's
321
+ listener there is `nodeListener(app, { scheme })`, not `toRequest` and `sendResponse` by hand:
322
+ `toRequest` throws for a request fetch can't take (`TRACE`, a Host that is no URL), and a throw
323
+ in a listener ends a Node process. `nodeListener`, `nodeHost` and `nodeServer` answer those 405
324
+ and 400, and a handler or listener that fails 500 (P092). Pass `onError: (error, request) =>
325
+ log.error(…)` to any of them to hear your own failures (by default a process warning).
326
+ - **Rate limit:** `rateLimit: { perMinute }` keys an anonymous viewer by the address the server
327
+ saw (the socket's peer on Node, `CF-Connecting-IP` on Workers), never by `X-Forwarded-For` a
328
+ client can write (P092). **Behind a proxy** (a TLS edge, a load balancer, a CDN), that address
329
+ is the proxy's: say how many proxies append to `X-Forwarded-For` (`trustedProxies: 1` for one
330
+ edge, `2` for a CDN in front of a balancer), or key it yourself (`key: (request, viewer) =>
331
+ …`). Without either, anonymous requests through the proxy share one allowance. An IPv6
332
+ address counts by its /64 (one client's network). Three cases to know:
333
+ - **No peer address:** the Node adapter leaves the socket's peer on the request it makes. Where
334
+ it is missing (Hono's own Node adapter, an app that rebuilds the request with
335
+ `new Request(req)`, Deno or Bun), every anonymous request shares one allowance: set
336
+ `rateLimit.key`.
337
+ - **`trustedProxies` only where the app can't be reached except through those proxies:** a
338
+ client that reaches it directly writes the very `X-Forwarded-For` entry that is counted.
339
+ - **Uploads after the answer:** once an answer is out, a request body no one read is dropped
340
+ for at most 1 MiB and 5 s, then the connection closes (P092). An app that answers early and
341
+ keeps reading the upload (a handler that returns its Response before it has read the
342
+ request's body) is cut off there.
272
343
  - **Health:** `health: { probe: nodeProbe(), onServedChange: (served) => … }` checks the content
273
344
  domain over the real network and falls back to opaque frames while it doesn't answer.
345
+ - **Behind an edge that rewrites headers** (a CDN, a proxy), pass Porthole's
346
+ `Content-Security-Policy` on as it is: a served page opened on a tab of its own (a link, a new
347
+ tab) has no frame, and the header's `sandbox allow-scripts allow-same-origin` is its sandbox
348
+ there (P099). The conformance runner's `served.domain.tab-*` cases fail if it is lost.
274
349
 
275
350
  ### Pages made of many files
276
351
 
@@ -312,9 +387,8 @@ entry: {
312
387
  frame's address instead. A base's segments are letters, digits and `. _ : ~ -`.
313
388
  - **An artifact's versions share an origin**, so they are one trust domain (P082): give versions
314
389
  that must stay apart scopes of their own.
315
- - **Each version is a directory of its origin** (`/v/<n>/`). Keep `/_blob/` (`ASSET_LIBRARY_PATH`)
316
- free: it is reserved for an asset library across versions (not built yet); `versionedAddress`
317
- names nothing there.
390
+ - **Each version is a directory of its origin** (`/v/<n>/`). `/_blob/` (`ASSET_LIBRARY_PATH`) is
391
+ the asset library's, across versions (0.7, below); `versionedAddress` names nothing there.
318
392
  - **In a frame**, the files' address carries the frame's access (WebKit keeps no cookie there,
319
393
  P083): the frame's URL is `/__porthole/f/<sealed>/`, good for the session. A host's
320
394
  `issue` and its locator don't change.
@@ -324,6 +398,109 @@ entry: {
324
398
  })` to run it, and the manual's Files section where a kind serves files. Show a set served: an
325
399
  opaque frame has no origin to serve its files from.
326
400
 
401
+ ### The capability runtime: pages that are apps
402
+
403
+ 0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
404
+ it declared when it was published and what its viewer's level allows. Porthole carries, checks
405
+ and gates the calls; you keep the services. It is an optional layer over the display: what it adds
406
+ to your side (your API's checks, versions, revocation, each person's data) is in
407
+ [THREAT_MODEL.md § The display layer and the app runtime](THREAT_MODEL.md#7-the-display-layer-and-the-app-runtime).
408
+
409
+ ```js
410
+ import { declareCapabilities, presets } from "@botiverse/porthole";
411
+
412
+ // 1. The kind's config offers the runtime and the host functions behind it.
413
+ const page = presets.artifact({
414
+ isolation: "domain", contentOrigins: [source], runtime: "1",
415
+ capabilities: { copyText: {}, openLink: {}, comments: {}, user: {}, artifact: {}, assets: {}, db: {} },
416
+ });
417
+
418
+ // 2. At publish: the artifact's declaration (omitted: carried forward; {}: cleared; an object: replaced).
419
+ const declared = declareCapabilities({ stored: artifact.declaration, given: body.capabilities, config: page });
420
+ if (!declared.ok) return problems(declared.problems); // [{ path: "capabilities.db.rules", message }]
421
+ await myStore.saveDeclaration(artifact.id, declared.declaration); // { capabilities, runtime: "1" }
422
+
423
+ // 3. The viewer's level, in your access (the issue's answer carries it to the display's bridge).
424
+ access: async (instance, viewer) =>
425
+ viewer && { viewer: viewer.id, level: await levelOf(viewer, instance), user: { id: viewer.publicId, name: viewer.name } },
426
+
427
+ // 4. Your services, as handlers (the page's calls arrive checked: declared, shaped, at level).
428
+ handlers: {
429
+ db: (args, { viewer, declared, instance, changed, signal }) => myApi.db(instance, viewer, args, declared?.rules, { changed, signal }),
430
+ artifact: (args, { viewer, instance }) => myApi.artifact(instance, viewer, args), // Refused("conflict") when base moved
431
+ assets: (args, { viewer, instance }) => myApi.assets(instance, viewer, args),
432
+ comments: ({ anchor }) => composer.open(anchor), // true if it opened
433
+ },
434
+ // 5. The mount: what this version declared, within what the artifact declares now; null for a
435
+ // page published before 0.7 (required under a runtime). Before rendering: a stored
436
+ // declaration that isn't one's shape is a problem to show, never a mount with null (0.6's
437
+ // surface) or with either declaration alone (P093).
438
+ const shown = version.declaration ? tryIntersectDeclarations(version.declaration, artifact.declaration) : null;
439
+ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; // "This version can't be shown"
440
+ <PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
441
+ ```
442
+
443
+ - **Built-ins** (`clipboard`, `links`, `downloads`, `comments`) reach every page whose kind offers
444
+ them; everything else only a page that declared it. A page with no declaration (one published
445
+ before 0.7) gets the built-ins through `use` and 0.6's globals as before: give it a declaration
446
+ when it is next published.
447
+ - **Levels**: `view < interact < admin < owner`. Reads are `view`; `chat.send`, `data.call`,
448
+ `context.set` and db writes `interact`; `artifact.publish` and asset removal `admin`; uploads
449
+ `admin` unless you set `assets: { levels: { upload: "interact" } }` (then scripts and styles from
450
+ the library never run: P089). Raise any method in its config's `levels`. Without a viewer the
451
+ runtime's own are refused.
452
+ - **Your API is the wall.** The bridge refuses early, in your page; your handlers call your API as
453
+ the viewer, and it must check again, from its own session and its own stored declaration: never
454
+ trust `context.viewer` or `context.declared` for what your data allows (a page past the bridge
455
+ could forge them). `dbAccess(request, viewer, rules)` is the db rule set (another person's
456
+ `data/users/<id>` refused, `me` resolved), `atLeast(level, "admin")` for a publish. Hold every
457
+ write to an existing document to its `ifVersion` (updates and deletes too), apply a batch in
458
+ order against one state, and refuse a moved base or version with `new Refused("conflict")`;
459
+ check and admit the merged version as any (`checkFileSet`, `admitFiles`).
460
+ - **Per version**: store each version's declaration with it (`declareCapabilities` at its publish)
461
+ and mount a version with `tryIntersectDeclarations(version's, current)` (`intersectDeclarations`
462
+ throws its problems as a `TypeError`); your API's rules for that version are the same
463
+ intersection's (whatever it allows, both declarations allow).
464
+ - **Rules hold in any case**: `dbAccess` holds `Votes/a` to its exact name's rule (else `*`'s)
465
+ and to the rule for `votes` too (any rule naming it in another ASCII case), so a store that
466
+ folds case is safe with it; paths reach your handler as the page wrote them (Porthole never
467
+ lowercases them), and a publish that names a collection twice in different cases is refused.
468
+ - **Objects without a prototype**: checked declarations (`checkDeclaration`, `declareCapabilities`,
469
+ the intersection) have none, so `.hasOwnProperty()` on one, or one in a template string,
470
+ throws: use `Object.hasOwn` and `JSON.stringify`.
471
+ - **Who the page may know**: `Grant.user.id` is one path segment, never `me`; give
472
+ `pseudonymFor(secret, artifact, person)` where pages shouldn't link a person across artifacts.
473
+ - **Assets**: `createContentHost({ assets: (id, access) => myStore.asset(id, access) })` answers
474
+ `{ scope, artifact, name, size, sha256, trusted?, read }` for an id you made (32 random hex
475
+ characters, `ASSET_ID`); `/server` serves it at `/_blob/<id>` on that scope's origin only, to an
476
+ access for that artifact (a session, or a framed page's sealed address), after your check,
477
+ revalidated at each load. Store an upload's `trusted` (the bridge sets it: an admin's code where
478
+ uploaded code may run) and give it back: other code-typed assets are served as downloads. Pages
479
+ show assets with `assets.url(id)` (some engines' frames send no address a `/_blob/` load could
480
+ carry). `{ get, bearer: true }` serves by id alone, an explicit opt-in for public artifacts.
481
+ A trusted script goes out as one only while the config still lets uploaded code run, checked at
482
+ each load (P103): in bearer mode, with no access to name the page's config, every artifact
483
+ config your server has must (one where anyone who interacts uploads, or with no `assets`, turns
484
+ them all into downloads).
485
+ Refuse names that aren't assets (`assetNameProblem`).
486
+ - **Run the conformance cases** against your handlers (no browser):
487
+
488
+ ```js
489
+ import { defineRuntimeConformance } from "@botiverse/porthole/conformance";
490
+ for (const each of defineRuntimeConformance({
491
+ config: page, viewers, handlers: () => freshArtifactHandlers(), assets: () => assetStore,
492
+ // Your own API for the same artifact, signed in as `viewer` with that person's real session:
493
+ // the cases past the bridge then forge the context, as a page past it could.
494
+ api: (handlers, viewer) => apiAs(handlers, viewer),
495
+ })) {
496
+ test(each.name, () => each.run());
497
+ }
498
+ ```
499
+
500
+ - **The agent** declares capabilities in your publish tool (`capabilities: { db: {} }`) and reads
501
+ topic `capabilities` of the manual: declaring, levels, errors, where state goes, each one's types
502
+ (`types/runtime/v1/*.d.ts`, also in the package for a page's own TypeScript).
503
+
327
504
  ### The page
328
505
 
329
506
  ```js
@@ -422,6 +599,17 @@ same parts: `upstreamHeaders.request(headers, { origin, target, websocket })` an
422
599
  detail, reason, hostOrigins })` (a page that tells the frame's host why it shows nothing, desktop
423
600
  schemes included), and `nodeHost`'s `appSocket` (a WebSocket, Porthole's cookies already removed).
424
601
 
602
+ What a url-mode app gets from another origin (P101): its cookie opens it for what its own origin
603
+ asks (`Origin` its own, or `Sec-Fetch-Site` `same-origin` or `none`) and for a navigation that
604
+ opens it (GET or HEAD: your frame, a link, the way back from sign-in); anything else another origin
605
+ sends (a sibling app's fetch, form post, script tag or image, an opaque origin's `null`) is a 403
606
+ that never reaches the app or your `authorize.check`. A WebSocket opens from the app's own origin
607
+ only: `access(request)`, which `nodeHost` asks before `appSocket` and a Worker asks on its own
608
+ upgrade path, is null for any other `Origin`. A client that sends neither header (curl with the
609
+ cookie) is no browser and goes on. An app whose sign-in posts back from another site (OpenID's
610
+ `form_post`) can't sign in through the preview; a tab's `Lax` cookie didn't go with that post
611
+ before either.
612
+
425
613
  ## 5. Cloudflare Workers
426
614
 
427
615
  ```js
@@ -607,7 +795,8 @@ prints each reason at the end; so does `--reporter=json`.
607
795
  (`'unsafe-inline'`), so eval adds no capability, and libraries content uses compile with it
608
796
  (Vue's in-browser build, Alpine.js, Vega's expressions, WebAssembly). Egress, the sandbox and the
609
797
  origin are what isolate it (P071).
610
- - On `http` loopback the session cookies are `porthole-<key>`; on `https`, `__Host-porthole-<key>`.
798
+ - On `http` loopback the session cookies are `porthole-<key>`; on `https`, `__Host-porthole-<key>`,
799
+ and only that name is read (P101: a sibling label can set any other for the whole domain).
611
800
  A frame's are `Secure; SameSite=None; Partitioned` on loopback too: browsers keep `Secure`
612
801
  cookies on `localhost`.
613
802
  - A served frame is one iframe on the content's own origin (no frame inside it), first loaded at
@@ -621,11 +810,12 @@ prints each reason at the end; so does `--reporter=json`.
621
810
  | Import | What |
622
811
  | --- | --- |
623
812
  | `@botiverse/porthole` | `createHost`, `presets`, `defineDisplays`, `portholeClient`, `frameFallback`, `entryTarget`, `lintContent`, `admitContent`, `showTool`, `guideTool`, `checkTool`, `answerGuide`, `guideChanges`, `compile` |
813
+ | `@botiverse/porthole` (the runtime, 0.7) | `declareCapabilities`, `declarationProblems`, `checkDeclaration`, `dbAccess`, `atLeast`, `methodLevel`, `rosterOf`, `assetNameProblem`, `RUNTIME_CAPABILITIES`, `RUNTIME_TYPES`, `Refused` (`conflict`, `forbidden`, `too_large`); `types/runtime/v1/*.d.ts` |
624
814
  | `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame`, `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain` |
625
815
  | `@botiverse/porthole/server` | `createContentHost` (`routes`, `forget`), `contentHostFor`, `prefixedName`, `memoryTicketStore`, `d1TicketStore`, `upstreamHeaders`, `statusPage`, `conformancePage`, the callbacks' types |
626
- | `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeProbe`, `toRequest`, `sendResponse` |
816
+ | `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeListener`, `nodeProbe`, `toRequest`, `sendResponse` |
627
817
  | `@botiverse/porthole/check` | `checkPage`, `playwrightDriver`, `cdpDriver` (`CHECK_ORIGIN`, `CHECK_CONTENT_DOMAIN`: the names a driver of your own answers); `/check/page`, the check page's script (`checkPage` has it already) |
628
818
  | `@botiverse/porthole/mcp` | the MCP Apps adapter (views, the sandbox proxy) |
629
- | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`; `/conformance/reporter`, skip reasons |
819
+ | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`, `defineRuntimeConformance` (no browser); `/conformance/reporter`, skip reasons |
630
820
 
631
821
  The types' doc comments are the precise reference; DESIGN.md § "The host kit" is the long form.