@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,245 @@
|
|
|
1
|
+
import { atLeast, higher } from "./levels.js";
|
|
2
|
+
/**
|
|
3
|
+
* The capability runtime's contract (P085): what a page reaches through its one global,
|
|
4
|
+
* `porthole.use(name)`, by contract version. A version is pinned per artifact when it is published
|
|
5
|
+
* (`declareCapabilities`) and served as pinned, so a page keeps the API it was written against.
|
|
6
|
+
*
|
|
7
|
+
* Each runtime capability is a namespace of methods; each method is served by one of the config's
|
|
8
|
+
* host functions (PRINCIPLE 4: the config still says what the host offers, with its gates), needs
|
|
9
|
+
* a viewer level (P087), and is either a call or a watch (a subscription). A built-in is reachable
|
|
10
|
+
* by any page whose host offers it; every other one only by a page that declared it (P086).
|
|
11
|
+
*/
|
|
12
|
+
/** The contract versions this Porthole serves. */
|
|
13
|
+
export const RUNTIME_VERSIONS = ["1"];
|
|
14
|
+
/** The version a declaration is pinned to unless its author asks for another. */
|
|
15
|
+
export const RUNTIME_VERSION = "1";
|
|
16
|
+
export function isRuntimeVersion(value) {
|
|
17
|
+
return typeof value === "string" && RUNTIME_VERSIONS.includes(value);
|
|
18
|
+
}
|
|
19
|
+
/** The one global the shell defines for the runtime, with `use` its only member. */
|
|
20
|
+
export const RUNTIME_GLOBAL = "porthole";
|
|
21
|
+
/** Where the host's roster goes in the handshake: MCP Apps' experimental host capabilities. */
|
|
22
|
+
export const RUNTIME_EXPERIMENTAL_KEY = "porthole/runtime";
|
|
23
|
+
/** A runtime call (own-prefixed, P002): `{ capability, method, args }`. */
|
|
24
|
+
export const RUNTIME_CALL_METHOD = "porthole/call";
|
|
25
|
+
/** A watch's end, frame to host (a notification, never gated): `{ watch }`. */
|
|
26
|
+
export const RUNTIME_UNWATCH_METHOD = "porthole/unwatch";
|
|
27
|
+
/** A watch's update, host to frame: `{ watch, data }`. */
|
|
28
|
+
export const RUNTIME_EVENT_METHOD = "porthole/event";
|
|
29
|
+
const method = (serves, level, extra = {}) => ({
|
|
30
|
+
serves,
|
|
31
|
+
level,
|
|
32
|
+
floor: extra.floor ?? "view",
|
|
33
|
+
...(extra.watch === undefined ? {} : { watch: true }),
|
|
34
|
+
...(extra.gates === undefined ? {} : { gates: extra.gates }),
|
|
35
|
+
});
|
|
36
|
+
/** What changes the artifact for everyone: the person's click, then their yes. */
|
|
37
|
+
const CHANGES = ["user-activation", "confirm"];
|
|
38
|
+
/** Contract 1's capabilities, by the name a page passes to `use`. */
|
|
39
|
+
export const RUNTIME_CAPABILITIES = {
|
|
40
|
+
/** Who is viewing: `{ id, name, level }`, as the host says. Declared: the page learns who. */
|
|
41
|
+
user: { builtIn: false, methods: { get: method("user", "view") } },
|
|
42
|
+
/** Opens the host's comment composer at an anchor the page names. Write-only (P090). */
|
|
43
|
+
comments: { builtIn: true, methods: { open: method("comments", "view") } },
|
|
44
|
+
/** Copies text, done and shown by the host (P051, P052). */
|
|
45
|
+
clipboard: { builtIn: true, methods: { copy: method("copyText", "view") } },
|
|
46
|
+
/** Opens an http(s) link outside the frame. */
|
|
47
|
+
links: { builtIn: true, methods: { open: method("openLink", "view") } },
|
|
48
|
+
/** Hands the person a file to save. */
|
|
49
|
+
downloads: { builtIn: true, methods: { save: method("downloadFile", "view") } },
|
|
50
|
+
/** Sends text to the agent as the person's message. */
|
|
51
|
+
chat: { builtIn: false, methods: { send: method("sendPrompt", "interact") } },
|
|
52
|
+
/** The host's data (MCP resources and tools, P079): read, follow, call. */
|
|
53
|
+
data: {
|
|
54
|
+
builtIn: false,
|
|
55
|
+
methods: {
|
|
56
|
+
read: method("readData", "view"),
|
|
57
|
+
subscribe: method("subscribeData", "view", { watch: true }),
|
|
58
|
+
call: method("callTool", "interact"),
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
/** Context for the agent's next turns. */
|
|
62
|
+
context: { builtIn: false, methods: { set: method("setModelContext", "interact") } },
|
|
63
|
+
/** This artifact itself: its current version, and a new version of it (P088). */
|
|
64
|
+
artifact: {
|
|
65
|
+
builtIn: false,
|
|
66
|
+
methods: {
|
|
67
|
+
get: method("artifact", "view"),
|
|
68
|
+
publish: method("artifact", "admin", { floor: "admin", gates: CHANGES }),
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
/** The artifact's asset library, served at `/_blob/<id>` (P089). */
|
|
72
|
+
assets: {
|
|
73
|
+
builtIn: false,
|
|
74
|
+
methods: {
|
|
75
|
+
list: method("assets", "view"),
|
|
76
|
+
// In the frame alone (P091): the address that loads an asset in this page now.
|
|
77
|
+
url: method("assets", "view"),
|
|
78
|
+
// An upload's own gate depends on whether what is uploaded may run (`methodGates`).
|
|
79
|
+
upload: method("assets", "admin", { floor: "interact" }),
|
|
80
|
+
delete: method("assets", "admin", { floor: "admin", gates: CHANGES }),
|
|
81
|
+
},
|
|
82
|
+
},
|
|
83
|
+
/** The artifact's shared document store (P088). */
|
|
84
|
+
db: {
|
|
85
|
+
builtIn: false,
|
|
86
|
+
methods: {
|
|
87
|
+
get: method("db", "view"),
|
|
88
|
+
query: method("db", "view"),
|
|
89
|
+
watch: method("db", "view", { watch: true }),
|
|
90
|
+
set: method("db", "interact", { floor: "interact" }),
|
|
91
|
+
update: method("db", "interact", { floor: "interact" }),
|
|
92
|
+
delete: method("db", "interact", { floor: "interact" }),
|
|
93
|
+
batch: method("db", "interact", { floor: "interact" }),
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
};
|
|
97
|
+
export const RUNTIME_CAPABILITY_NAMES = Object.keys(RUNTIME_CAPABILITIES);
|
|
98
|
+
export function isRuntimeCapabilityName(value) {
|
|
99
|
+
return typeof value === "string" && Object.hasOwn(RUNTIME_CAPABILITIES, value);
|
|
100
|
+
}
|
|
101
|
+
/** A runtime capability's spec, as the general shape. */
|
|
102
|
+
export function runtimeCapability(name) {
|
|
103
|
+
return RUNTIME_CAPABILITIES[name];
|
|
104
|
+
}
|
|
105
|
+
/** The host functions the runtime added in contract 1 (P085): the config needs `runtime` for them. */
|
|
106
|
+
export const RUNTIME_HOST_FUNCTIONS = [
|
|
107
|
+
"user",
|
|
108
|
+
"comments",
|
|
109
|
+
"artifact",
|
|
110
|
+
"assets",
|
|
111
|
+
"db",
|
|
112
|
+
];
|
|
113
|
+
/**
|
|
114
|
+
* Where a host function sits in the runtime: its capability and the methods it serves. Null for
|
|
115
|
+
* the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
|
|
116
|
+
*/
|
|
117
|
+
export function familyOf(serves) {
|
|
118
|
+
for (const name of RUNTIME_CAPABILITY_NAMES) {
|
|
119
|
+
const methods = Object.entries(runtimeCapability(name).methods)
|
|
120
|
+
.filter(([, each]) => each.serves === serves)
|
|
121
|
+
.map(([each]) => each);
|
|
122
|
+
if (methods.length > 0) {
|
|
123
|
+
return { name, methods };
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
return null;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* The runtime method a host function's validated call is: the `op` of one that serves several
|
|
130
|
+
* (`artifact`, `assets`, `db`), else its one method.
|
|
131
|
+
*/
|
|
132
|
+
export function methodOf(serves, args) {
|
|
133
|
+
const family = familyOf(serves);
|
|
134
|
+
if (family === null) {
|
|
135
|
+
return null;
|
|
136
|
+
}
|
|
137
|
+
if (family.methods.length === 1) {
|
|
138
|
+
return family.methods[0] ?? null;
|
|
139
|
+
}
|
|
140
|
+
const op = args !== null && typeof args === "object" ? args.op : undefined;
|
|
141
|
+
return typeof op === "string" && family.methods.includes(op) ? op : null;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* The runtime methods a validated call runs, each as often as it runs it: its own, and for a db
|
|
145
|
+
* batch each of its writes' (`set`, `update`, `delete`), for a db watch the read it repeats (`get`
|
|
146
|
+
* for a document, `query` for a collection). Each one's level and gates apply to the call (P091
|
|
147
|
+
* item 4 for levels, P094 for gates): a batch is its writes, a watch its read.
|
|
148
|
+
*/
|
|
149
|
+
export function methodsOfCall(serves, args) {
|
|
150
|
+
const own = methodOf(serves, args);
|
|
151
|
+
if (own === null) {
|
|
152
|
+
return [];
|
|
153
|
+
}
|
|
154
|
+
if (serves !== "db") {
|
|
155
|
+
return [own];
|
|
156
|
+
}
|
|
157
|
+
const request = args;
|
|
158
|
+
if (request.op === "batch") {
|
|
159
|
+
return [own, ...(request.writes ?? []).map((write) => write.op)];
|
|
160
|
+
}
|
|
161
|
+
if (request.op === "watch") {
|
|
162
|
+
return [own, (request.path ?? "").split("/").length % 2 === 0 ? "get" : "query"];
|
|
163
|
+
}
|
|
164
|
+
return [own];
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Whether a config's asset uploads are its admins' alone (`assets.upload` at admin or above,
|
|
168
|
+
* P089): only then may scripts and styles an admin uploaded run from the library. Never where
|
|
169
|
+
* the config serves no assets (P103: a config that dropped them runs nothing of its library).
|
|
170
|
+
*/
|
|
171
|
+
export function assetCodeRuns(config) {
|
|
172
|
+
if (config.capabilities.assets === undefined) {
|
|
173
|
+
return false;
|
|
174
|
+
}
|
|
175
|
+
const level = methodLevel(config, "assets", "upload");
|
|
176
|
+
return level !== null && atLeast(level, "admin");
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* A runtime method's own gates (after the review): the config's (`CapabilityConfig.methodGates`),
|
|
180
|
+
* else the contract's; an upload where uploaded code may run is confirmed (P089).
|
|
181
|
+
*/
|
|
182
|
+
export function methodGates(config, family, name) {
|
|
183
|
+
const methods = runtimeCapability(family).methods;
|
|
184
|
+
const spec = Object.hasOwn(methods, name) ? methods[name] : undefined;
|
|
185
|
+
if (spec === undefined) {
|
|
186
|
+
return [];
|
|
187
|
+
}
|
|
188
|
+
const own = config.capabilities[spec.serves]?.methodGates;
|
|
189
|
+
if (own !== undefined && Object.hasOwn(own, name)) {
|
|
190
|
+
return own[name] ?? [];
|
|
191
|
+
}
|
|
192
|
+
if (family === "assets" && name === "upload") {
|
|
193
|
+
return assetCodeRuns(config) ? ["confirm"] : [];
|
|
194
|
+
}
|
|
195
|
+
return spec.gates ?? [];
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* The least level that may call `family.method` (P087): the contract's, or the host's config
|
|
199
|
+
* (`CapabilityConfig.levels`, no lower than the floor), raised by the page's declaration.
|
|
200
|
+
*/
|
|
201
|
+
export function methodLevel(config, family, name, declared) {
|
|
202
|
+
const methods = runtimeCapability(family).methods;
|
|
203
|
+
const spec = Object.hasOwn(methods, name) ? methods[name] : undefined;
|
|
204
|
+
if (spec === undefined) {
|
|
205
|
+
return null;
|
|
206
|
+
}
|
|
207
|
+
const host = config.capabilities[spec.serves]?.levels?.[name];
|
|
208
|
+
const base = host === undefined ? spec.level : higher(host, spec.floor);
|
|
209
|
+
// The page's own names only (P093): a declaration a host passes unchecked may be a plain object.
|
|
210
|
+
const levels = declared?.levels;
|
|
211
|
+
const page = levels !== undefined && Object.hasOwn(levels, name) ? levels[name] : undefined;
|
|
212
|
+
return page === undefined ? base : higher(base, page);
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* What the host offers a display (P085): each runtime capability the config serves at least one
|
|
216
|
+
* method of (with those methods), reachable when it is built in or the page declared it. Without
|
|
217
|
+
* `config.runtime`, nothing: the display is 0.6's. `declared` is the page's declaration's names;
|
|
218
|
+
* absent, the page declared nothing (built-ins only).
|
|
219
|
+
*/
|
|
220
|
+
export function rosterOf(config, declared) {
|
|
221
|
+
if (config.runtime === undefined) {
|
|
222
|
+
return {};
|
|
223
|
+
}
|
|
224
|
+
const roster = {};
|
|
225
|
+
for (const name of RUNTIME_CAPABILITY_NAMES) {
|
|
226
|
+
const spec = runtimeCapability(name);
|
|
227
|
+
if (!spec.builtIn && !(declared ?? []).includes(name)) {
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
const methods = Object.entries(spec.methods)
|
|
231
|
+
.filter(([, each]) => config.capabilities[each.serves] !== undefined)
|
|
232
|
+
.map(([each]) => each);
|
|
233
|
+
if (methods.length > 0) {
|
|
234
|
+
roster[name] = methods;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
return roster;
|
|
238
|
+
}
|
|
239
|
+
/** The capabilities a config offers to pages that declare them (for the manual and `declareCapabilities`). */
|
|
240
|
+
export function offeredCapabilities(config) {
|
|
241
|
+
if (config.runtime === undefined) {
|
|
242
|
+
return [];
|
|
243
|
+
}
|
|
244
|
+
return RUNTIME_CAPABILITY_NAMES.filter((name) => Object.values(runtimeCapability(name).methods).some((each) => config.capabilities[each.serves] !== undefined));
|
|
245
|
+
}
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import { type ViewerInfo, type ViewerLevel } from "./levels.ts";
|
|
2
|
+
import { isDbSegment } from "./segments.ts";
|
|
3
|
+
export { isDbSegment };
|
|
4
|
+
/**
|
|
5
|
+
* The `db` capability's contract (P088): a document store the host keeps for an artifact, which
|
|
6
|
+
* its page reads and writes as the person viewing it. Porthole checks what crosses the frame (the
|
|
7
|
+
* shape, the sizes, the paths), resolves `me`, keeps a viewer to their own per-user data
|
|
8
|
+
* (`data/users/<id>`), and applies the page's per-level rules; the host stores, versions and
|
|
9
|
+
* evaluates them again on its own side (`dbAccess`), since its API is the wall for its data.
|
|
10
|
+
*
|
|
11
|
+
* Paths are slash-separated: a collection is an odd number of segments (`votes`,
|
|
12
|
+
* `rooms/r1/messages`), a document an even number (`votes/ada`). Every write to a document that
|
|
13
|
+
* exists names the version it read (`ifVersion`); a mismatch is a `conflict`.
|
|
14
|
+
*/
|
|
15
|
+
export declare const DB_LIMITS: {
|
|
16
|
+
/** The most a document's data holds, JSON bytes. */
|
|
17
|
+
readonly maxDocBytes: 1048576;
|
|
18
|
+
/** The most writes one batch holds, and their bytes together. */
|
|
19
|
+
readonly maxBatchWrites: 50;
|
|
20
|
+
readonly maxBatchBytes: 1048576;
|
|
21
|
+
/** The most documents one query answers. */
|
|
22
|
+
readonly maxQueryLimit: 500;
|
|
23
|
+
readonly maxWhere: 10;
|
|
24
|
+
/** The most values an `in` holds. */
|
|
25
|
+
readonly maxIn: 30;
|
|
26
|
+
/** The most segments a path holds (a document: 16; a collection: 15). */
|
|
27
|
+
readonly maxSegments: 16;
|
|
28
|
+
/** The deepest a document's data nests. */
|
|
29
|
+
readonly maxDepth: 32;
|
|
30
|
+
/** The most watches one frame keeps at once. */
|
|
31
|
+
readonly maxWatches: 50;
|
|
32
|
+
/** The most values (objects, arrays, scalars) one document holds, and one batch. */
|
|
33
|
+
readonly maxNodes: 100000;
|
|
34
|
+
/** The most a `where` operand holds: values, and JSON bytes. */
|
|
35
|
+
readonly maxOperandNodes: 1000;
|
|
36
|
+
readonly maxOperandBytes: 16384;
|
|
37
|
+
};
|
|
38
|
+
/** The per-user subtree: `data/users/<id>/…`, the viewer's own; `me` names the viewer. */
|
|
39
|
+
export declare const DB_USERS_PREFIX = "data/users/";
|
|
40
|
+
/** A path's segments, or null for one that names nothing (empty, dot segments, odd characters). */
|
|
41
|
+
export declare function dbSegments(path: unknown): string[] | null;
|
|
42
|
+
/** Whether `path` names a document (`even`) or a collection (`odd`). */
|
|
43
|
+
export declare function dbPathKind(segments: readonly string[]): "doc" | "collection";
|
|
44
|
+
/** A JSON value Porthole passes on: plain data, no cycles, no deeper than `maxDepth`. */
|
|
45
|
+
export type DbValue = null | boolean | number | string | readonly DbValue[] | {
|
|
46
|
+
readonly [field: string]: DbValue;
|
|
47
|
+
};
|
|
48
|
+
export type DbData = {
|
|
49
|
+
readonly [field: string]: DbValue;
|
|
50
|
+
};
|
|
51
|
+
/** Whether `value` is plain JSON within `nodes` nodes (a document's, a `where` operand's). */
|
|
52
|
+
export declare function isPlainJson(value: unknown, nodes?: number): boolean;
|
|
53
|
+
/**
|
|
54
|
+
* The bytes checked plain JSON takes (`plainJson` first: no cycles, bounded nodes and depth), or
|
|
55
|
+
* `max + 1` once it surely takes more: written out only within its limit (P095: a string of
|
|
56
|
+
* control characters is six times its length as JSON, and could pass a string's longest).
|
|
57
|
+
*/
|
|
58
|
+
export declare const jsonBytes: (value: unknown, max: number) => number;
|
|
59
|
+
export type DbWhereOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "array-contains";
|
|
60
|
+
export type DbWhere = readonly [field: string, op: DbWhereOp, value: DbValue];
|
|
61
|
+
export type DbWrite = {
|
|
62
|
+
readonly op: "set";
|
|
63
|
+
readonly path: string;
|
|
64
|
+
readonly data: DbData;
|
|
65
|
+
/** The version read (0: it must not exist yet). Needed to replace one that exists. */
|
|
66
|
+
readonly ifVersion?: number;
|
|
67
|
+
} | {
|
|
68
|
+
readonly op: "update";
|
|
69
|
+
readonly path: string;
|
|
70
|
+
/** Fields merged over the document's (top level). */
|
|
71
|
+
readonly data: DbData;
|
|
72
|
+
readonly ifVersion?: number;
|
|
73
|
+
} | {
|
|
74
|
+
readonly op: "delete";
|
|
75
|
+
readonly path: string;
|
|
76
|
+
readonly ifVersion?: number;
|
|
77
|
+
};
|
|
78
|
+
/** A `db` call, as the host's handler gets it (paths checked, `me` resolved). */
|
|
79
|
+
export type DbRequest = {
|
|
80
|
+
readonly op: "get";
|
|
81
|
+
readonly path: string;
|
|
82
|
+
} | DbWrite | {
|
|
83
|
+
readonly op: "query";
|
|
84
|
+
readonly collection: string;
|
|
85
|
+
readonly where?: readonly DbWhere[];
|
|
86
|
+
readonly orderBy?: {
|
|
87
|
+
readonly field: string;
|
|
88
|
+
readonly direction: "asc" | "desc";
|
|
89
|
+
};
|
|
90
|
+
readonly limit?: number;
|
|
91
|
+
} | {
|
|
92
|
+
readonly op: "batch";
|
|
93
|
+
readonly writes: readonly DbWrite[];
|
|
94
|
+
}
|
|
95
|
+
/** A document or a collection, kept current: the handler calls `changed` with each new state. */
|
|
96
|
+
| {
|
|
97
|
+
readonly op: "watch";
|
|
98
|
+
readonly path: string;
|
|
99
|
+
};
|
|
100
|
+
/** A document as the host answers it. `version` counts its writes (1 for the first). */
|
|
101
|
+
export interface DbSnapshot {
|
|
102
|
+
readonly path: string;
|
|
103
|
+
readonly id: string;
|
|
104
|
+
readonly exists: boolean;
|
|
105
|
+
readonly version: number;
|
|
106
|
+
readonly data?: DbData;
|
|
107
|
+
}
|
|
108
|
+
/** What each op answers. */
|
|
109
|
+
export type DbResult =
|
|
110
|
+
/** get */
|
|
111
|
+
DbSnapshot
|
|
112
|
+
/** set, update */
|
|
113
|
+
| {
|
|
114
|
+
readonly version: number;
|
|
115
|
+
}
|
|
116
|
+
/** query, a collection's watch */
|
|
117
|
+
| {
|
|
118
|
+
readonly docs: readonly DbSnapshot[];
|
|
119
|
+
}
|
|
120
|
+
/** batch: each write's new version (null for a delete) */
|
|
121
|
+
| {
|
|
122
|
+
readonly versions: readonly (number | null)[];
|
|
123
|
+
}
|
|
124
|
+
/** delete, watch */
|
|
125
|
+
| undefined;
|
|
126
|
+
type Parsed<T> = T | "too_large" | null;
|
|
127
|
+
/** A `db` call's arguments as content sent them, checked: null (malformed), "too_large", or the call. */
|
|
128
|
+
export declare function parseDbRequest(args: unknown): Parsed<DbRequest>;
|
|
129
|
+
/**
|
|
130
|
+
* The page's rules for its data (its `db` declaration, P086): by top-level collection (or `*`),
|
|
131
|
+
* the least level that may read and write it. They only raise the contract's (read: view, write:
|
|
132
|
+
* interact); the host evaluates them again on its side (`dbAccess`).
|
|
133
|
+
*/
|
|
134
|
+
export type DbRules = Readonly<Record<string, DbRule>>;
|
|
135
|
+
/** One collection's rule: the least level that may read it, and write it (absent: the contract's). */
|
|
136
|
+
export interface DbRule {
|
|
137
|
+
readonly read?: ViewerLevel;
|
|
138
|
+
readonly write?: ViewerLevel;
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* The most collections a page's rules name (P086). At publish, `DB_MAX_RULES`; where a
|
|
142
|
+
* declaration is shown (a mount, `intersectDeclarations`), an intersection of two: twice that, and
|
|
143
|
+
* `*` (P093, after its review).
|
|
144
|
+
*/
|
|
145
|
+
export declare const DB_MAX_RULES = 100;
|
|
146
|
+
export declare const DB_MAX_SHOWN_RULES: number;
|
|
147
|
+
/** Where a declaration is checked: at publish, or where it is shown (a mount, an intersection). */
|
|
148
|
+
export type DeclarationStage = "publish" | "shown";
|
|
149
|
+
/** A collection's name, ASCII case folded: a store that folds case keeps `Votes` where `votes` is. */
|
|
150
|
+
export declare const foldCollection: (name: string) => string;
|
|
151
|
+
/** The level a rule asks to read or write (absent: the contract's, read view and write interact). */
|
|
152
|
+
export declare function dbRuleLevel(rule: DbRule | undefined, write: boolean): ViewerLevel;
|
|
153
|
+
/** The stricter of two rules, read and write each (absent: the contract's level). */
|
|
154
|
+
export declare function stricterDbRule(x: DbRule | undefined, y: DbRule | undefined): DbRule;
|
|
155
|
+
/**
|
|
156
|
+
* The rule a top-level collection is under (P086, P093): the rule object the rules give its exact
|
|
157
|
+
* name, else `*`'s, whole; never field by field (a collection's `{}` is the contract's levels,
|
|
158
|
+
* whatever `*` says). Then made stricter by every rule that names it in another ASCII case (a
|
|
159
|
+
* store that folds case keeps `Votes` where `votes` is): never looser than the exact name's
|
|
160
|
+
* lookup, and the same where nothing names it in another case. Own names only: a collection
|
|
161
|
+
* named `constructor` or `__proto__` is no rule unless the rules name it (P091). `dbAccess` and
|
|
162
|
+
* `intersectDeclarations` both read rules through this.
|
|
163
|
+
*/
|
|
164
|
+
export declare function dbRuleOf(rules: DbRules | undefined, collection: string): DbRule | undefined;
|
|
165
|
+
/**
|
|
166
|
+
* A rules object's problem, or null. At publish (the default) at most `DB_MAX_RULES` names, none
|
|
167
|
+
* two that differ only in case (P093); where shown, an intersection's `DB_MAX_SHOWN_RULES`, and
|
|
168
|
+
* names in more than one case as a page from before P093 may have them.
|
|
169
|
+
*/
|
|
170
|
+
export declare function dbRulesProblem(value: unknown, stage?: DeclarationStage): string | null;
|
|
171
|
+
/**
|
|
172
|
+
* Whether `viewer` may make `request` under `rules` (P088), and the call with `me` resolved:
|
|
173
|
+
* someone else's per-user data is refused at every level, and so is any path under `data` that
|
|
174
|
+
* isn't `data/users/<own id>/…`; then each path's rule. The bridge applies it before the host's
|
|
175
|
+
* handler; a host applies it again in its own API (its data's wall).
|
|
176
|
+
*/
|
|
177
|
+
export declare function dbAccess(request: DbRequest, viewer: ViewerInfo | undefined, rules?: DbRules): {
|
|
178
|
+
readonly ok: true;
|
|
179
|
+
readonly request: DbRequest;
|
|
180
|
+
} | {
|
|
181
|
+
readonly ok: false;
|
|
182
|
+
};
|
|
183
|
+
/**
|
|
184
|
+
* A `db` answer as content gets it (P088, after the review): every path in the viewer's own tree
|
|
185
|
+
* says `data/users/me`, never their id, so a page that didn't declare `user` doesn't learn who is
|
|
186
|
+
* viewing from its own data's paths. Snapshots and `{ docs }`; anything else as it is.
|
|
187
|
+
*/
|
|
188
|
+
export declare function withMe(value: unknown, viewer: ViewerInfo | undefined): unknown;
|