@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,363 @@
|
|
|
1
|
+
import { RUNTIME_CAPABILITY_NAMES, RUNTIME_VERSION, isRuntimeCapabilityName, isRuntimeVersion, offeredCapabilities, runtimeCapability, } from "./contract.js";
|
|
2
|
+
import { dbRuleLevel, dbRuleOf, dbRulesProblem, foldCollection, stricterDbRule, } 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
|
+
/** The most names `data` lists at publish; where shown (an intersection of two), twice that (P093). */
|
|
10
|
+
const MAX_NAMES = 200;
|
|
11
|
+
const names = (values, path, problems, stage) => {
|
|
12
|
+
const most = stage === "publish" ? MAX_NAMES : 2 * MAX_NAMES;
|
|
13
|
+
if (!Array.isArray(values) ||
|
|
14
|
+
values.length > most ||
|
|
15
|
+
values.some((each) => typeof each !== "string" ||
|
|
16
|
+
each === "" ||
|
|
17
|
+
each.length > 512 ||
|
|
18
|
+
/\p{Cc}/u.test(each) ||
|
|
19
|
+
// A `*` only at the end: a prefix.
|
|
20
|
+
(each.includes("*") && each.indexOf("*") !== each.length - 1))) {
|
|
21
|
+
problems.push({
|
|
22
|
+
path,
|
|
23
|
+
message: `must be a list of names (at most ${most}), each exact or a prefix ending in *`,
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* The problems with a declaration, against the host's offer (`config`): each name one the
|
|
29
|
+
* runtime knows, the config offers and isn't built in; each config of its own shape. Empty: fine.
|
|
30
|
+
*/
|
|
31
|
+
export function declarationProblems(given, config, runtime = RUNTIME_VERSION) {
|
|
32
|
+
return stagedProblems(given, config, runtime, "publish");
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* `declarationProblems` at a stage (P093): at publish, the limits a page is held to; where a
|
|
36
|
+
* declaration is shown (a mount), an intersection of two such (`intersectDeclarations`) fits too.
|
|
37
|
+
*/
|
|
38
|
+
function stagedProblems(given, config, runtime, stage) {
|
|
39
|
+
const problems = [];
|
|
40
|
+
if (!isRuntimeVersion(runtime)) {
|
|
41
|
+
return [{ path: "runtime", message: `is not a runtime version Porthole serves` }];
|
|
42
|
+
}
|
|
43
|
+
if (!isRecord(given)) {
|
|
44
|
+
return [{ path: "capabilities", message: "must be an object: { name: config }" }];
|
|
45
|
+
}
|
|
46
|
+
const offered = offeredCapabilities(config);
|
|
47
|
+
for (const [name, value] of Object.entries(given)) {
|
|
48
|
+
const path = `capabilities.${name}`;
|
|
49
|
+
if (!isRuntimeCapabilityName(name)) {
|
|
50
|
+
problems.push({
|
|
51
|
+
path,
|
|
52
|
+
message: `is not a capability (${RUNTIME_CAPABILITY_NAMES.filter((each) => !runtimeCapability(each).builtIn).join(", ")})`,
|
|
53
|
+
});
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
if (runtimeCapability(name).builtIn) {
|
|
57
|
+
problems.push({ path, message: "is built in: use it without declaring it" });
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
if (!offered.includes(name)) {
|
|
61
|
+
problems.push({ path, message: "isn't offered here" });
|
|
62
|
+
continue;
|
|
63
|
+
}
|
|
64
|
+
configProblems(name, value, path, problems, stage);
|
|
65
|
+
}
|
|
66
|
+
return problems;
|
|
67
|
+
}
|
|
68
|
+
/** The problems with one capability's config, its shape alone (no host's offer needed). */
|
|
69
|
+
function configProblems(name, value, path, problems, stage) {
|
|
70
|
+
const spec = runtimeCapability(name);
|
|
71
|
+
if (!isRecord(value)) {
|
|
72
|
+
problems.push({ path, message: "must be an object ({} for none of its own)" });
|
|
73
|
+
return;
|
|
74
|
+
}
|
|
75
|
+
const allowed = KEYS[name] ?? ["levels"];
|
|
76
|
+
for (const key of Object.keys(value)) {
|
|
77
|
+
if (!allowed.includes(key)) {
|
|
78
|
+
problems.push({ path: `${path}.${key}`, message: `is not a field of ${name}'s config` });
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
if (value.levels !== undefined) {
|
|
82
|
+
if (!isRecord(value.levels)) {
|
|
83
|
+
problems.push({ path: `${path}.levels`, message: "must be an object of levels by method" });
|
|
84
|
+
}
|
|
85
|
+
else {
|
|
86
|
+
for (const [method, level] of Object.entries(value.levels)) {
|
|
87
|
+
if (!Object.hasOwn(spec.methods, method)) {
|
|
88
|
+
problems.push({
|
|
89
|
+
path: `${path}.levels.${method}`,
|
|
90
|
+
message: `is not a method of ${name} (${Object.keys(spec.methods).join(", ")})`,
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
else if (!isViewerLevel(level)) {
|
|
94
|
+
problems.push({
|
|
95
|
+
path: `${path}.levels.${method}`,
|
|
96
|
+
message: "must be view, interact, admin or owner",
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
if (name === "data") {
|
|
103
|
+
if (value.resources !== undefined) {
|
|
104
|
+
names(value.resources, `${path}.resources`, problems, stage);
|
|
105
|
+
}
|
|
106
|
+
if (value.tools !== undefined) {
|
|
107
|
+
names(value.tools, `${path}.tools`, problems, stage);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
if (name === "db" && value.rules !== undefined) {
|
|
111
|
+
const problem = dbRulesProblem(value.rules, stage);
|
|
112
|
+
if (problem !== null) {
|
|
113
|
+
problems.push({ path: `${path}.rules`, message: problem });
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
/** A declaration checked (a host's stored one, given to `mount`); throws a `TypeError` naming its problems. */
|
|
118
|
+
export function checkDeclaration(given, config) {
|
|
119
|
+
if (!isRecord(given)) {
|
|
120
|
+
throw new TypeError("A declaration is { capabilities, runtime }");
|
|
121
|
+
}
|
|
122
|
+
const runtime = given.runtime;
|
|
123
|
+
if (!isRuntimeVersion(runtime)) {
|
|
124
|
+
throw new TypeError(`A declaration's runtime ${JSON.stringify(runtime)} is not one this Porthole serves`);
|
|
125
|
+
}
|
|
126
|
+
const problems = stagedProblems(given.capabilities, config, runtime, "shown");
|
|
127
|
+
if (problems.length > 0) {
|
|
128
|
+
throw new TypeError(`The declaration doesn't fit this config: ${problems.map((each) => `${each.path} ${each.message}`).join("; ")}`);
|
|
129
|
+
}
|
|
130
|
+
return { capabilities: copied(given.capabilities), runtime };
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* A declaration's own copy, every object without a prototype (after the review): a rule or a
|
|
134
|
+
* level looked up by a name like `constructor` finds nothing but what the page wrote.
|
|
135
|
+
*/
|
|
136
|
+
function copied(value) {
|
|
137
|
+
if (Array.isArray(value)) {
|
|
138
|
+
return value.map(copied);
|
|
139
|
+
}
|
|
140
|
+
if (value === null || typeof value !== "object") {
|
|
141
|
+
return value;
|
|
142
|
+
}
|
|
143
|
+
const out = Object.create(null);
|
|
144
|
+
for (const [key, each] of Object.entries(value)) {
|
|
145
|
+
out[key] = copied(each);
|
|
146
|
+
}
|
|
147
|
+
return out;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* At publish (P086): the declaration a new version leaves the artifact with.
|
|
151
|
+
* - `given` undefined: the stored one, unchanged (its pin too); none stored: an empty one.
|
|
152
|
+
* - `given` `{}`: cleared.
|
|
153
|
+
* - `given` non-empty: it replaces the stored one whole (anything not restated is revoked).
|
|
154
|
+
* The pin moves only when the author asks (`runtime`). Checked against the host's offer.
|
|
155
|
+
*/
|
|
156
|
+
export function declareCapabilities(options) {
|
|
157
|
+
const { stored, given, config } = options;
|
|
158
|
+
if (options.runtime !== undefined && !isRuntimeVersion(options.runtime)) {
|
|
159
|
+
return {
|
|
160
|
+
ok: false,
|
|
161
|
+
problems: [{ path: "runtime", message: "is not a runtime version Porthole serves" }],
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
const runtime = options.runtime ?? stored?.runtime ?? RUNTIME_VERSION;
|
|
165
|
+
if (given === undefined) {
|
|
166
|
+
const capabilities = stored?.capabilities ?? {};
|
|
167
|
+
// A stored declaration still fits the host's offer (a host may have narrowed its config); as
|
|
168
|
+
// stored, a page's from before P093 too (rule names in more than one case).
|
|
169
|
+
const problems = stagedProblems(capabilities, config, runtime, "shown");
|
|
170
|
+
return problems.length > 0
|
|
171
|
+
? { ok: false, problems }
|
|
172
|
+
: {
|
|
173
|
+
ok: true,
|
|
174
|
+
// Its own copy, as at a publish that gives one (P093, after its review).
|
|
175
|
+
declaration: { capabilities: copied(capabilities), runtime },
|
|
176
|
+
changed: stored === undefined || stored === null || stored.runtime !== runtime,
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
const problems = declarationProblems(given, config, runtime);
|
|
180
|
+
if (problems.length > 0) {
|
|
181
|
+
return { ok: false, problems };
|
|
182
|
+
}
|
|
183
|
+
// Its own copy, without prototypes (P093): what was checked, not the caller's object.
|
|
184
|
+
const declaration = { capabilities: copied(given), runtime };
|
|
185
|
+
return {
|
|
186
|
+
ok: true,
|
|
187
|
+
declaration,
|
|
188
|
+
changed: stored === undefined ||
|
|
189
|
+
stored === null ||
|
|
190
|
+
stored.runtime !== runtime ||
|
|
191
|
+
JSON.stringify(stored.capabilities) !== JSON.stringify(declaration.capabilities),
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* A name a prefix can't vouch for (after the review): a dot segment, or one written with an
|
|
196
|
+
* escape or a backslash, may resolve outside the prefix (`app://tasks/../secrets`).
|
|
197
|
+
*/
|
|
198
|
+
const ESCAPES_PREFIX = /(^|[/\\])\.{1,2}([/\\?#]|$)|%2e|%2f|%5c|\\/iu;
|
|
199
|
+
/** Whether `name` matches a declared list's entry (exact, or a prefix ending in `*`). */
|
|
200
|
+
export function declaredMatch(list, name) {
|
|
201
|
+
return (list === undefined ||
|
|
202
|
+
list.some((each) => each.endsWith("*")
|
|
203
|
+
? name.startsWith(each.slice(0, -1)) && !ESCAPES_PREFIX.test(name)
|
|
204
|
+
: each === name));
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* An object without a prototype (P093): a name the page wrote (`__proto__`, a collection's) is an
|
|
208
|
+
* own key of it when set, never a prototype's setter or a prototype's name when read.
|
|
209
|
+
*/
|
|
210
|
+
const bare = () => Object.create(null);
|
|
211
|
+
/** The stricter of two declared level maps (absent: the contract's, everywhere). */
|
|
212
|
+
function stricterLevels(a, b) {
|
|
213
|
+
if (a === undefined && b === undefined) {
|
|
214
|
+
return undefined;
|
|
215
|
+
}
|
|
216
|
+
const out = bare();
|
|
217
|
+
for (const method of new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})])) {
|
|
218
|
+
const x = a !== undefined && Object.hasOwn(a, method) ? a[method] : undefined;
|
|
219
|
+
const y = b !== undefined && Object.hasOwn(b, method) ? b[method] : undefined;
|
|
220
|
+
const level = x === undefined ? y : y === undefined ? x : higher(x, y);
|
|
221
|
+
if (level !== undefined) {
|
|
222
|
+
out[method] = level;
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
return out;
|
|
226
|
+
}
|
|
227
|
+
/** The names both lists admit (absent: everything). */
|
|
228
|
+
function bothNames(a, b) {
|
|
229
|
+
if (a === undefined || b === undefined) {
|
|
230
|
+
return a === undefined ? b?.slice() : a.slice();
|
|
231
|
+
}
|
|
232
|
+
return [
|
|
233
|
+
...new Set([
|
|
234
|
+
...a.filter((each) => declaredMatch(b, each)),
|
|
235
|
+
...b.filter((each) => declaredMatch(a, each)),
|
|
236
|
+
]),
|
|
237
|
+
];
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* The stricter of two pages' rules, by collection (P093, the 2026-10-19 audit's S02): each name
|
|
241
|
+
* either side's rules give, in any case, and `*`, is under the stricter of the rule EACH side
|
|
242
|
+
* puts it under, as `dbAccess` reads that side (`dbRuleOf`). A collection neither names is under
|
|
243
|
+
* both sides' `*`, the output's `*`. So the output allows a level at most what both allow it (an
|
|
244
|
+
* old version's `public` doesn't outlive the current `*`, nor the other way), and exactly that
|
|
245
|
+
* where both spell each collection alike; where they spell one differently it may be stricter
|
|
246
|
+
* (after the re-review). One name for each name in any case (as the first side spells it); none
|
|
247
|
+
* for a name whose rule is the output's `*`'s (after the review: it says nothing `*` doesn't).
|
|
248
|
+
*/
|
|
249
|
+
function stricterRules(a, b) {
|
|
250
|
+
if (a === undefined && b === undefined) {
|
|
251
|
+
return undefined;
|
|
252
|
+
}
|
|
253
|
+
const wildcard = stricterDbRule(dbRuleOf(a, "*"), dbRuleOf(b, "*"));
|
|
254
|
+
const same = (rule) => dbRuleLevel(rule, false) === dbRuleLevel(wildcard, false) &&
|
|
255
|
+
dbRuleLevel(rule, true) === dbRuleLevel(wildcard, true);
|
|
256
|
+
const out = bare();
|
|
257
|
+
const seen = new Set();
|
|
258
|
+
for (const name of [...Object.keys(a ?? {}), ...Object.keys(b ?? {})]) {
|
|
259
|
+
const folded = foldCollection(name);
|
|
260
|
+
if (name === "*" || seen.has(folded)) {
|
|
261
|
+
continue;
|
|
262
|
+
}
|
|
263
|
+
seen.add(folded);
|
|
264
|
+
const rule = stricterDbRule(dbRuleOf(a, name), dbRuleOf(b, name));
|
|
265
|
+
if (!same(rule)) {
|
|
266
|
+
out[name] = rule;
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
if ((a !== undefined && Object.hasOwn(a, "*")) || (b !== undefined && Object.hasOwn(b, "*"))) {
|
|
270
|
+
out["*"] = wildcard;
|
|
271
|
+
}
|
|
272
|
+
return out;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* The problems with a declaration's shape where it is shown (no host's offer: the mount checks
|
|
276
|
+
* that), each path under `which`: what would be read as allowing anything could loosen the other
|
|
277
|
+
* side (`higher` with a level that isn't one returns the other).
|
|
278
|
+
*/
|
|
279
|
+
function shapeProblems(declaration, which) {
|
|
280
|
+
const problems = [];
|
|
281
|
+
if (!isRecord(declaration) || !isRecord(declaration.capabilities)) {
|
|
282
|
+
return [{ path: `${which}.capabilities`, message: "must be an object: { name: config }" }];
|
|
283
|
+
}
|
|
284
|
+
if (!isRuntimeVersion(declaration.runtime)) {
|
|
285
|
+
problems.push({
|
|
286
|
+
path: `${which}.runtime`,
|
|
287
|
+
message: "is not a runtime version Porthole serves",
|
|
288
|
+
});
|
|
289
|
+
}
|
|
290
|
+
for (const [name, value] of Object.entries(declaration.capabilities)) {
|
|
291
|
+
const path = `${which}.capabilities.${name}`;
|
|
292
|
+
if (!isRuntimeCapabilityName(name)) {
|
|
293
|
+
problems.push({ path, message: "is not a capability" });
|
|
294
|
+
}
|
|
295
|
+
else if (runtimeCapability(name).builtIn) {
|
|
296
|
+
problems.push({ path, message: "is built in: use it without declaring it" });
|
|
297
|
+
}
|
|
298
|
+
else {
|
|
299
|
+
configProblems(name, value, path, problems, "shown");
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
return problems;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* What a version may do when it is shown (after the review): what it declared when it was
|
|
306
|
+
* published AND what the artifact declares now. A host stores each version's declaration with
|
|
307
|
+
* it (`declareCapabilities` at its publish) and mounts a version with this, so an old version
|
|
308
|
+
* never keeps what the artifact has since revoked, nor gains what it declared later. Each
|
|
309
|
+
* capability only where both declare it, at the stricter levels, the narrower `data` names and
|
|
310
|
+
* the stricter `db` rules (each side read as `dbAccess` reads it, P093); the version's own pinned
|
|
311
|
+
* runtime. Whatever the result allows, each side allows alone; a mount takes it (two pages at
|
|
312
|
+
* the publish limits make one within a mount's). Objects without a prototype.
|
|
313
|
+
*
|
|
314
|
+
* Answers its problems (P093, after its review) where either side isn't a declaration's shape
|
|
315
|
+
* (or the two make one past a mount's limits): show the version as an error, never with `null`
|
|
316
|
+
* (that is 0.6's surface) or with either side alone.
|
|
317
|
+
*/
|
|
318
|
+
export function tryIntersectDeclarations(version, current) {
|
|
319
|
+
const problems = [...shapeProblems(version, "version"), ...shapeProblems(current, "current")];
|
|
320
|
+
if (problems.length > 0) {
|
|
321
|
+
return { ok: false, problems };
|
|
322
|
+
}
|
|
323
|
+
const a = version.capabilities;
|
|
324
|
+
const b = current.capabilities;
|
|
325
|
+
const capabilities = bare();
|
|
326
|
+
for (const name of Object.keys(a)) {
|
|
327
|
+
if (!Object.hasOwn(b, name)) {
|
|
328
|
+
continue;
|
|
329
|
+
}
|
|
330
|
+
const x = a[name] ?? {};
|
|
331
|
+
const y = b[name] ?? {};
|
|
332
|
+
const out = Object.create(null);
|
|
333
|
+
const levels = stricterLevels(x.levels, y.levels);
|
|
334
|
+
const resources = bothNames(x.resources, y.resources);
|
|
335
|
+
const tools = bothNames(x.tools, y.tools);
|
|
336
|
+
const rules = stricterRules(x.rules, y.rules);
|
|
337
|
+
if (levels !== undefined) {
|
|
338
|
+
out.levels = levels;
|
|
339
|
+
}
|
|
340
|
+
if (resources !== undefined) {
|
|
341
|
+
out.resources = resources;
|
|
342
|
+
}
|
|
343
|
+
if (tools !== undefined) {
|
|
344
|
+
out.tools = tools;
|
|
345
|
+
}
|
|
346
|
+
if (rules !== undefined) {
|
|
347
|
+
out.rules = rules;
|
|
348
|
+
}
|
|
349
|
+
capabilities[name] = out;
|
|
350
|
+
}
|
|
351
|
+
const declaration = { capabilities, runtime: version.runtime };
|
|
352
|
+
// Within a mount's limits: sides that were themselves intersections could make one past them.
|
|
353
|
+
const past = shapeProblems(declaration, "intersection");
|
|
354
|
+
return past.length > 0 ? { ok: false, problems: past } : { ok: true, declaration };
|
|
355
|
+
}
|
|
356
|
+
/** `tryIntersectDeclarations`, a `TypeError` naming the problems where it answers some. */
|
|
357
|
+
export function intersectDeclarations(version, current) {
|
|
358
|
+
const result = tryIntersectDeclarations(version, current);
|
|
359
|
+
if (!result.ok) {
|
|
360
|
+
throw new TypeError(`The declarations don't intersect: ${result.problems.map((each) => `${each.path} ${each.message}`).join("; ")}`);
|
|
361
|
+
}
|
|
362
|
+
return result.declaration;
|
|
363
|
+
}
|
|
@@ -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 {};
|