@botiverse/porthole 0.6.0 → 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.
- package/README.md +16 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +200 -8
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/policy.d.ts +19 -0
- package/dist/compile/policy.js +42 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +24 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +66 -4
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +34 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +24 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +8 -2
- package/dist/index.js +9 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +48 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +14 -1
- package/dist/server/files.js +97 -3
- package/dist/server/host.d.ts +6 -1
- package/dist/server/host.js +5 -0
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +1 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +214 -35
- package/dist/server/types.d.ts +69 -0
- package/dist/shell/document.d.ts +8 -0
- package/dist/shell/document.js +16 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +29 -42
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +91 -6
- package/docs/ARCHITECTURE.md +22 -3
- package/docs/DECISIONS.md +415 -6
- package/docs/DESIGN.md +66 -0
- package/package.json +3 -1
- package/src/bridge/bridge.ts +273 -12
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/policy.ts +54 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +24 -0
- package/src/config/validate.ts +99 -4
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +59 -53
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +34 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +89 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +52 -3
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +117 -4
- package/src/server/host.ts +12 -0
- package/src/server/index.ts +3 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +247 -37
- package/src/server/types.ts +68 -0
- package/src/shell/document.ts +21 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +29 -42
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- 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
|
@@ -50,8 +50,8 @@ data (fetch, WebSocket). Every preset starts closed, and a kind opens more only
|
|
|
50
50
|
|
|
51
51
|
| Level | Config (`options`) | What it opens | The risk it re-opens | Typical host | The agent's manual says | Why | Tested by |
|
|
52
52
|
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
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) |
|
|
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-p089) | 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-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
55
|
| **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
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) |
|
|
57
57
|
|
|
@@ -312,9 +312,8 @@ entry: {
|
|
|
312
312
|
frame's address instead. A base's segments are letters, digits and `. _ : ~ -`.
|
|
313
313
|
- **An artifact's versions share an origin**, so they are one trust domain (P082): give versions
|
|
314
314
|
that must stay apart scopes of their own.
|
|
315
|
-
- **Each version is a directory of its origin** (`/v/<n>/`).
|
|
316
|
-
|
|
317
|
-
names nothing there.
|
|
315
|
+
- **Each version is a directory of its origin** (`/v/<n>/`). `/_blob/` (`ASSET_LIBRARY_PATH`) is
|
|
316
|
+
the asset library's, across versions (0.7, below); `versionedAddress` names nothing there.
|
|
318
317
|
- **In a frame**, the files' address carries the frame's access (WebKit keeps no cookie there,
|
|
319
318
|
P083): the frame's URL is `/__porthole/f/<sealed>/`, good for the session. A host's
|
|
320
319
|
`issue` and its locator don't change.
|
|
@@ -324,6 +323,91 @@ entry: {
|
|
|
324
323
|
})` to run it, and the manual's Files section where a kind serves files. Show a set served: an
|
|
325
324
|
opaque frame has no origin to serve its files from.
|
|
326
325
|
|
|
326
|
+
### The capability runtime: pages that are apps
|
|
327
|
+
|
|
328
|
+
0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
|
|
329
|
+
it declared when it was published and what its viewer's level allows. Porthole carries, checks
|
|
330
|
+
and gates the calls; you keep the services.
|
|
331
|
+
|
|
332
|
+
```js
|
|
333
|
+
import { declareCapabilities, presets } from "@botiverse/porthole";
|
|
334
|
+
|
|
335
|
+
// 1. The kind's config offers the runtime and the host functions behind it.
|
|
336
|
+
const page = presets.artifact({
|
|
337
|
+
isolation: "domain", contentOrigins: [source], runtime: "1",
|
|
338
|
+
capabilities: { copyText: {}, openLink: {}, comments: {}, user: {}, artifact: {}, assets: {}, db: {} },
|
|
339
|
+
});
|
|
340
|
+
|
|
341
|
+
// 2. At publish: the artifact's declaration (omitted: carried forward; {}: cleared; an object: replaced).
|
|
342
|
+
const declared = declareCapabilities({ stored: artifact.declaration, given: body.capabilities, config: page });
|
|
343
|
+
if (!declared.ok) return problems(declared.problems); // [{ path: "capabilities.db.rules", message }]
|
|
344
|
+
await myStore.saveDeclaration(artifact.id, declared.declaration); // { capabilities, runtime: "1" }
|
|
345
|
+
|
|
346
|
+
// 3. The viewer's level, in your access (the issue's answer carries it to the display's bridge).
|
|
347
|
+
access: async (instance, viewer) =>
|
|
348
|
+
viewer && { viewer: viewer.id, level: await levelOf(viewer, instance), user: { id: viewer.publicId, name: viewer.name } },
|
|
349
|
+
|
|
350
|
+
// 4. Your services, as handlers (the page's calls arrive checked: declared, shaped, at level).
|
|
351
|
+
handlers: {
|
|
352
|
+
db: (args, { viewer, declared, instance, changed, signal }) => myApi.db(instance, viewer, args, declared?.rules, { changed, signal }),
|
|
353
|
+
artifact: (args, { viewer, instance }) => myApi.artifact(instance, viewer, args), // Refused("conflict") when base moved
|
|
354
|
+
assets: (args, { viewer, instance }) => myApi.assets(instance, viewer, args),
|
|
355
|
+
comments: ({ anchor }) => composer.open(anchor), // true if it opened
|
|
356
|
+
},
|
|
357
|
+
// 5. The mount: what this version declared, within what the artifact declares now; null for a
|
|
358
|
+
// page published before 0.7 (required under a runtime).
|
|
359
|
+
<PortholeView display="page" instance={instance}
|
|
360
|
+
declaration={version.declaration ? intersectDeclarations(version.declaration, artifact.declaration) : null} />
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
- **Built-ins** (`clipboard`, `links`, `downloads`, `comments`) reach every page whose kind offers
|
|
364
|
+
them; everything else only a page that declared it. A page with no declaration (one published
|
|
365
|
+
before 0.7) gets the built-ins through `use` and 0.6's globals as before: give it a declaration
|
|
366
|
+
when it is next published.
|
|
367
|
+
- **Levels**: `view < interact < admin < owner`. Reads are `view`; `chat.send`, `data.call`,
|
|
368
|
+
`context.set` and db writes `interact`; `artifact.publish` and asset removal `admin`; uploads
|
|
369
|
+
`admin` unless you set `assets: { levels: { upload: "interact" } }` (then scripts and styles from
|
|
370
|
+
the library never run: P089). Raise any method in its config's `levels`. Without a viewer the
|
|
371
|
+
runtime's own are refused.
|
|
372
|
+
- **Your API is the wall.** The bridge refuses early, in your page; your handlers call your API as
|
|
373
|
+
the viewer, and it must check again, from its own session and its own stored declaration: never
|
|
374
|
+
trust `context.viewer` or `context.declared` for what your data allows (a page past the bridge
|
|
375
|
+
could forge them). `dbAccess(request, viewer, rules)` is the db rule set (another person's
|
|
376
|
+
`data/users/<id>` refused, `me` resolved), `atLeast(level, "admin")` for a publish. Hold every
|
|
377
|
+
write to an existing document to its `ifVersion` (updates and deletes too), apply a batch in
|
|
378
|
+
order against one state, and refuse a moved base or version with `new Refused("conflict")`;
|
|
379
|
+
check and admit the merged version as any (`checkFileSet`, `admitFiles`).
|
|
380
|
+
- **Per version**: store each version's declaration with it (`declareCapabilities` at its publish)
|
|
381
|
+
and mount a version with `intersectDeclarations(version's, current)`.
|
|
382
|
+
- **Who the page may know**: `Grant.user.id` is one path segment, never `me`; give
|
|
383
|
+
`pseudonymFor(secret, artifact, person)` where pages shouldn't link a person across artifacts.
|
|
384
|
+
- **Assets**: `createContentHost({ assets: (id, access) => myStore.asset(id, access) })` answers
|
|
385
|
+
`{ scope, artifact, name, size, sha256, trusted?, read }` for an id you made (32 random hex
|
|
386
|
+
characters, `ASSET_ID`); `/server` serves it at `/_blob/<id>` on that scope's origin only, to an
|
|
387
|
+
access for that artifact (a session, or a framed page's sealed address), after your check,
|
|
388
|
+
revalidated at each load. Store an upload's `trusted` (the bridge sets it: an admin's code where
|
|
389
|
+
uploaded code may run) and give it back: other code-typed assets are served as downloads. Pages
|
|
390
|
+
show assets with `assets.url(id)` (some engines' frames send no address a `/_blob/` load could
|
|
391
|
+
carry). `{ get, bearer: true }` serves by id alone, an explicit opt-in for public artifacts.
|
|
392
|
+
Refuse names that aren't assets (`assetNameProblem`).
|
|
393
|
+
- **Run the conformance cases** against your handlers (no browser):
|
|
394
|
+
|
|
395
|
+
```js
|
|
396
|
+
import { defineRuntimeConformance } from "@botiverse/porthole/conformance";
|
|
397
|
+
for (const each of defineRuntimeConformance({
|
|
398
|
+
config: page, viewers, handlers: () => freshArtifactHandlers(), assets: () => assetStore,
|
|
399
|
+
// Your own API for the same artifact, signed in as `viewer` with that person's real session:
|
|
400
|
+
// the cases past the bridge then forge the context, as a page past it could.
|
|
401
|
+
api: (handlers, viewer) => apiAs(handlers, viewer),
|
|
402
|
+
})) {
|
|
403
|
+
test(each.name, () => each.run());
|
|
404
|
+
}
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
- **The agent** declares capabilities in your publish tool (`capabilities: { db: {} }`) and reads
|
|
408
|
+
topic `capabilities` of the manual: declaring, levels, errors, where state goes, each one's types
|
|
409
|
+
(`types/runtime/v1/*.d.ts`, also in the package for a page's own TypeScript).
|
|
410
|
+
|
|
327
411
|
### The page
|
|
328
412
|
|
|
329
413
|
```js
|
|
@@ -621,11 +705,12 @@ prints each reason at the end; so does `--reporter=json`.
|
|
|
621
705
|
| Import | What |
|
|
622
706
|
| --- | --- |
|
|
623
707
|
| `@botiverse/porthole` | `createHost`, `presets`, `defineDisplays`, `portholeClient`, `frameFallback`, `entryTarget`, `lintContent`, `admitContent`, `showTool`, `guideTool`, `checkTool`, `answerGuide`, `guideChanges`, `compile` |
|
|
708
|
+
| `@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
709
|
| `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame`, `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain` |
|
|
625
710
|
| `@botiverse/porthole/server` | `createContentHost` (`routes`, `forget`), `contentHostFor`, `prefixedName`, `memoryTicketStore`, `d1TicketStore`, `upstreamHeaders`, `statusPage`, `conformancePage`, the callbacks' types |
|
|
626
711
|
| `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeProbe`, `toRequest`, `sendResponse` |
|
|
627
712
|
| `@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
713
|
| `@botiverse/porthole/mcp` | the MCP Apps adapter (views, the sandbox proxy) |
|
|
629
|
-
| `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage
|
|
714
|
+
| `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`, `defineRuntimeConformance` (no browser); `/conformance/reporter`, skip reasons |
|
|
630
715
|
|
|
631
716
|
The types' doc comments are the precise reference; DESIGN.md § "The host kit" is the long form.
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -16,6 +16,13 @@ Porthole renders **agent-drawn HTML plus a declared set of host functions.**
|
|
|
16
16
|
needs** (origins it must reach), and its **guide entry** (how the manual
|
|
17
17
|
describes it).
|
|
18
18
|
|
|
19
|
+
A page published as an artifact may be an app: under the **capability runtime** it reaches its
|
|
20
|
+
host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
|
|
21
|
+
level allows. The runtime is how content reaches host functions, not new ones: each of its
|
|
22
|
+
methods is served by a host function the config declares, and the bridge alone decides each call
|
|
23
|
+
(the page's declaration, the viewer's level, the gates). The services behind them (a document
|
|
24
|
+
store, an asset library, versions, comments) are the host's.
|
|
25
|
+
|
|
19
26
|
One capability list therefore drives three artifacts: the **bridge** (which
|
|
20
27
|
functions the shell wires and the host handles), the **CSP** (what the sandbox
|
|
21
28
|
may reach), and the **manual** (what the agent is told). This is why the config
|
|
@@ -216,7 +223,8 @@ only the declared content origins.
|
|
|
216
223
|
|
|
217
224
|
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
218
225
|
origins the config's capabilities declare (and, for a served page with files,
|
|
219
|
-
its own version's path on its own origin
|
|
226
|
+
its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
|
|
227
|
+
host's own server, P082, P089). Two
|
|
220
228
|
kinds of attacker matter:
|
|
221
229
|
- *Attacking the host* (steal credentials, read other data, escape the
|
|
222
230
|
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
@@ -234,14 +242,21 @@ only the declared content origins.
|
|
|
234
242
|
closed than its config says: an origin the config opens stays shut. On such
|
|
235
243
|
a page prefer domain mode, whose frames inherit nothing (P058).
|
|
236
244
|
|
|
237
|
-
3. **
|
|
245
|
+
3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
|
|
246
|
+
built-ins and what it declared at publish (stored by the host, given to the mount), and each
|
|
247
|
+
method only for viewers at its level (`view < interact < admin < owner`), which the host's
|
|
248
|
+
access says. The bridge refuses before any handler; the host's own API checks again, since it
|
|
249
|
+
is its data's wall. A person's per-user data is reached by the host's id for them, never the
|
|
250
|
+
content's word.
|
|
251
|
+
|
|
252
|
+
4. **Message boundary.** Every message crossing the frame is validated against a
|
|
238
253
|
schema and checked for sender identity before use; the shell accepts messages
|
|
239
254
|
only from its host, and the host only from its frame. What the frame says about
|
|
240
255
|
itself (its size, its errors, an annotation's anchor and where it is) is the
|
|
241
256
|
content's word even when the shell says it, since they share a realm: the host
|
|
242
257
|
bounds it and uses it as a UI hint, never as a permission (P053).
|
|
243
258
|
|
|
244
|
-
|
|
259
|
+
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
245
260
|
*policy* are the host's; carrying the host's decision safely onto the content
|
|
246
261
|
domain is Porthole's *mechanism*. The host decides who may open an instance
|
|
247
262
|
before it calls `issue` (a viewer it knows, or a public link), and may decide
|
|
@@ -262,6 +277,10 @@ only the declared content origins.
|
|
|
262
277
|
names are the default vocabulary.
|
|
263
278
|
- **The person's clipboard** is the host's alone: content asks for a copy
|
|
264
279
|
(`copyText`), the host performs it and shows what it copied (P051, P052).
|
|
280
|
+
- **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
|
|
281
|
+
namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
|
|
282
|
+
its config and serves them through its handlers; an artifact's asset library is served by
|
|
283
|
+
`/server` from the host's store at `/_blob/<id>` on the artifact's origin.
|
|
265
284
|
- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
|
|
266
285
|
the shell; anchors are W3C Web Annotation selectors a host stores with its own
|
|
267
286
|
comments (P053).
|