@botiverse/porthole 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +200 -8
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/policy.d.ts +19 -0
- package/dist/compile/policy.js +42 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +24 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +66 -4
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +34 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +24 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +8 -2
- package/dist/index.js +9 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +48 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +14 -1
- package/dist/server/files.js +97 -3
- package/dist/server/host.d.ts +6 -1
- package/dist/server/host.js +5 -0
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +1 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +214 -35
- package/dist/server/types.d.ts +69 -0
- package/dist/shell/document.d.ts +8 -0
- package/dist/shell/document.js +16 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +29 -42
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +91 -6
- package/docs/ARCHITECTURE.md +22 -3
- package/docs/DECISIONS.md +415 -6
- package/docs/DESIGN.md +66 -0
- package/package.json +3 -1
- package/src/bridge/bridge.ts +273 -12
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/policy.ts +54 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +24 -0
- package/src/config/validate.ts +99 -4
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +59 -53
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +34 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +89 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +52 -3
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +117 -4
- package/src/server/host.ts +12 -0
- package/src/server/index.ts +3 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +247 -37
- package/src/server/types.ts +68 -0
- package/src/shell/document.ts +21 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +29 -42
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import {
|
|
3
|
+
RUNTIME_CAPABILITY_NAMES,
|
|
4
|
+
RUNTIME_VERSION,
|
|
5
|
+
isRuntimeCapabilityName,
|
|
6
|
+
isRuntimeVersion,
|
|
7
|
+
offeredCapabilities,
|
|
8
|
+
runtimeCapability,
|
|
9
|
+
type RuntimeVersion,
|
|
10
|
+
} from "./contract.ts";
|
|
11
|
+
import { dbRulesProblem, type DbRules } from "./db.ts";
|
|
12
|
+
import { higher, isViewerLevel, type ViewerLevel } from "./levels.ts";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* A page's declaration (P086): the capabilities it uses, by name, each with its own config,
|
|
16
|
+
* stored with the artifact when it is published and handed to `mount` when it is shown; and the
|
|
17
|
+
* runtime contract it was written against, pinned. Built-ins are never declared.
|
|
18
|
+
*
|
|
19
|
+
* At publish (`declareCapabilities`): omitted carries the stored declaration forward (and its
|
|
20
|
+
* pin); `{}` clears it; a non-empty object replaces it whole. A page can't change its own: a
|
|
21
|
+
* publish from the page (`artifact.publish`) carries none.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
/** Every capability's config may raise its methods' levels (never lower them). */
|
|
25
|
+
export interface DeclaredCapability {
|
|
26
|
+
readonly levels?: Readonly<Record<string, ViewerLevel>>;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** `data`: which of the host's resources and tools the page uses (absent: all it serves). */
|
|
30
|
+
export interface DeclaredData extends DeclaredCapability {
|
|
31
|
+
/** URIs, exact, or a prefix ending in `*` (`app://tasks/*`). */
|
|
32
|
+
readonly resources?: readonly string[];
|
|
33
|
+
readonly tools?: readonly string[];
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** `db`: the page's rules for its data, by top-level collection (`DbRules`). */
|
|
37
|
+
export interface DeclaredDb extends DeclaredCapability {
|
|
38
|
+
readonly rules?: DbRules;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** What a page declares, by runtime capability name. */
|
|
42
|
+
export interface CapabilityDeclaration {
|
|
43
|
+
readonly user?: DeclaredCapability;
|
|
44
|
+
readonly chat?: DeclaredCapability;
|
|
45
|
+
readonly data?: DeclaredData;
|
|
46
|
+
readonly context?: DeclaredCapability;
|
|
47
|
+
readonly artifact?: DeclaredCapability;
|
|
48
|
+
readonly assets?: DeclaredCapability;
|
|
49
|
+
readonly db?: DeclaredDb;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** A declaration as an artifact stores it and a mount is given it. */
|
|
53
|
+
export interface PageDeclaration {
|
|
54
|
+
readonly capabilities: CapabilityDeclaration;
|
|
55
|
+
readonly runtime: RuntimeVersion;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export interface DeclarationProblem {
|
|
59
|
+
/** Where, as `capabilities.db.rules.votes`. */
|
|
60
|
+
readonly path: string;
|
|
61
|
+
readonly message: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
65
|
+
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
66
|
+
|
|
67
|
+
const KEYS: Readonly<Record<string, readonly string[]>> = {
|
|
68
|
+
data: ["levels", "resources", "tools"],
|
|
69
|
+
db: ["levels", "rules"],
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
const names = (values: unknown, path: string, problems: DeclarationProblem[]): void => {
|
|
73
|
+
if (
|
|
74
|
+
!Array.isArray(values) ||
|
|
75
|
+
values.length > 200 ||
|
|
76
|
+
values.some(
|
|
77
|
+
(each) =>
|
|
78
|
+
typeof each !== "string" ||
|
|
79
|
+
each === "" ||
|
|
80
|
+
each.length > 512 ||
|
|
81
|
+
/\p{Cc}/u.test(each) ||
|
|
82
|
+
// A `*` only at the end: a prefix.
|
|
83
|
+
(each.includes("*") && each.indexOf("*") !== each.length - 1),
|
|
84
|
+
)
|
|
85
|
+
) {
|
|
86
|
+
problems.push({
|
|
87
|
+
path,
|
|
88
|
+
message: "must be a list of names (at most 200), each exact or a prefix ending in *",
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The problems with a declaration, against the host's offer (`config`): each name one the
|
|
95
|
+
* runtime knows, the config offers and isn't built in; each config of its own shape. Empty: fine.
|
|
96
|
+
*/
|
|
97
|
+
export function declarationProblems(
|
|
98
|
+
given: unknown,
|
|
99
|
+
config: PortholeConfig,
|
|
100
|
+
runtime: RuntimeVersion = RUNTIME_VERSION,
|
|
101
|
+
): DeclarationProblem[] {
|
|
102
|
+
const problems: DeclarationProblem[] = [];
|
|
103
|
+
if (!isRuntimeVersion(runtime)) {
|
|
104
|
+
return [{ path: "runtime", message: `is not a runtime version Porthole serves` }];
|
|
105
|
+
}
|
|
106
|
+
if (!isRecord(given)) {
|
|
107
|
+
return [{ path: "capabilities", message: "must be an object: { name: config }" }];
|
|
108
|
+
}
|
|
109
|
+
const offered = offeredCapabilities(config);
|
|
110
|
+
for (const [name, value] of Object.entries(given)) {
|
|
111
|
+
const path = `capabilities.${name}`;
|
|
112
|
+
if (!isRuntimeCapabilityName(name)) {
|
|
113
|
+
problems.push({
|
|
114
|
+
path,
|
|
115
|
+
message: `is not a capability (${RUNTIME_CAPABILITY_NAMES.filter((each) => !runtimeCapability(each).builtIn).join(", ")})`,
|
|
116
|
+
});
|
|
117
|
+
continue;
|
|
118
|
+
}
|
|
119
|
+
const spec = runtimeCapability(name);
|
|
120
|
+
if (spec.builtIn) {
|
|
121
|
+
problems.push({ path, message: "is built in: use it without declaring it" });
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
if (!offered.includes(name)) {
|
|
125
|
+
problems.push({ path, message: "isn't offered here" });
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
if (!isRecord(value)) {
|
|
129
|
+
problems.push({ path, message: "must be an object ({} for none of its own)" });
|
|
130
|
+
continue;
|
|
131
|
+
}
|
|
132
|
+
const allowed = KEYS[name] ?? ["levels"];
|
|
133
|
+
for (const key of Object.keys(value)) {
|
|
134
|
+
if (!allowed.includes(key)) {
|
|
135
|
+
problems.push({ path: `${path}.${key}`, message: `is not a field of ${name}'s config` });
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
if (value.levels !== undefined) {
|
|
139
|
+
if (!isRecord(value.levels)) {
|
|
140
|
+
problems.push({ path: `${path}.levels`, message: "must be an object of levels by method" });
|
|
141
|
+
} else {
|
|
142
|
+
for (const [method, level] of Object.entries(value.levels)) {
|
|
143
|
+
if (!Object.hasOwn(spec.methods, method)) {
|
|
144
|
+
problems.push({
|
|
145
|
+
path: `${path}.levels.${method}`,
|
|
146
|
+
message: `is not a method of ${name} (${Object.keys(spec.methods).join(", ")})`,
|
|
147
|
+
});
|
|
148
|
+
} else if (!isViewerLevel(level)) {
|
|
149
|
+
problems.push({
|
|
150
|
+
path: `${path}.levels.${method}`,
|
|
151
|
+
message: "must be view, interact, admin or owner",
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
if (name === "data") {
|
|
158
|
+
if (value.resources !== undefined) {
|
|
159
|
+
names(value.resources, `${path}.resources`, problems);
|
|
160
|
+
}
|
|
161
|
+
if (value.tools !== undefined) {
|
|
162
|
+
names(value.tools, `${path}.tools`, problems);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
if (name === "db" && value.rules !== undefined) {
|
|
166
|
+
const problem = dbRulesProblem(value.rules);
|
|
167
|
+
if (problem !== null) {
|
|
168
|
+
problems.push({ path: `${path}.rules`, message: problem });
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
return problems;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** A declaration checked (a host's stored one, given to `mount`); throws a `TypeError` naming its problems. */
|
|
176
|
+
export function checkDeclaration(given: unknown, config: PortholeConfig): PageDeclaration {
|
|
177
|
+
if (!isRecord(given)) {
|
|
178
|
+
throw new TypeError("A declaration is { capabilities, runtime }");
|
|
179
|
+
}
|
|
180
|
+
const runtime = given.runtime;
|
|
181
|
+
if (!isRuntimeVersion(runtime)) {
|
|
182
|
+
throw new TypeError(
|
|
183
|
+
`A declaration's runtime ${JSON.stringify(runtime)} is not one this Porthole serves`,
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
const problems = declarationProblems(given.capabilities, config, runtime);
|
|
187
|
+
if (problems.length > 0) {
|
|
188
|
+
throw new TypeError(
|
|
189
|
+
`The declaration doesn't fit this config: ${problems.map((each) => `${each.path} ${each.message}`).join("; ")}`,
|
|
190
|
+
);
|
|
191
|
+
}
|
|
192
|
+
return { capabilities: copied(given.capabilities) as CapabilityDeclaration, runtime };
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* A declaration's own copy, every object without a prototype (after the review): a rule or a
|
|
197
|
+
* level looked up by a name like `constructor` finds nothing but what the page wrote.
|
|
198
|
+
*/
|
|
199
|
+
function copied(value: unknown): unknown {
|
|
200
|
+
if (Array.isArray(value)) {
|
|
201
|
+
return value.map(copied);
|
|
202
|
+
}
|
|
203
|
+
if (value === null || typeof value !== "object") {
|
|
204
|
+
return value;
|
|
205
|
+
}
|
|
206
|
+
const out = Object.create(null) as Record<string, unknown>;
|
|
207
|
+
for (const [key, each] of Object.entries(value)) {
|
|
208
|
+
out[key] = copied(each);
|
|
209
|
+
}
|
|
210
|
+
return out;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* At publish (P086): the declaration a new version leaves the artifact with.
|
|
215
|
+
* - `given` undefined: the stored one, unchanged (its pin too); none stored: an empty one.
|
|
216
|
+
* - `given` `{}`: cleared.
|
|
217
|
+
* - `given` non-empty: it replaces the stored one whole (anything not restated is revoked).
|
|
218
|
+
* The pin moves only when the author asks (`runtime`). Checked against the host's offer.
|
|
219
|
+
*/
|
|
220
|
+
export function declareCapabilities(options: {
|
|
221
|
+
readonly stored?: PageDeclaration | null;
|
|
222
|
+
readonly given?: unknown;
|
|
223
|
+
readonly config: PortholeConfig;
|
|
224
|
+
readonly runtime?: unknown;
|
|
225
|
+
}):
|
|
226
|
+
| {
|
|
227
|
+
readonly ok: true;
|
|
228
|
+
readonly declaration: PageDeclaration;
|
|
229
|
+
/** Whether it differs from the stored one. */
|
|
230
|
+
readonly changed: boolean;
|
|
231
|
+
}
|
|
232
|
+
| { readonly ok: false; readonly problems: readonly DeclarationProblem[] } {
|
|
233
|
+
const { stored, given, config } = options;
|
|
234
|
+
if (options.runtime !== undefined && !isRuntimeVersion(options.runtime)) {
|
|
235
|
+
return {
|
|
236
|
+
ok: false,
|
|
237
|
+
problems: [{ path: "runtime", message: "is not a runtime version Porthole serves" }],
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
const runtime: RuntimeVersion = options.runtime ?? stored?.runtime ?? RUNTIME_VERSION;
|
|
241
|
+
if (given === undefined) {
|
|
242
|
+
const declaration = stored ?? { capabilities: {}, runtime };
|
|
243
|
+
const pinned = { capabilities: declaration.capabilities, runtime };
|
|
244
|
+
// A stored declaration still fits the host's offer (a host may have narrowed its config).
|
|
245
|
+
const problems = declarationProblems(pinned.capabilities, config, runtime);
|
|
246
|
+
return problems.length > 0
|
|
247
|
+
? { ok: false, problems }
|
|
248
|
+
: {
|
|
249
|
+
ok: true,
|
|
250
|
+
declaration: pinned,
|
|
251
|
+
changed: stored === undefined || stored === null || stored.runtime !== runtime,
|
|
252
|
+
};
|
|
253
|
+
}
|
|
254
|
+
const problems = declarationProblems(given, config, runtime);
|
|
255
|
+
if (problems.length > 0) {
|
|
256
|
+
return { ok: false, problems };
|
|
257
|
+
}
|
|
258
|
+
const declaration = { capabilities: given as CapabilityDeclaration, runtime };
|
|
259
|
+
return {
|
|
260
|
+
ok: true,
|
|
261
|
+
declaration,
|
|
262
|
+
changed:
|
|
263
|
+
stored === undefined ||
|
|
264
|
+
stored === null ||
|
|
265
|
+
stored.runtime !== runtime ||
|
|
266
|
+
JSON.stringify(stored.capabilities) !== JSON.stringify(declaration.capabilities),
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* A name a prefix can't vouch for (after the review): a dot segment, or one written with an
|
|
272
|
+
* escape or a backslash, may resolve outside the prefix (`app://tasks/../secrets`).
|
|
273
|
+
*/
|
|
274
|
+
const ESCAPES_PREFIX = /(^|[/\\])\.{1,2}([/\\?#]|$)|%2e|%2f|%5c|\\/iu;
|
|
275
|
+
|
|
276
|
+
/** Whether `name` matches a declared list's entry (exact, or a prefix ending in `*`). */
|
|
277
|
+
export function declaredMatch(list: readonly string[] | undefined, name: string): boolean {
|
|
278
|
+
return (
|
|
279
|
+
list === undefined ||
|
|
280
|
+
list.some((each) =>
|
|
281
|
+
each.endsWith("*")
|
|
282
|
+
? name.startsWith(each.slice(0, -1)) && !ESCAPES_PREFIX.test(name)
|
|
283
|
+
: each === name,
|
|
284
|
+
)
|
|
285
|
+
);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** The stricter of two declared level maps. */
|
|
289
|
+
function stricterLevels(
|
|
290
|
+
a: Readonly<Record<string, ViewerLevel>> | undefined,
|
|
291
|
+
b: Readonly<Record<string, ViewerLevel>> | undefined,
|
|
292
|
+
): Readonly<Record<string, ViewerLevel>> | undefined {
|
|
293
|
+
if (a === undefined || b === undefined) {
|
|
294
|
+
return a ?? b;
|
|
295
|
+
}
|
|
296
|
+
const out: Record<string, ViewerLevel> = { ...a };
|
|
297
|
+
for (const [method, level] of Object.entries(b)) {
|
|
298
|
+
const other = Object.hasOwn(out, method) ? out[method] : undefined;
|
|
299
|
+
out[method] = other === undefined ? level : higher(other, level);
|
|
300
|
+
}
|
|
301
|
+
return out;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/** The names both lists admit (absent: everything). */
|
|
305
|
+
function bothNames(
|
|
306
|
+
a: readonly string[] | undefined,
|
|
307
|
+
b: readonly string[] | undefined,
|
|
308
|
+
): readonly string[] | undefined {
|
|
309
|
+
if (a === undefined || b === undefined) {
|
|
310
|
+
return a ?? b;
|
|
311
|
+
}
|
|
312
|
+
return [
|
|
313
|
+
...new Set([
|
|
314
|
+
...a.filter((each) => declaredMatch(b, each)),
|
|
315
|
+
...b.filter((each) => declaredMatch(a, each)),
|
|
316
|
+
]),
|
|
317
|
+
];
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** The stricter of two pages' rules, by collection. */
|
|
321
|
+
function stricterRules(a: DbRules | undefined, b: DbRules | undefined): DbRules | undefined {
|
|
322
|
+
if (a === undefined || b === undefined) {
|
|
323
|
+
return a ?? b;
|
|
324
|
+
}
|
|
325
|
+
const out: Record<string, { read?: ViewerLevel; write?: ViewerLevel }> = {};
|
|
326
|
+
for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
|
|
327
|
+
const x = Object.hasOwn(a, key) ? a[key] : undefined;
|
|
328
|
+
const y = Object.hasOwn(b, key) ? b[key] : undefined;
|
|
329
|
+
const read =
|
|
330
|
+
x?.read === undefined ? y?.read : y?.read === undefined ? x.read : higher(x.read, y.read);
|
|
331
|
+
const write =
|
|
332
|
+
x?.write === undefined
|
|
333
|
+
? y?.write
|
|
334
|
+
: y?.write === undefined
|
|
335
|
+
? x.write
|
|
336
|
+
: higher(x.write, y.write);
|
|
337
|
+
out[key] = {
|
|
338
|
+
...(read === undefined ? {} : { read }),
|
|
339
|
+
...(write === undefined ? {} : { write }),
|
|
340
|
+
};
|
|
341
|
+
}
|
|
342
|
+
return out;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* What a version may do when it is shown (after the review): what it declared when it was
|
|
347
|
+
* published AND what the artifact declares now. A host stores each version's declaration with
|
|
348
|
+
* it (`declareCapabilities` at its publish) and mounts a version with this, so an old version
|
|
349
|
+
* never keeps what the artifact has since revoked, nor gains what it declared later. Each
|
|
350
|
+
* capability only where both declare it, at the stricter levels, the narrower `data` names and
|
|
351
|
+
* the stricter `db` rules; the version's own pinned runtime.
|
|
352
|
+
*/
|
|
353
|
+
export function intersectDeclarations(
|
|
354
|
+
version: PageDeclaration,
|
|
355
|
+
current: PageDeclaration,
|
|
356
|
+
): PageDeclaration {
|
|
357
|
+
const capabilities: Record<string, DeclaredCapability & DeclaredData & DeclaredDb> = {};
|
|
358
|
+
const a = version.capabilities as Readonly<Record<string, DeclaredData & DeclaredDb>>;
|
|
359
|
+
const b = current.capabilities as Readonly<Record<string, DeclaredData & DeclaredDb>>;
|
|
360
|
+
for (const name of Object.keys(a)) {
|
|
361
|
+
if (!Object.hasOwn(b, name)) {
|
|
362
|
+
continue;
|
|
363
|
+
}
|
|
364
|
+
const x = a[name] ?? {};
|
|
365
|
+
const y = b[name] ?? {};
|
|
366
|
+
const levels = stricterLevels(x.levels, y.levels);
|
|
367
|
+
const resources = bothNames(x.resources, y.resources);
|
|
368
|
+
const tools = bothNames(x.tools, y.tools);
|
|
369
|
+
const rules = stricterRules(x.rules, y.rules);
|
|
370
|
+
capabilities[name] = {
|
|
371
|
+
...(levels === undefined ? {} : { levels }),
|
|
372
|
+
...(resources === undefined ? {} : { resources }),
|
|
373
|
+
...(tools === undefined ? {} : { tools }),
|
|
374
|
+
...(rules === undefined ? {} : { rules }),
|
|
375
|
+
};
|
|
376
|
+
}
|
|
377
|
+
return { capabilities, runtime: version.runtime };
|
|
378
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { isDbSegment } from "./segments.ts";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Viewer levels (P087): who the person viewing a display is to it, in the host's words, which
|
|
5
|
+
* decides each capability method's audience. Ordered: `view` (see it, comment) < `interact` (use
|
|
6
|
+
* what the page does: write its data, ask the agent) < `admin` (publish its versions, manage its
|
|
7
|
+
* assets) < `owner`. The host says a viewer's level (its access, per request); Porthole carries it
|
|
8
|
+
* and refuses a call whose method needs more, before any handler runs.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
export const VIEWER_LEVELS = ["view", "interact", "admin", "owner"] as const;
|
|
12
|
+
|
|
13
|
+
export type ViewerLevel = (typeof VIEWER_LEVELS)[number];
|
|
14
|
+
|
|
15
|
+
export function isViewerLevel(value: unknown): value is ViewerLevel {
|
|
16
|
+
return typeof value === "string" && (VIEWER_LEVELS as readonly string[]).includes(value);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Whether `level` reaches `needed`. */
|
|
20
|
+
export function atLeast(level: ViewerLevel, needed: ViewerLevel): boolean {
|
|
21
|
+
return VIEWER_LEVELS.indexOf(level) >= VIEWER_LEVELS.indexOf(needed);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** The higher of two levels. */
|
|
25
|
+
export function higher(a: ViewerLevel, b: ViewerLevel): ViewerLevel {
|
|
26
|
+
return atLeast(a, b) ? a : b;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Who is viewing a display, as the host says (its access at issue, `Grant.level`, or a mount's
|
|
31
|
+
* `viewer`): the level decides what the page may do; `id` and `name` are what the `user`
|
|
32
|
+
* capability tells a page that declares it, and `id` is whose per-user data (`data/users/<id>`)
|
|
33
|
+
* the page reaches. All the host's words, never the content's. `id` is the host's public id for
|
|
34
|
+
* the person (not necessarily the `Grant.viewer` it keeps to itself).
|
|
35
|
+
*/
|
|
36
|
+
export interface ViewerInfo {
|
|
37
|
+
readonly level: ViewerLevel;
|
|
38
|
+
/**
|
|
39
|
+
* One path segment (`A-Z a-z 0-9 _ . ~ : @ + -`, at most 128, never `me`): the host's public id
|
|
40
|
+
* for the person, or a pseudonym per artifact (`pseudonymFor`, P087), never their account id
|
|
41
|
+
* where pages shouldn't link people across artifacts.
|
|
42
|
+
*/
|
|
43
|
+
readonly id?: string;
|
|
44
|
+
readonly name?: string;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const MAX_ID = 256;
|
|
48
|
+
|
|
49
|
+
/** A viewer as the host gave it (possibly over the network: an issue's answer), or null. */
|
|
50
|
+
export function parseViewer(value: unknown): ViewerInfo | null {
|
|
51
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
54
|
+
const { level, id, name } = value as Record<string, unknown>;
|
|
55
|
+
if (!isViewerLevel(level)) {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
const text = (each: unknown) =>
|
|
59
|
+
typeof each === "string" && each !== "" && each.length <= MAX_ID && !/[\p{Cc}]/u.test(each);
|
|
60
|
+
// An id names the person's own data (`data/users/<id>`): one path segment, never `me`.
|
|
61
|
+
if ((id !== undefined && !isDbSegment(id)) || (name !== undefined && !text(name))) {
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
level,
|
|
66
|
+
...(id === undefined ? {} : { id }),
|
|
67
|
+
...(name === undefined ? {} : { name: name as string }),
|
|
68
|
+
};
|
|
69
|
+
}
|