@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.
- package/README.md +25 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +38 -5
- package/dist/bridge/bridge.js +469 -39
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +17 -0
- package/dist/bridge/types.d.ts +73 -5
- 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 +16 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +55 -0
- package/dist/compile/policy.js +157 -0
- package/dist/config/capabilities.d.ts +85 -7
- package/dist/config/capabilities.js +32 -2
- package/dist/config/schema.d.ts +35 -0
- package/dist/config/validate.d.ts +9 -3
- package/dist/config/validate.js +92 -8
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +11 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +324 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +9 -0
- package/dist/guide/gates.js +31 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +35 -33
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +210 -0
- package/dist/host/create-host.js +73 -37
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +26 -1
- package/dist/index.d.ts +11 -4
- package/dist/index.js +11 -2
- package/dist/isolation/types.d.ts +8 -0
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +22 -8
- package/dist/presets/presets.js +40 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +116 -0
- package/dist/protocol/shell-adapter.js +64 -25
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +91 -16
- package/dist/react/frame.d.ts +25 -1
- package/dist/react/frame.js +85 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +201 -0
- package/dist/runtime/contract.js +245 -0
- package/dist/runtime/db.d.ts +188 -0
- package/dist/runtime/db.js +502 -0
- package/dist/runtime/declaration.d.ts +100 -0
- package/dist/runtime/declaration.js +363 -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 +215 -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 +19 -1
- package/dist/server/files.js +115 -6
- package/dist/server/host.d.ts +24 -2
- package/dist/server/host.js +137 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.js +2 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- 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 +318 -52
- package/dist/server/types.d.ts +74 -2
- package/dist/shell/document.d.ts +16 -0
- package/dist/shell/document.js +19 -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 +390 -56
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +205 -15
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +1867 -11
- package/docs/DESIGN.md +137 -17
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +16 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +601 -51
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +17 -0
- package/src/bridge/types.ts +76 -5
- 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 +16 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +177 -0
- package/src/config/capabilities.ts +71 -5
- package/src/config/schema.ts +35 -0
- package/src/config/validate.ts +141 -8
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +17 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +594 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +37 -0
- package/src/guide/guide.ts +61 -55
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +253 -0
- package/src/host/create-host.ts +88 -36
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +33 -1
- package/src/index.ts +94 -0
- package/src/isolation/types.ts +8 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +67 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +141 -0
- package/src/protocol/shell-adapter.ts +79 -26
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +108 -15
- package/src/react/frame.tsx +120 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +339 -0
- package/src/runtime/db.ts +650 -0
- package/src/runtime/declaration.ts +516 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +355 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +138 -7
- package/src/server/host.ts +170 -3
- package/src/server/index.ts +4 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +370 -57
- package/src/server/types.ts +73 -2
- package/src/shell/document.ts +29 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +390 -56
- 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 +27 -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
|
@@ -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>/`).
|
|
316
|
-
|
|
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
|
|
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.
|