@botiverse/porthole 0.5.1 → 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 +41 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +208 -13
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- 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 +19 -3
- package/dist/check/check.js +55 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +31 -12
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +27 -3
- package/dist/compile/policy.d.ts +34 -0
- package/dist/compile/policy.js +74 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +32 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +74 -5
- 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/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -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 +44 -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 +45 -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 +13 -4
- package/dist/index.js +16 -3
- 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/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +52 -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 +57 -0
- package/dist/server/files.js +338 -0
- package/dist/server/host.d.ts +44 -2
- package/dist/server/host.js +42 -2
- package/dist/server/index.d.ts +5 -2
- package/dist/server/index.js +5 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -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 +468 -24
- package/dist/server/types.d.ts +118 -5
- package/dist/shell/document.d.ts +27 -0
- package/dist/shell/document.js +46 -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.d.ts +2 -1
- package/dist/shell/runtime.js +114 -46
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +142 -5
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +716 -7
- package/docs/DESIGN.md +97 -3
- package/package.json +3 -1
- package/src/bridge/bridge.ts +281 -17
- package/src/bridge/navigation.ts +12 -0
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +100 -14
- package/src/check/files.ts +384 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +33 -12
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +52 -3
- package/src/compile/policy.ts +92 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +32 -0
- package/src/config/validate.ts +107 -5
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +78 -52
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +55 -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 +121 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +56 -2
- 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 +425 -0
- package/src/server/host.ts +84 -3
- package/src/server/index.ts +22 -0
- package/src/server/keys.ts +53 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +565 -26
- package/src/server/types.ts +124 -4
- package/src/shell/document.ts +74 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +114 -46
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
import { RUNTIME_CAPABILITY_NAMES, RUNTIME_VERSION, isRuntimeCapabilityName, isRuntimeVersion, offeredCapabilities, runtimeCapability, } from "./contract.js";
|
|
2
|
+
import { dbRulesProblem } from "./db.js";
|
|
3
|
+
import { higher, isViewerLevel } from "./levels.js";
|
|
4
|
+
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
5
|
+
const KEYS = {
|
|
6
|
+
data: ["levels", "resources", "tools"],
|
|
7
|
+
db: ["levels", "rules"],
|
|
8
|
+
};
|
|
9
|
+
const names = (values, path, problems) => {
|
|
10
|
+
if (!Array.isArray(values) ||
|
|
11
|
+
values.length > 200 ||
|
|
12
|
+
values.some((each) => typeof each !== "string" ||
|
|
13
|
+
each === "" ||
|
|
14
|
+
each.length > 512 ||
|
|
15
|
+
/\p{Cc}/u.test(each) ||
|
|
16
|
+
// A `*` only at the end: a prefix.
|
|
17
|
+
(each.includes("*") && each.indexOf("*") !== each.length - 1))) {
|
|
18
|
+
problems.push({
|
|
19
|
+
path,
|
|
20
|
+
message: "must be a list of names (at most 200), each exact or a prefix ending in *",
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* The problems with a declaration, against the host's offer (`config`): each name one the
|
|
26
|
+
* runtime knows, the config offers and isn't built in; each config of its own shape. Empty: fine.
|
|
27
|
+
*/
|
|
28
|
+
export function declarationProblems(given, config, runtime = RUNTIME_VERSION) {
|
|
29
|
+
const problems = [];
|
|
30
|
+
if (!isRuntimeVersion(runtime)) {
|
|
31
|
+
return [{ path: "runtime", message: `is not a runtime version Porthole serves` }];
|
|
32
|
+
}
|
|
33
|
+
if (!isRecord(given)) {
|
|
34
|
+
return [{ path: "capabilities", message: "must be an object: { name: config }" }];
|
|
35
|
+
}
|
|
36
|
+
const offered = offeredCapabilities(config);
|
|
37
|
+
for (const [name, value] of Object.entries(given)) {
|
|
38
|
+
const path = `capabilities.${name}`;
|
|
39
|
+
if (!isRuntimeCapabilityName(name)) {
|
|
40
|
+
problems.push({
|
|
41
|
+
path,
|
|
42
|
+
message: `is not a capability (${RUNTIME_CAPABILITY_NAMES.filter((each) => !runtimeCapability(each).builtIn).join(", ")})`,
|
|
43
|
+
});
|
|
44
|
+
continue;
|
|
45
|
+
}
|
|
46
|
+
const spec = runtimeCapability(name);
|
|
47
|
+
if (spec.builtIn) {
|
|
48
|
+
problems.push({ path, message: "is built in: use it without declaring it" });
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
if (!offered.includes(name)) {
|
|
52
|
+
problems.push({ path, message: "isn't offered here" });
|
|
53
|
+
continue;
|
|
54
|
+
}
|
|
55
|
+
if (!isRecord(value)) {
|
|
56
|
+
problems.push({ path, message: "must be an object ({} for none of its own)" });
|
|
57
|
+
continue;
|
|
58
|
+
}
|
|
59
|
+
const allowed = KEYS[name] ?? ["levels"];
|
|
60
|
+
for (const key of Object.keys(value)) {
|
|
61
|
+
if (!allowed.includes(key)) {
|
|
62
|
+
problems.push({ path: `${path}.${key}`, message: `is not a field of ${name}'s config` });
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
if (value.levels !== undefined) {
|
|
66
|
+
if (!isRecord(value.levels)) {
|
|
67
|
+
problems.push({ path: `${path}.levels`, message: "must be an object of levels by method" });
|
|
68
|
+
}
|
|
69
|
+
else {
|
|
70
|
+
for (const [method, level] of Object.entries(value.levels)) {
|
|
71
|
+
if (!Object.hasOwn(spec.methods, method)) {
|
|
72
|
+
problems.push({
|
|
73
|
+
path: `${path}.levels.${method}`,
|
|
74
|
+
message: `is not a method of ${name} (${Object.keys(spec.methods).join(", ")})`,
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
else if (!isViewerLevel(level)) {
|
|
78
|
+
problems.push({
|
|
79
|
+
path: `${path}.levels.${method}`,
|
|
80
|
+
message: "must be view, interact, admin or owner",
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
if (name === "data") {
|
|
87
|
+
if (value.resources !== undefined) {
|
|
88
|
+
names(value.resources, `${path}.resources`, problems);
|
|
89
|
+
}
|
|
90
|
+
if (value.tools !== undefined) {
|
|
91
|
+
names(value.tools, `${path}.tools`, problems);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
if (name === "db" && value.rules !== undefined) {
|
|
95
|
+
const problem = dbRulesProblem(value.rules);
|
|
96
|
+
if (problem !== null) {
|
|
97
|
+
problems.push({ path: `${path}.rules`, message: problem });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return problems;
|
|
102
|
+
}
|
|
103
|
+
/** A declaration checked (a host's stored one, given to `mount`); throws a `TypeError` naming its problems. */
|
|
104
|
+
export function checkDeclaration(given, config) {
|
|
105
|
+
if (!isRecord(given)) {
|
|
106
|
+
throw new TypeError("A declaration is { capabilities, runtime }");
|
|
107
|
+
}
|
|
108
|
+
const runtime = given.runtime;
|
|
109
|
+
if (!isRuntimeVersion(runtime)) {
|
|
110
|
+
throw new TypeError(`A declaration's runtime ${JSON.stringify(runtime)} is not one this Porthole serves`);
|
|
111
|
+
}
|
|
112
|
+
const problems = declarationProblems(given.capabilities, config, runtime);
|
|
113
|
+
if (problems.length > 0) {
|
|
114
|
+
throw new TypeError(`The declaration doesn't fit this config: ${problems.map((each) => `${each.path} ${each.message}`).join("; ")}`);
|
|
115
|
+
}
|
|
116
|
+
return { capabilities: copied(given.capabilities), runtime };
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* A declaration's own copy, every object without a prototype (after the review): a rule or a
|
|
120
|
+
* level looked up by a name like `constructor` finds nothing but what the page wrote.
|
|
121
|
+
*/
|
|
122
|
+
function copied(value) {
|
|
123
|
+
if (Array.isArray(value)) {
|
|
124
|
+
return value.map(copied);
|
|
125
|
+
}
|
|
126
|
+
if (value === null || typeof value !== "object") {
|
|
127
|
+
return value;
|
|
128
|
+
}
|
|
129
|
+
const out = Object.create(null);
|
|
130
|
+
for (const [key, each] of Object.entries(value)) {
|
|
131
|
+
out[key] = copied(each);
|
|
132
|
+
}
|
|
133
|
+
return out;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* At publish (P086): the declaration a new version leaves the artifact with.
|
|
137
|
+
* - `given` undefined: the stored one, unchanged (its pin too); none stored: an empty one.
|
|
138
|
+
* - `given` `{}`: cleared.
|
|
139
|
+
* - `given` non-empty: it replaces the stored one whole (anything not restated is revoked).
|
|
140
|
+
* The pin moves only when the author asks (`runtime`). Checked against the host's offer.
|
|
141
|
+
*/
|
|
142
|
+
export function declareCapabilities(options) {
|
|
143
|
+
const { stored, given, config } = options;
|
|
144
|
+
if (options.runtime !== undefined && !isRuntimeVersion(options.runtime)) {
|
|
145
|
+
return {
|
|
146
|
+
ok: false,
|
|
147
|
+
problems: [{ path: "runtime", message: "is not a runtime version Porthole serves" }],
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
const runtime = options.runtime ?? stored?.runtime ?? RUNTIME_VERSION;
|
|
151
|
+
if (given === undefined) {
|
|
152
|
+
const declaration = stored ?? { capabilities: {}, runtime };
|
|
153
|
+
const pinned = { capabilities: declaration.capabilities, runtime };
|
|
154
|
+
// A stored declaration still fits the host's offer (a host may have narrowed its config).
|
|
155
|
+
const problems = declarationProblems(pinned.capabilities, config, runtime);
|
|
156
|
+
return problems.length > 0
|
|
157
|
+
? { ok: false, problems }
|
|
158
|
+
: {
|
|
159
|
+
ok: true,
|
|
160
|
+
declaration: pinned,
|
|
161
|
+
changed: stored === undefined || stored === null || stored.runtime !== runtime,
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
const problems = declarationProblems(given, config, runtime);
|
|
165
|
+
if (problems.length > 0) {
|
|
166
|
+
return { ok: false, problems };
|
|
167
|
+
}
|
|
168
|
+
const declaration = { capabilities: given, runtime };
|
|
169
|
+
return {
|
|
170
|
+
ok: true,
|
|
171
|
+
declaration,
|
|
172
|
+
changed: stored === undefined ||
|
|
173
|
+
stored === null ||
|
|
174
|
+
stored.runtime !== runtime ||
|
|
175
|
+
JSON.stringify(stored.capabilities) !== JSON.stringify(declaration.capabilities),
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* A name a prefix can't vouch for (after the review): a dot segment, or one written with an
|
|
180
|
+
* escape or a backslash, may resolve outside the prefix (`app://tasks/../secrets`).
|
|
181
|
+
*/
|
|
182
|
+
const ESCAPES_PREFIX = /(^|[/\\])\.{1,2}([/\\?#]|$)|%2e|%2f|%5c|\\/iu;
|
|
183
|
+
/** Whether `name` matches a declared list's entry (exact, or a prefix ending in `*`). */
|
|
184
|
+
export function declaredMatch(list, name) {
|
|
185
|
+
return (list === undefined ||
|
|
186
|
+
list.some((each) => each.endsWith("*")
|
|
187
|
+
? name.startsWith(each.slice(0, -1)) && !ESCAPES_PREFIX.test(name)
|
|
188
|
+
: each === name));
|
|
189
|
+
}
|
|
190
|
+
/** The stricter of two declared level maps. */
|
|
191
|
+
function stricterLevels(a, b) {
|
|
192
|
+
if (a === undefined || b === undefined) {
|
|
193
|
+
return a ?? b;
|
|
194
|
+
}
|
|
195
|
+
const out = { ...a };
|
|
196
|
+
for (const [method, level] of Object.entries(b)) {
|
|
197
|
+
const other = Object.hasOwn(out, method) ? out[method] : undefined;
|
|
198
|
+
out[method] = other === undefined ? level : higher(other, level);
|
|
199
|
+
}
|
|
200
|
+
return out;
|
|
201
|
+
}
|
|
202
|
+
/** The names both lists admit (absent: everything). */
|
|
203
|
+
function bothNames(a, b) {
|
|
204
|
+
if (a === undefined || b === undefined) {
|
|
205
|
+
return a ?? b;
|
|
206
|
+
}
|
|
207
|
+
return [
|
|
208
|
+
...new Set([
|
|
209
|
+
...a.filter((each) => declaredMatch(b, each)),
|
|
210
|
+
...b.filter((each) => declaredMatch(a, each)),
|
|
211
|
+
]),
|
|
212
|
+
];
|
|
213
|
+
}
|
|
214
|
+
/** The stricter of two pages' rules, by collection. */
|
|
215
|
+
function stricterRules(a, b) {
|
|
216
|
+
if (a === undefined || b === undefined) {
|
|
217
|
+
return a ?? b;
|
|
218
|
+
}
|
|
219
|
+
const out = {};
|
|
220
|
+
for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
|
|
221
|
+
const x = Object.hasOwn(a, key) ? a[key] : undefined;
|
|
222
|
+
const y = Object.hasOwn(b, key) ? b[key] : undefined;
|
|
223
|
+
const read = x?.read === undefined ? y?.read : y?.read === undefined ? x.read : higher(x.read, y.read);
|
|
224
|
+
const write = x?.write === undefined
|
|
225
|
+
? y?.write
|
|
226
|
+
: y?.write === undefined
|
|
227
|
+
? x.write
|
|
228
|
+
: higher(x.write, y.write);
|
|
229
|
+
out[key] = {
|
|
230
|
+
...(read === undefined ? {} : { read }),
|
|
231
|
+
...(write === undefined ? {} : { write }),
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
return out;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* What a version may do when it is shown (after the review): what it declared when it was
|
|
238
|
+
* published AND what the artifact declares now. A host stores each version's declaration with
|
|
239
|
+
* it (`declareCapabilities` at its publish) and mounts a version with this, so an old version
|
|
240
|
+
* never keeps what the artifact has since revoked, nor gains what it declared later. Each
|
|
241
|
+
* capability only where both declare it, at the stricter levels, the narrower `data` names and
|
|
242
|
+
* the stricter `db` rules; the version's own pinned runtime.
|
|
243
|
+
*/
|
|
244
|
+
export function intersectDeclarations(version, current) {
|
|
245
|
+
const capabilities = {};
|
|
246
|
+
const a = version.capabilities;
|
|
247
|
+
const b = current.capabilities;
|
|
248
|
+
for (const name of Object.keys(a)) {
|
|
249
|
+
if (!Object.hasOwn(b, name)) {
|
|
250
|
+
continue;
|
|
251
|
+
}
|
|
252
|
+
const x = a[name] ?? {};
|
|
253
|
+
const y = b[name] ?? {};
|
|
254
|
+
const levels = stricterLevels(x.levels, y.levels);
|
|
255
|
+
const resources = bothNames(x.resources, y.resources);
|
|
256
|
+
const tools = bothNames(x.tools, y.tools);
|
|
257
|
+
const rules = stricterRules(x.rules, y.rules);
|
|
258
|
+
capabilities[name] = {
|
|
259
|
+
...(levels === undefined ? {} : { levels }),
|
|
260
|
+
...(resources === undefined ? {} : { resources }),
|
|
261
|
+
...(tools === undefined ? {} : { tools }),
|
|
262
|
+
...(rules === undefined ? {} : { rules }),
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
return { capabilities, runtime: version.runtime };
|
|
266
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Viewer levels (P087): who the person viewing a display is to it, in the host's words, which
|
|
3
|
+
* decides each capability method's audience. Ordered: `view` (see it, comment) < `interact` (use
|
|
4
|
+
* what the page does: write its data, ask the agent) < `admin` (publish its versions, manage its
|
|
5
|
+
* assets) < `owner`. The host says a viewer's level (its access, per request); Porthole carries it
|
|
6
|
+
* and refuses a call whose method needs more, before any handler runs.
|
|
7
|
+
*/
|
|
8
|
+
export declare const VIEWER_LEVELS: readonly ["view", "interact", "admin", "owner"];
|
|
9
|
+
export type ViewerLevel = (typeof VIEWER_LEVELS)[number];
|
|
10
|
+
export declare function isViewerLevel(value: unknown): value is ViewerLevel;
|
|
11
|
+
/** Whether `level` reaches `needed`. */
|
|
12
|
+
export declare function atLeast(level: ViewerLevel, needed: ViewerLevel): boolean;
|
|
13
|
+
/** The higher of two levels. */
|
|
14
|
+
export declare function higher(a: ViewerLevel, b: ViewerLevel): ViewerLevel;
|
|
15
|
+
/**
|
|
16
|
+
* Who is viewing a display, as the host says (its access at issue, `Grant.level`, or a mount's
|
|
17
|
+
* `viewer`): the level decides what the page may do; `id` and `name` are what the `user`
|
|
18
|
+
* capability tells a page that declares it, and `id` is whose per-user data (`data/users/<id>`)
|
|
19
|
+
* the page reaches. All the host's words, never the content's. `id` is the host's public id for
|
|
20
|
+
* the person (not necessarily the `Grant.viewer` it keeps to itself).
|
|
21
|
+
*/
|
|
22
|
+
export interface ViewerInfo {
|
|
23
|
+
readonly level: ViewerLevel;
|
|
24
|
+
/**
|
|
25
|
+
* One path segment (`A-Z a-z 0-9 _ . ~ : @ + -`, at most 128, never `me`): the host's public id
|
|
26
|
+
* for the person, or a pseudonym per artifact (`pseudonymFor`, P087), never their account id
|
|
27
|
+
* where pages shouldn't link people across artifacts.
|
|
28
|
+
*/
|
|
29
|
+
readonly id?: string;
|
|
30
|
+
readonly name?: string;
|
|
31
|
+
}
|
|
32
|
+
/** A viewer as the host gave it (possibly over the network: an issue's answer), or null. */
|
|
33
|
+
export declare function parseViewer(value: unknown): ViewerInfo | null;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { isDbSegment } from "./segments.js";
|
|
2
|
+
/**
|
|
3
|
+
* Viewer levels (P087): who the person viewing a display is to it, in the host's words, which
|
|
4
|
+
* decides each capability method's audience. Ordered: `view` (see it, comment) < `interact` (use
|
|
5
|
+
* what the page does: write its data, ask the agent) < `admin` (publish its versions, manage its
|
|
6
|
+
* assets) < `owner`. The host says a viewer's level (its access, per request); Porthole carries it
|
|
7
|
+
* and refuses a call whose method needs more, before any handler runs.
|
|
8
|
+
*/
|
|
9
|
+
export const VIEWER_LEVELS = ["view", "interact", "admin", "owner"];
|
|
10
|
+
export function isViewerLevel(value) {
|
|
11
|
+
return typeof value === "string" && VIEWER_LEVELS.includes(value);
|
|
12
|
+
}
|
|
13
|
+
/** Whether `level` reaches `needed`. */
|
|
14
|
+
export function atLeast(level, needed) {
|
|
15
|
+
return VIEWER_LEVELS.indexOf(level) >= VIEWER_LEVELS.indexOf(needed);
|
|
16
|
+
}
|
|
17
|
+
/** The higher of two levels. */
|
|
18
|
+
export function higher(a, b) {
|
|
19
|
+
return atLeast(a, b) ? a : b;
|
|
20
|
+
}
|
|
21
|
+
const MAX_ID = 256;
|
|
22
|
+
/** A viewer as the host gave it (possibly over the network: an issue's answer), or null. */
|
|
23
|
+
export function parseViewer(value) {
|
|
24
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
25
|
+
return null;
|
|
26
|
+
}
|
|
27
|
+
const { level, id, name } = value;
|
|
28
|
+
if (!isViewerLevel(level)) {
|
|
29
|
+
return null;
|
|
30
|
+
}
|
|
31
|
+
const text = (each) => typeof each === "string" && each !== "" && each.length <= MAX_ID && !/[\p{Cc}]/u.test(each);
|
|
32
|
+
// An id names the person's own data (`data/users/<id>`): one path segment, never `me`.
|
|
33
|
+
if ((id !== undefined && !isDbSegment(id)) || (name !== undefined && !text(name))) {
|
|
34
|
+
return null;
|
|
35
|
+
}
|
|
36
|
+
return {
|
|
37
|
+
level,
|
|
38
|
+
...(id === undefined ? {} : { id }),
|
|
39
|
+
...(name === undefined ? {} : { name: name }),
|
|
40
|
+
};
|
|
41
|
+
}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import type { Limits } from "../config/schema.ts";
|
|
2
|
+
import type { ViewerLevel } from "./levels.ts";
|
|
3
|
+
/**
|
|
4
|
+
* What the runtime's own host functions carry (P088–P090), checked where they cross the frame:
|
|
5
|
+
* `artifact` (this artifact's version, and a new one), `assets` (its library), `comments` (the
|
|
6
|
+
* host's composer at an anchor), `user` (who is viewing). A call that doesn't fit is refused
|
|
7
|
+
* before any handler runs; one past a limit is refused as `too_large`.
|
|
8
|
+
*/
|
|
9
|
+
type Parsed<T> = T | "too_large" | null;
|
|
10
|
+
/** The bytes a base64 text decodes to, or null if it isn't base64. */
|
|
11
|
+
export declare function base64Bytes(value: unknown): number | null;
|
|
12
|
+
/** Who is viewing, as the host said (`ViewerInfo`): what `user.get()` answers. */
|
|
13
|
+
export interface UserInfo {
|
|
14
|
+
readonly id: string | null;
|
|
15
|
+
readonly name: string | null;
|
|
16
|
+
readonly level: ViewerLevel;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Where a comment goes, in the page's own words (P090): a name the page chose (`refs/a.md#L12`,
|
|
20
|
+
* `slide-3`), a label to show, the text it quotes. The content's word: the host shows it as such.
|
|
21
|
+
*/
|
|
22
|
+
export interface CommentAnchor {
|
|
23
|
+
readonly name: string;
|
|
24
|
+
readonly label?: string;
|
|
25
|
+
readonly quote?: string;
|
|
26
|
+
}
|
|
27
|
+
export interface CommentRequest {
|
|
28
|
+
readonly anchor: CommentAnchor;
|
|
29
|
+
}
|
|
30
|
+
export declare function parseCommentRequest(args: unknown): CommentRequest | null;
|
|
31
|
+
/** One file of a new version: text, bytes as base64, or `null` (removed from the base's set). */
|
|
32
|
+
export type PublishedFile = {
|
|
33
|
+
readonly text: string;
|
|
34
|
+
} | {
|
|
35
|
+
readonly base64: string;
|
|
36
|
+
} | null;
|
|
37
|
+
/** The most files one publish names (as the publish protocol, task #124 §4). */
|
|
38
|
+
export declare const MAX_PUBLISH_FILES = 255;
|
|
39
|
+
export type ArtifactRequest = {
|
|
40
|
+
readonly op: "get";
|
|
41
|
+
} | {
|
|
42
|
+
readonly op: "publish";
|
|
43
|
+
/** The version the page read and changed: the host refuses with `conflict` if it moved. */
|
|
44
|
+
readonly base: string;
|
|
45
|
+
/** A patch on `base`'s files: listed paths added or replaced, `null` removes, the rest kept. */
|
|
46
|
+
readonly files: Readonly<Record<string, PublishedFile>>;
|
|
47
|
+
readonly entry?: string;
|
|
48
|
+
readonly label?: string;
|
|
49
|
+
readonly note?: string;
|
|
50
|
+
};
|
|
51
|
+
/** This artifact as `artifact.get()` answers it: its current version and that version's files. */
|
|
52
|
+
export interface ArtifactInfo {
|
|
53
|
+
readonly version: string;
|
|
54
|
+
readonly number?: number;
|
|
55
|
+
readonly entry: string;
|
|
56
|
+
readonly files: readonly {
|
|
57
|
+
readonly path: string;
|
|
58
|
+
readonly size: number;
|
|
59
|
+
readonly sha256: string;
|
|
60
|
+
}[];
|
|
61
|
+
}
|
|
62
|
+
/** What a publish answers: the new version. */
|
|
63
|
+
export interface PublishedVersion {
|
|
64
|
+
readonly version: string;
|
|
65
|
+
readonly number?: number;
|
|
66
|
+
}
|
|
67
|
+
export declare function parseArtifactRequest(args: unknown, limits: Partial<Limits>): Parsed<ArtifactRequest>;
|
|
68
|
+
/** Where an artifact's assets are served, on its own origin, outside every version (P089). */
|
|
69
|
+
export declare const ASSET_PATH = "/_blob/";
|
|
70
|
+
/** An asset's id: 32 lowercase hex characters, made by the host, never guessable. */
|
|
71
|
+
export declare const ASSET_ID: RegExp;
|
|
72
|
+
/** An asset's address on its artifact's origin: what a page puts in `src`, as given. */
|
|
73
|
+
export declare const assetUrl: (id: string) => string;
|
|
74
|
+
/** An asset as the library lists it. `type` is Porthole's for its name, never the uploader's. */
|
|
75
|
+
export interface AssetInfo {
|
|
76
|
+
readonly id: string;
|
|
77
|
+
readonly url: string;
|
|
78
|
+
readonly name: string;
|
|
79
|
+
readonly type: string;
|
|
80
|
+
readonly size: number;
|
|
81
|
+
}
|
|
82
|
+
export type AssetRequest = {
|
|
83
|
+
readonly op: "list";
|
|
84
|
+
} | {
|
|
85
|
+
readonly op: "upload";
|
|
86
|
+
/** Its file name: the type it is served with comes from its extension. */
|
|
87
|
+
readonly name: string;
|
|
88
|
+
readonly base64: string;
|
|
89
|
+
readonly size: number;
|
|
90
|
+
/** Porthole's type for `name` (`fileTypeOf`). */
|
|
91
|
+
readonly type: string;
|
|
92
|
+
/**
|
|
93
|
+
* Whether it may run as code (P089, after the review): a script, stylesheet or WebAssembly
|
|
94
|
+
* an admin uploaded where uploaded code may run. Store it (`StoredAsset.trusted`): any other
|
|
95
|
+
* code-typed asset is served as a download.
|
|
96
|
+
*/
|
|
97
|
+
readonly trusted: boolean;
|
|
98
|
+
} | {
|
|
99
|
+
readonly op: "delete";
|
|
100
|
+
readonly id: string;
|
|
101
|
+
};
|
|
102
|
+
/**
|
|
103
|
+
* Whether a file name may go into an asset library: a name (no separators or control
|
|
104
|
+
* characters) whose extension Porthole's table types, and not a page: an asset is never served
|
|
105
|
+
* as a document that runs (P089).
|
|
106
|
+
*/
|
|
107
|
+
export declare function assetNameProblem(name: unknown): string | null;
|
|
108
|
+
/** Whether a name's type runs as code in a page (a script, a stylesheet, WebAssembly). */
|
|
109
|
+
export declare function isCodeAsset(name: string): boolean;
|
|
110
|
+
export declare function parseAssetRequest(args: unknown, limits: Partial<Limits>,
|
|
111
|
+
/** Whether uploaded code may run here (`assetCodeRuns`): else code-typed names are refused. */
|
|
112
|
+
code?: boolean): Parsed<AssetRequest>;
|
|
113
|
+
/** A file `downloads.save` hands the person: a name, its text or bytes (base64), its type. */
|
|
114
|
+
export interface DownloadedFile {
|
|
115
|
+
readonly name: string;
|
|
116
|
+
readonly type?: string;
|
|
117
|
+
readonly text?: string;
|
|
118
|
+
readonly base64?: string;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* `downloads.save(file)` as MCP Apps' `ui/download-file` carries it (one embedded resource), or
|
|
122
|
+
* null for a file that doesn't fit.
|
|
123
|
+
*/
|
|
124
|
+
export declare function downloadContents(file: unknown): readonly unknown[] | null;
|
|
125
|
+
export {};
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import { fileLimits, filePathProblem } from "../files/paths.js";
|
|
2
|
+
import { fileTypeOf } from "../files/types.js";
|
|
3
|
+
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
4
|
+
/** A short text of the content's: a string of `1..max` characters, no control characters. */
|
|
5
|
+
const shortText = (value, max) => typeof value === "string" && value.trim() !== "" && value.length <= max && !/\p{Cc}/u.test(value);
|
|
6
|
+
const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/u;
|
|
7
|
+
/** The bytes a base64 text decodes to, or null if it isn't base64. */
|
|
8
|
+
export function base64Bytes(value) {
|
|
9
|
+
if (typeof value !== "string" || value.length % 4 !== 0 || !BASE64.test(value)) {
|
|
10
|
+
return null;
|
|
11
|
+
}
|
|
12
|
+
const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
|
|
13
|
+
return (value.length / 4) * 3 - padding;
|
|
14
|
+
}
|
|
15
|
+
const encoder = new TextEncoder();
|
|
16
|
+
export function parseCommentRequest(args) {
|
|
17
|
+
const anchor = isRecord(args) ? args.anchor : undefined;
|
|
18
|
+
if (!isRecord(anchor) || !shortText(anchor.name, 256)) {
|
|
19
|
+
return null;
|
|
20
|
+
}
|
|
21
|
+
if ((anchor.label !== undefined && !shortText(anchor.label, 200)) ||
|
|
22
|
+
(anchor.quote !== undefined && !shortText(anchor.quote, 2_000))) {
|
|
23
|
+
return null;
|
|
24
|
+
}
|
|
25
|
+
return {
|
|
26
|
+
anchor: {
|
|
27
|
+
name: anchor.name,
|
|
28
|
+
...(anchor.label === undefined ? {} : { label: anchor.label }),
|
|
29
|
+
...(anchor.quote === undefined ? {} : { quote: anchor.quote }),
|
|
30
|
+
},
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/** The most files one publish names (as the publish protocol, task #124 §4). */
|
|
34
|
+
export const MAX_PUBLISH_FILES = 255;
|
|
35
|
+
export function parseArtifactRequest(args, limits) {
|
|
36
|
+
if (!isRecord(args)) {
|
|
37
|
+
return null;
|
|
38
|
+
}
|
|
39
|
+
if (args.op === "get") {
|
|
40
|
+
return { op: "get" };
|
|
41
|
+
}
|
|
42
|
+
if (args.op !== "publish" || !shortText(args.base, 200) || !isRecord(args.files)) {
|
|
43
|
+
return null;
|
|
44
|
+
}
|
|
45
|
+
const { maxFiles, maxFileBytes, maxVersionBytes } = fileLimits(limits);
|
|
46
|
+
const entries = Object.entries(args.files);
|
|
47
|
+
if (entries.length === 0) {
|
|
48
|
+
return null;
|
|
49
|
+
}
|
|
50
|
+
if (entries.length > Math.min(MAX_PUBLISH_FILES, maxFiles)) {
|
|
51
|
+
return "too_large";
|
|
52
|
+
}
|
|
53
|
+
// No prototype: a path named `__proto__` is a path (after the review).
|
|
54
|
+
const files = Object.create(null);
|
|
55
|
+
let total = 0;
|
|
56
|
+
for (const [path, file] of entries) {
|
|
57
|
+
if (filePathProblem(path) !== null) {
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
if (file === null) {
|
|
61
|
+
files[path] = null;
|
|
62
|
+
continue;
|
|
63
|
+
}
|
|
64
|
+
if (!isRecord(file)) {
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
let size = null;
|
|
68
|
+
if (typeof file.text === "string" && file.base64 === undefined) {
|
|
69
|
+
size = encoder.encode(file.text).length;
|
|
70
|
+
files[path] = { text: file.text };
|
|
71
|
+
}
|
|
72
|
+
else if (file.text === undefined) {
|
|
73
|
+
size = base64Bytes(file.base64);
|
|
74
|
+
if (size !== null) {
|
|
75
|
+
files[path] = { base64: file.base64 };
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
if (size === null) {
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
if (size > maxFileBytes) {
|
|
82
|
+
return "too_large";
|
|
83
|
+
}
|
|
84
|
+
total += size;
|
|
85
|
+
}
|
|
86
|
+
if (total > maxVersionBytes) {
|
|
87
|
+
return "too_large";
|
|
88
|
+
}
|
|
89
|
+
if ((args.entry !== undefined && filePathProblem(args.entry) !== null) ||
|
|
90
|
+
(args.label !== undefined && !shortText(args.label, 60)) ||
|
|
91
|
+
(args.note !== undefined && !shortText(args.note, 500))) {
|
|
92
|
+
return null;
|
|
93
|
+
}
|
|
94
|
+
return {
|
|
95
|
+
op: "publish",
|
|
96
|
+
base: args.base,
|
|
97
|
+
files,
|
|
98
|
+
...(args.entry === undefined ? {} : { entry: args.entry }),
|
|
99
|
+
...(args.label === undefined ? {} : { label: args.label }),
|
|
100
|
+
...(args.note === undefined ? {} : { note: args.note }),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
// --- assets -------------------------------------------------------------------------------------
|
|
104
|
+
/** Where an artifact's assets are served, on its own origin, outside every version (P089). */
|
|
105
|
+
export const ASSET_PATH = "/_blob/";
|
|
106
|
+
/** An asset's id: 32 lowercase hex characters, made by the host, never guessable. */
|
|
107
|
+
export const ASSET_ID = /^[0-9a-f]{32}$/u;
|
|
108
|
+
/** An asset's address on its artifact's origin: what a page puts in `src`, as given. */
|
|
109
|
+
export const assetUrl = (id) => `${ASSET_PATH}${id}`;
|
|
110
|
+
/**
|
|
111
|
+
* Whether a file name may go into an asset library: a name (no separators or control
|
|
112
|
+
* characters) whose extension Porthole's table types, and not a page: an asset is never served
|
|
113
|
+
* as a document that runs (P089).
|
|
114
|
+
*/
|
|
115
|
+
export function assetNameProblem(name) {
|
|
116
|
+
if (typeof name !== "string" ||
|
|
117
|
+
name.trim() === "" ||
|
|
118
|
+
name.length > 255 ||
|
|
119
|
+
/[/\\\p{Cc}\p{Cf}]/u.test(name)) {
|
|
120
|
+
return "an asset's name is a file name: 1 to 255 characters, no / or \\";
|
|
121
|
+
}
|
|
122
|
+
const { role, type } = fileTypeOf(name);
|
|
123
|
+
if (role === "page") {
|
|
124
|
+
return "a page can't be an asset (HTML is published with the artifact's files)";
|
|
125
|
+
}
|
|
126
|
+
if (type === "application/octet-stream") {
|
|
127
|
+
return "an asset's name needs an extension Porthole types (an image, media, a font, a PDF, a stylesheet, a script, text or data)";
|
|
128
|
+
}
|
|
129
|
+
return null;
|
|
130
|
+
}
|
|
131
|
+
/** Whether a name's type runs as code in a page (a script, a stylesheet, WebAssembly). */
|
|
132
|
+
export function isCodeAsset(name) {
|
|
133
|
+
const { role, type } = fileTypeOf(name);
|
|
134
|
+
return role === "script" || type.startsWith("text/css") || type === "application/wasm";
|
|
135
|
+
}
|
|
136
|
+
export function parseAssetRequest(args, limits,
|
|
137
|
+
/** Whether uploaded code may run here (`assetCodeRuns`): else code-typed names are refused. */
|
|
138
|
+
code = true) {
|
|
139
|
+
if (!isRecord(args)) {
|
|
140
|
+
return null;
|
|
141
|
+
}
|
|
142
|
+
switch (args.op) {
|
|
143
|
+
case "list":
|
|
144
|
+
return { op: "list" };
|
|
145
|
+
case "delete":
|
|
146
|
+
return typeof args.id === "string" && ASSET_ID.test(args.id)
|
|
147
|
+
? { op: "delete", id: args.id }
|
|
148
|
+
: null;
|
|
149
|
+
case "upload": {
|
|
150
|
+
if (assetNameProblem(args.name) !== null || (!code && isCodeAsset(args.name))) {
|
|
151
|
+
return null;
|
|
152
|
+
}
|
|
153
|
+
const size = base64Bytes(args.base64);
|
|
154
|
+
if (size === null) {
|
|
155
|
+
return null;
|
|
156
|
+
}
|
|
157
|
+
if (size > fileLimits(limits).maxFileBytes) {
|
|
158
|
+
return "too_large";
|
|
159
|
+
}
|
|
160
|
+
const name = args.name;
|
|
161
|
+
return {
|
|
162
|
+
op: "upload",
|
|
163
|
+
name,
|
|
164
|
+
base64: args.base64,
|
|
165
|
+
size,
|
|
166
|
+
type: fileTypeOf(name).type,
|
|
167
|
+
// The bridge says, once it knows who uploads (P089).
|
|
168
|
+
trusted: false,
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
default:
|
|
172
|
+
return null;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* `downloads.save(file)` as MCP Apps' `ui/download-file` carries it (one embedded resource), or
|
|
177
|
+
* null for a file that doesn't fit.
|
|
178
|
+
*/
|
|
179
|
+
export function downloadContents(file) {
|
|
180
|
+
if (!isRecord(file) || !shortText(file.name, 255) || /[/\\]/u.test(file.name)) {
|
|
181
|
+
return null;
|
|
182
|
+
}
|
|
183
|
+
const type = file.type === undefined
|
|
184
|
+
? fileTypeOf(file.name).type
|
|
185
|
+
: typeof file.type === "string" && /^[\w.+-]+\/[\w.+-]+$/u.test(file.type)
|
|
186
|
+
? file.type
|
|
187
|
+
: null;
|
|
188
|
+
if (type === null) {
|
|
189
|
+
return null;
|
|
190
|
+
}
|
|
191
|
+
const uri = `file:///${encodeURIComponent(file.name)}`;
|
|
192
|
+
if (typeof file.text === "string" && file.base64 === undefined) {
|
|
193
|
+
return [{ type: "resource", resource: { uri, mimeType: type, text: file.text } }];
|
|
194
|
+
}
|
|
195
|
+
if (file.text === undefined && base64Bytes(file.base64) !== null) {
|
|
196
|
+
return [{ type: "resource", resource: { uri, mimeType: type, blob: file.base64 } }];
|
|
197
|
+
}
|
|
198
|
+
return null;
|
|
199
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** A db path's segment (P088): letters, digits and `_ . ~ : @ + -`, at most 128. */
|
|
2
|
+
export declare const SEGMENT: RegExp;
|
|
3
|
+
/**
|
|
4
|
+
* Whether `value` is one path segment: what a viewer's id must be to name their own data
|
|
5
|
+
* (`data/users/<id>`), and never `me`, which names them (after the review: an id `a/b` would
|
|
6
|
+
* reach another person's tree).
|
|
7
|
+
*/
|
|
8
|
+
export declare function isDbSegment(value: unknown): value is string;
|