@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
package/dist/server/types.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import type { ViewerLevel } from "../runtime/levels.ts";
|
|
3
4
|
import type { Naming } from "./naming.ts";
|
|
4
5
|
export interface ContentDomain {
|
|
5
6
|
/**
|
|
@@ -57,6 +58,23 @@ export type Grant = ({
|
|
|
57
58
|
* url-mode app's every request, rides on.
|
|
58
59
|
*/
|
|
59
60
|
readonly sessionSeconds?: number;
|
|
61
|
+
/**
|
|
62
|
+
* The viewer's level on this instance (P087), as the host decided it now: carried in the
|
|
63
|
+
* issue's answer (`FrameLocation.viewer`) to the display's bridge, which checks each runtime
|
|
64
|
+
* method's level against it. Never in the ticket or the cookie, never shown to content but by
|
|
65
|
+
* the `user` capability.
|
|
66
|
+
*/
|
|
67
|
+
readonly level?: ViewerLevel;
|
|
68
|
+
/**
|
|
69
|
+
* Who the viewer is to pages that declare `user` (P087): the host's public id for them (whose
|
|
70
|
+
* per-user data, `data/users/<id>`, the page reaches: one path segment, never `me`) and a name.
|
|
71
|
+
* Never `viewer`, unless the host means it to be seen; `pseudonymFor(secret, artifact, person)`
|
|
72
|
+
* gives an id per artifact, so pages can't link a person across artifacts. Only with `level`.
|
|
73
|
+
*/
|
|
74
|
+
readonly user?: {
|
|
75
|
+
readonly id: string;
|
|
76
|
+
readonly name?: string;
|
|
77
|
+
};
|
|
60
78
|
};
|
|
61
79
|
export interface TicketRecord {
|
|
62
80
|
readonly instance: InstanceRef;
|
|
@@ -122,6 +140,50 @@ export interface StoredFiles {
|
|
|
122
140
|
export type StoredVersion = {
|
|
123
141
|
readonly html: string;
|
|
124
142
|
} | StoredFiles;
|
|
143
|
+
/**
|
|
144
|
+
* One asset of an artifact's library (P089), as the host stored it: served at `/_blob/<id>` on
|
|
145
|
+
* the origin of `scope`, and nowhere else. Its type is Porthole's for `name`'s extension, never
|
|
146
|
+
* the uploader's; it is never served as a page.
|
|
147
|
+
*/
|
|
148
|
+
export interface StoredAsset {
|
|
149
|
+
/** The storage scope whose origin serves it (the artifact's). */
|
|
150
|
+
readonly scope: string;
|
|
151
|
+
/**
|
|
152
|
+
* The artifact whose library holds it (`ServedDocument`'s `id`, after the review): served only
|
|
153
|
+
* to an access for that artifact, never another one sharing the scope.
|
|
154
|
+
*/
|
|
155
|
+
readonly artifact: string;
|
|
156
|
+
/**
|
|
157
|
+
* Whether it may run as code (P089, after the review): a script, stylesheet or WebAssembly an
|
|
158
|
+
* admin uploaded where uploaded code may run (the upload's `trusted`). Any other code-typed
|
|
159
|
+
* asset is served as a download, whatever the config says now.
|
|
160
|
+
*/
|
|
161
|
+
readonly trusted?: boolean;
|
|
162
|
+
/** Its file name (its extension types it). */
|
|
163
|
+
readonly name: string;
|
|
164
|
+
readonly size: number;
|
|
165
|
+
/** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
|
|
166
|
+
readonly sha256: string;
|
|
167
|
+
read(): Promise<FileBody | null>;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Where an artifact's assets are kept (P089): the host's library, by id. Ids are the host's, 32
|
|
171
|
+
* lowercase hex characters made at random (`ASSET_ID`): an asset's address is known only to those
|
|
172
|
+
* shown it; Porthole serves one only on its own scope's origin.
|
|
173
|
+
*/
|
|
174
|
+
export interface AssetStore {
|
|
175
|
+
/**
|
|
176
|
+
* The asset, for `access` (who asks, for which artifact: the host decides, and its check runs
|
|
177
|
+
* after); null if it isn't there for them. `access` is null only in bearer mode.
|
|
178
|
+
*/
|
|
179
|
+
get(id: string, access: Access | null): Promise<StoredAsset | null>;
|
|
180
|
+
/**
|
|
181
|
+
* Bearer mode, an explicit opt-in (after the review): serve an asset to anyone holding its id,
|
|
182
|
+
* with no access and no host check (a public artifact's library). Its id is then a capability:
|
|
183
|
+
* whoever saw it keeps it until the asset is removed.
|
|
184
|
+
*/
|
|
185
|
+
readonly bearer?: boolean;
|
|
186
|
+
}
|
|
125
187
|
/** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
|
|
126
188
|
export interface ArtifactStore {
|
|
127
189
|
get(id: string, version: string): Promise<StoredVersion | null>;
|
|
@@ -188,6 +250,13 @@ export interface ServerOptions {
|
|
|
188
250
|
*/
|
|
189
251
|
readonly configs: Readonly<Record<string, PortholeConfig>>;
|
|
190
252
|
readonly artifacts?: ArtifactStore;
|
|
253
|
+
/**
|
|
254
|
+
* Artifacts' asset libraries (P089): `/_blob/<id>` on each content origin, for a request that
|
|
255
|
+
* carries an access to the asset's own artifact (a frame's sealed files' address as its
|
|
256
|
+
* `Referer`, or a session cookie), after the host's check. Absent: `/_blob/` is a clean address
|
|
257
|
+
* like any other.
|
|
258
|
+
*/
|
|
259
|
+
readonly assets?: AssetStore;
|
|
191
260
|
readonly tickets?: TicketStore;
|
|
192
261
|
/** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
|
|
193
262
|
readonly upstream?: Upstream;
|
package/dist/shell/document.d.ts
CHANGED
|
@@ -32,6 +32,8 @@ export interface ShellDocumentOptions {
|
|
|
32
32
|
* (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
|
|
33
33
|
* other pages there, and to nothing else.
|
|
34
34
|
*/
|
|
35
|
+
/** `same-origin`: the document's loads tell its own origin its address (P091); else none. */
|
|
36
|
+
readonly referrer?: "same-origin";
|
|
35
37
|
readonly files?: {
|
|
36
38
|
readonly base: string;
|
|
37
39
|
/**
|
|
@@ -51,4 +53,10 @@ export interface ShellDocumentOptions {
|
|
|
51
53
|
* The frame's document: its policy first, then the base styles, an empty root, and the runtime.
|
|
52
54
|
* A given `document` travels in the runtime's plan, as data.
|
|
53
55
|
*/
|
|
56
|
+
/**
|
|
57
|
+
* The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
|
|
58
|
+
* globals (the legacy path, P085) for what the config declares, and the capability runtime where
|
|
59
|
+
* the config has one.
|
|
60
|
+
*/
|
|
61
|
+
export declare function composedRuntime(plan: ShellPlan): string;
|
|
54
62
|
export declare function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string;
|
package/dist/shell/document.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { hostOriginProblem } from "../isolation/served.js";
|
|
2
2
|
import { ANNOTATE_RUNTIME } from "./annotate.js";
|
|
3
|
+
import { LEGACY_GLOBALS_RUNTIME } from "./legacy.js";
|
|
3
4
|
import { SHELL_RUNTIME } from "./runtime.js";
|
|
5
|
+
import { USE_RUNTIME } from "./use.js";
|
|
4
6
|
/** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
|
|
5
7
|
function filesBaseOk(base) {
|
|
6
8
|
try {
|
|
@@ -62,6 +64,16 @@ body {
|
|
|
62
64
|
* The frame's document: its policy first, then the base styles, an empty root, and the runtime.
|
|
63
65
|
* A given `document` travels in the runtime's plan, as data.
|
|
64
66
|
*/
|
|
67
|
+
/**
|
|
68
|
+
* The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
|
|
69
|
+
* globals (the legacy path, P085) for what the config declares, and the capability runtime where
|
|
70
|
+
* the config has one.
|
|
71
|
+
*/
|
|
72
|
+
export function composedRuntime(plan) {
|
|
73
|
+
return SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME)
|
|
74
|
+
.replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
|
|
75
|
+
.replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
|
|
76
|
+
}
|
|
65
77
|
export function shellDocument(plan, csp, options) {
|
|
66
78
|
for (const origin of options.origins) {
|
|
67
79
|
const problem = hostOriginProblem(origin);
|
|
@@ -82,7 +94,7 @@ export function shellDocument(plan, csp, options) {
|
|
|
82
94
|
const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
|
|
83
95
|
// The annotation runtime only where it is declared; spliced in before the plan, which may carry
|
|
84
96
|
// any text (a document) and must not be searched.
|
|
85
|
-
const runtime =
|
|
97
|
+
const runtime = composedRuntime(plan).replace("__PLAN__", () => scriptJson({
|
|
86
98
|
...plan,
|
|
87
99
|
origins: options.origins,
|
|
88
100
|
...(options.document === undefined ? {} : { document: options.document }),
|
|
@@ -101,7 +113,9 @@ export function shellDocument(plan, csp, options) {
|
|
|
101
113
|
options.cspMeta === false
|
|
102
114
|
? null
|
|
103
115
|
: `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
|
|
104
|
-
|
|
116
|
+
// A framed page of files whose config serves assets says its sealed address to its own
|
|
117
|
+
// origin only, which its asset loads carry (P091); every other document says nothing.
|
|
118
|
+
`<meta name="referrer" content="${options.referrer === "same-origin" ? "same-origin" : "no-referrer"}">`,
|
|
105
119
|
// Off for good: an engine may prefetch names it sees in links, outside the CSP.
|
|
106
120
|
'<meta http-equiv="x-dns-prefetch-control" content="off">',
|
|
107
121
|
].filter((line) => line !== null);
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
|
|
3
|
+
* (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
|
|
4
|
+
* runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
|
|
5
|
+
* capability runtime reaches the same host functions through `porthole.use` instead; the bridge
|
|
6
|
+
* gates both paths alike, and holds a page that declared capabilities to its declaration on
|
|
7
|
+
* either (P086).
|
|
8
|
+
*
|
|
9
|
+
* Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
|
|
10
|
+
* pages' calls to `porthole.use`); until then the manual teaches these only where the config has
|
|
11
|
+
* no runtime.
|
|
12
|
+
*/
|
|
13
|
+
export declare const LEGACY_GLOBALS_RUNTIME: string;
|
|
14
|
+
/** The globals the legacy path defines, by the capability that defines each. */
|
|
15
|
+
export declare const LEGACY_GLOBALS: {
|
|
16
|
+
readonly sendPrompt: "sendPrompt";
|
|
17
|
+
readonly copyText: "copyText";
|
|
18
|
+
readonly openLink: "openLink";
|
|
19
|
+
readonly readData: "readData";
|
|
20
|
+
readonly subscribeData: "subscribeData";
|
|
21
|
+
};
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
|
|
3
|
+
* (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
|
|
4
|
+
* runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
|
|
5
|
+
* capability runtime reaches the same host functions through `porthole.use` instead; the bridge
|
|
6
|
+
* gates both paths alike, and holds a page that declared capabilities to its declaration on
|
|
7
|
+
* either (P086).
|
|
8
|
+
*
|
|
9
|
+
* Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
|
|
10
|
+
* pages' calls to `porthole.use`); until then the manual teaches these only where the config has
|
|
11
|
+
* no runtime.
|
|
12
|
+
*/
|
|
13
|
+
export const LEGACY_GLOBALS_RUNTIME = String.raw `
|
|
14
|
+
if (declared("sendPrompt")) {
|
|
15
|
+
lock(window, "sendPrompt", (text) => {
|
|
16
|
+
if (!gestured("sendPrompt")) {
|
|
17
|
+
return refuse("sendPrompt needs a click: call it from a button's handler");
|
|
18
|
+
}
|
|
19
|
+
const words = String(text);
|
|
20
|
+
if (words.trim() === "" || words.length > plan.maxPromptChars) {
|
|
21
|
+
return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
|
|
22
|
+
}
|
|
23
|
+
return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
|
|
24
|
+
(result) => !(result && result.isError),
|
|
25
|
+
);
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
if (declared("copyText")) {
|
|
29
|
+
lock(window, "copyText", (text) => {
|
|
30
|
+
if (!gestured("copyText")) {
|
|
31
|
+
return refuse("copyText needs a click: call it from a button's handler");
|
|
32
|
+
}
|
|
33
|
+
const words = String(text);
|
|
34
|
+
if (words === "" || words.length > plan.maxCopyChars) {
|
|
35
|
+
return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
|
|
36
|
+
}
|
|
37
|
+
return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
if (declared("openLink")) {
|
|
41
|
+
lock(window, "openLink", (url) => {
|
|
42
|
+
if (!gestured("openLink")) {
|
|
43
|
+
return refuse("openLink needs a click: call it from a link's or button's handler");
|
|
44
|
+
}
|
|
45
|
+
return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
if (declared("readData")) {
|
|
50
|
+
lock(window, "readData", readValue);
|
|
51
|
+
}
|
|
52
|
+
if (follow !== null) {
|
|
53
|
+
lock(window, "subscribeData", follow);
|
|
54
|
+
}
|
|
55
|
+
`;
|
|
56
|
+
/** The globals the legacy path defines, by the capability that defines each. */
|
|
57
|
+
export const LEGACY_GLOBALS = {
|
|
58
|
+
sendPrompt: "sendPrompt",
|
|
59
|
+
copyText: "copyText",
|
|
60
|
+
openLink: "openLink",
|
|
61
|
+
readData: "readData",
|
|
62
|
+
subscribeData: "subscribeData",
|
|
63
|
+
};
|
package/dist/shell/plan.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type CapabilityName } from "../config/capabilities.ts";
|
|
2
2
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import { type RuntimeVersion } from "../runtime/contract.ts";
|
|
3
4
|
/**
|
|
4
5
|
* What the shell wires, derived from the config: the JSON the shell's runtime is given. The
|
|
5
6
|
* agreement test reads it against the CSP and the manual, so it lists everything the shell
|
|
@@ -20,8 +21,23 @@ export interface ShellPlan {
|
|
|
20
21
|
readonly userActivation: boolean;
|
|
21
22
|
};
|
|
22
23
|
};
|
|
23
|
-
/**
|
|
24
|
+
/**
|
|
25
|
+
* The globals the shell defines on `window` and the manual teaches: `porthole` where the config
|
|
26
|
+
* has the capability runtime (P085), else 0.6's (sugar over the protocol's requests).
|
|
27
|
+
*/
|
|
24
28
|
readonly globals: readonly string[];
|
|
29
|
+
/**
|
|
30
|
+
* 0.6's globals the shell still defines under the runtime, for pages written before it (the
|
|
31
|
+
* legacy path, `shell/legacy.ts`), which the manual no longer teaches. Empty without a runtime.
|
|
32
|
+
*/
|
|
33
|
+
readonly legacyGlobals: readonly string[];
|
|
34
|
+
/** The capability runtime's contract version, where the config has one (`porthole.use`). */
|
|
35
|
+
readonly runtime?: RuntimeVersion;
|
|
36
|
+
/**
|
|
37
|
+
* The runtime methods whose own gates want a gesture (`capability.method`: `artifact.publish`,
|
|
38
|
+
* `assets.delete`): the shell refuses them without one, as it does a host function's.
|
|
39
|
+
*/
|
|
40
|
+
readonly methodActivation?: readonly string[];
|
|
25
41
|
/** The theme variables the shell applies; it drops any other name the host sends. */
|
|
26
42
|
readonly themeVariables: readonly string[];
|
|
27
43
|
/** The window event fired after a theme change. */
|
package/dist/shell/plan.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { MAX_COPY_CHARS, capabilitySpec } from "../config/capabilities.js";
|
|
2
2
|
import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
|
|
3
3
|
import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.js";
|
|
4
|
+
import { RUNTIME_GLOBAL, methodGates, offeredCapabilities, runtimeCapability, } from "../runtime/contract.js";
|
|
4
5
|
export function shellPlan(config) {
|
|
5
6
|
if (config.mode === "url") {
|
|
6
7
|
return null;
|
|
@@ -13,17 +14,27 @@ export function shellPlan(config) {
|
|
|
13
14
|
userActivation: effectiveGates(config, name).includes("user-activation"),
|
|
14
15
|
};
|
|
15
16
|
}
|
|
16
|
-
const
|
|
17
|
+
const legacy = protocol === "shell"
|
|
17
18
|
? declared.flatMap((name) => {
|
|
18
19
|
const spec = capabilitySpec(name);
|
|
19
20
|
return spec.global === undefined ? [] : [spec.global];
|
|
20
21
|
})
|
|
21
22
|
: [];
|
|
23
|
+
const runtime = protocol === "shell" ? config.runtime : undefined;
|
|
22
24
|
return {
|
|
23
25
|
protocol,
|
|
24
26
|
content: config.mode === "artifact" ? "document" : "fragment",
|
|
25
27
|
capabilities,
|
|
26
|
-
globals,
|
|
28
|
+
globals: runtime === undefined ? legacy : [RUNTIME_GLOBAL],
|
|
29
|
+
legacyGlobals: runtime === undefined ? [] : legacy,
|
|
30
|
+
...(runtime === undefined
|
|
31
|
+
? {}
|
|
32
|
+
: {
|
|
33
|
+
runtime,
|
|
34
|
+
methodActivation: offeredCapabilities(config).flatMap((family) => Object.keys(runtimeCapability(family).methods)
|
|
35
|
+
.filter((method) => methodGates(config, family, method).includes("user-activation"))
|
|
36
|
+
.map((method) => `${family}.${method}`)),
|
|
37
|
+
}),
|
|
27
38
|
themeVariables: Object.keys(config.theme.variables),
|
|
28
39
|
themeEvent: config.theme.event,
|
|
29
40
|
themeDocuments: config.theme.documents ?? "declared",
|
package/dist/shell/runtime.js
CHANGED
|
@@ -359,7 +359,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
359
359
|
// the person makes (their keys, their menu) copies their selection as the browser makes it: no
|
|
360
360
|
// copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
|
|
361
361
|
const noClipboard = function () {
|
|
362
|
-
return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? ": call copyText(text) from a click" : ""), "NotAllowedError"));
|
|
362
|
+
return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? (plan.runtime ? ': call (await porthole.use("clipboard")).copy(text) from a click' : ": call copyText(text) from a click") : ""), "NotAllowedError"));
|
|
363
363
|
};
|
|
364
364
|
if (typeof Clipboard === "function") {
|
|
365
365
|
for (const name of ["write", "writeText", "read", "readText"]) {
|
|
@@ -799,41 +799,6 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
799
799
|
return !(capability && capability.userActivation) || !activation || activation.isActive;
|
|
800
800
|
};
|
|
801
801
|
const refuse = (message) => Promise.reject(new Error(message));
|
|
802
|
-
if (declared("sendPrompt")) {
|
|
803
|
-
lock(window, "sendPrompt", (text) => {
|
|
804
|
-
if (!gestured("sendPrompt")) {
|
|
805
|
-
return refuse("sendPrompt needs a click: call it from a button's handler");
|
|
806
|
-
}
|
|
807
|
-
const words = String(text);
|
|
808
|
-
if (words.trim() === "" || words.length > plan.maxPromptChars) {
|
|
809
|
-
return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
|
|
810
|
-
}
|
|
811
|
-
return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
|
|
812
|
-
(result) => !(result && result.isError),
|
|
813
|
-
);
|
|
814
|
-
});
|
|
815
|
-
}
|
|
816
|
-
if (declared("copyText")) {
|
|
817
|
-
lock(window, "copyText", (text) => {
|
|
818
|
-
if (!gestured("copyText")) {
|
|
819
|
-
return refuse("copyText needs a click: call it from a button's handler");
|
|
820
|
-
}
|
|
821
|
-
const words = String(text);
|
|
822
|
-
if (words === "" || words.length > plan.maxCopyChars) {
|
|
823
|
-
return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
|
|
824
|
-
}
|
|
825
|
-
return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
|
|
826
|
-
});
|
|
827
|
-
}
|
|
828
|
-
if (declared("openLink")) {
|
|
829
|
-
lock(window, "openLink", (url) => {
|
|
830
|
-
if (!gestured("openLink")) {
|
|
831
|
-
return refuse("openLink needs a click: call it from a link's or button's handler");
|
|
832
|
-
}
|
|
833
|
-
return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
|
|
834
|
-
});
|
|
835
|
-
}
|
|
836
|
-
|
|
837
802
|
// Data (P079): readData reads a resource the host names, subscribeData follows one, through
|
|
838
803
|
// MCP's resources/* requests, which the host gates (the viewer's consent, a rate). A value is the
|
|
839
804
|
// first content's: JSON parsed when it says it is JSON, else its text.
|
|
@@ -857,9 +822,10 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
857
822
|
const later = (error) => setTimeout(() => {
|
|
858
823
|
throw error;
|
|
859
824
|
});
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
825
|
+
// Reads a resource (readData, the runtime's data.read).
|
|
826
|
+
const readValue = (uri) => request("resources/read", { uri: String(uri) }).then(valueOf);
|
|
827
|
+
// Follows one (subscribeData, the runtime's data.subscribe), where the config declares it.
|
|
828
|
+
let follow = null;
|
|
863
829
|
if (declared("subscribeData")) {
|
|
864
830
|
// One subscription per URI, however many follow it; a read at a time, one more if it changed
|
|
865
831
|
// meanwhile; a late follower gets the last value at once.
|
|
@@ -913,7 +879,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
913
879
|
refresh(entry);
|
|
914
880
|
}
|
|
915
881
|
};
|
|
916
|
-
|
|
882
|
+
follow = (uri, onData, onError) => {
|
|
917
883
|
if (typeof onData !== "function") {
|
|
918
884
|
throw new TypeError("subscribeData(uri, onData, onError): onData must be a function");
|
|
919
885
|
}
|
|
@@ -957,9 +923,19 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
957
923
|
request("resources/unsubscribe", { uri: key }).catch(() => {});
|
|
958
924
|
}
|
|
959
925
|
};
|
|
960
|
-
}
|
|
926
|
+
};
|
|
961
927
|
}
|
|
962
928
|
|
|
929
|
+
|
|
930
|
+
// The capability runtime's hooks (P085): the host's offer from the handshake (null: no host
|
|
931
|
+
// answered), and a watch's updates. The runtime, where the config has one, takes them.
|
|
932
|
+
let runtimeOffer = (_offer) => {};
|
|
933
|
+
let runtimeEvent = (_params) => {};
|
|
934
|
+
|
|
935
|
+
__LEGACY__
|
|
936
|
+
|
|
937
|
+
__RUNTIME__
|
|
938
|
+
|
|
963
939
|
window.addEventListener("error", (event) => {
|
|
964
940
|
const error = event.error;
|
|
965
941
|
const where = event.lineno ? " (line " + event.lineno + ")" : "";
|
|
@@ -1150,6 +1126,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1150
1126
|
resourceUpdated(params.uri);
|
|
1151
1127
|
}
|
|
1152
1128
|
break;
|
|
1129
|
+
case "porthole/event":
|
|
1130
|
+
runtimeEvent(params);
|
|
1131
|
+
break;
|
|
1153
1132
|
case "ui/resource-teardown":
|
|
1154
1133
|
case "ping":
|
|
1155
1134
|
if (data.id !== undefined) {
|
|
@@ -1177,7 +1156,12 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1177
1156
|
let initialized = false;
|
|
1178
1157
|
let tries = 0;
|
|
1179
1158
|
const initialize = () => {
|
|
1180
|
-
if (initialized
|
|
1159
|
+
if (initialized) {
|
|
1160
|
+
return;
|
|
1161
|
+
}
|
|
1162
|
+
if (tries >= 40) {
|
|
1163
|
+
// No host answered: the runtime has nothing to offer.
|
|
1164
|
+
runtimeOffer(null);
|
|
1181
1165
|
return;
|
|
1182
1166
|
}
|
|
1183
1167
|
tries += 1;
|
|
@@ -1190,6 +1174,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1190
1174
|
return;
|
|
1191
1175
|
}
|
|
1192
1176
|
initialized = true;
|
|
1177
|
+
const capabilities = result && result.hostCapabilities;
|
|
1178
|
+
const experimental = capabilities && capabilities.experimental;
|
|
1179
|
+
runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
|
|
1193
1180
|
applyTheme(result && result.hostContext);
|
|
1194
1181
|
notify("ui/notifications/initialized", {});
|
|
1195
1182
|
schedule();
|
|
@@ -0,0 +1,15 @@
|
|
|
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 declare const USE_RUNTIME: string;
|