@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,398 @@
|
|
|
1
|
+
import { atLeast, higher, isViewerLevel } from "./levels.js";
|
|
2
|
+
import { SEGMENT, isDbSegment } from "./segments.js";
|
|
3
|
+
export { isDbSegment };
|
|
4
|
+
/**
|
|
5
|
+
* The `db` capability's contract (P088): a document store the host keeps for an artifact, which
|
|
6
|
+
* its page reads and writes as the person viewing it. Porthole checks what crosses the frame (the
|
|
7
|
+
* shape, the sizes, the paths), resolves `me`, keeps a viewer to their own per-user data
|
|
8
|
+
* (`data/users/<id>`), and applies the page's per-level rules; the host stores, versions and
|
|
9
|
+
* evaluates them again on its own side (`dbAccess`), since its API is the wall for its data.
|
|
10
|
+
*
|
|
11
|
+
* Paths are slash-separated: a collection is an odd number of segments (`votes`,
|
|
12
|
+
* `rooms/r1/messages`), a document an even number (`votes/ada`). Every write to a document that
|
|
13
|
+
* exists names the version it read (`ifVersion`); a mismatch is a `conflict`.
|
|
14
|
+
*/
|
|
15
|
+
export const DB_LIMITS = {
|
|
16
|
+
/** The most a document's data holds, JSON bytes. */
|
|
17
|
+
maxDocBytes: 1_048_576,
|
|
18
|
+
/** The most writes one batch holds, and their bytes together. */
|
|
19
|
+
maxBatchWrites: 50,
|
|
20
|
+
maxBatchBytes: 1_048_576,
|
|
21
|
+
/** The most documents one query answers. */
|
|
22
|
+
maxQueryLimit: 500,
|
|
23
|
+
maxWhere: 10,
|
|
24
|
+
/** The most values an `in` holds. */
|
|
25
|
+
maxIn: 30,
|
|
26
|
+
/** The most segments a path holds (a document: 16; a collection: 15). */
|
|
27
|
+
maxSegments: 16,
|
|
28
|
+
/** The deepest a document's data nests. */
|
|
29
|
+
maxDepth: 32,
|
|
30
|
+
/** The most watches one frame keeps at once. */
|
|
31
|
+
maxWatches: 50,
|
|
32
|
+
/** The most values (objects, arrays, scalars) one document holds, and one batch. */
|
|
33
|
+
maxNodes: 100_000,
|
|
34
|
+
/** The most a `where` operand holds: values, and JSON bytes. */
|
|
35
|
+
maxOperandNodes: 1_000,
|
|
36
|
+
maxOperandBytes: 16_384,
|
|
37
|
+
};
|
|
38
|
+
/** The per-user subtree: `data/users/<id>/…`, the viewer's own; `me` names the viewer. */
|
|
39
|
+
export const DB_USERS_PREFIX = "data/users/";
|
|
40
|
+
/** A path's segments, or null for one that names nothing (empty, dot segments, odd characters). */
|
|
41
|
+
export function dbSegments(path) {
|
|
42
|
+
if (typeof path !== "string" || path === "" || path.length > 2_048) {
|
|
43
|
+
return null;
|
|
44
|
+
}
|
|
45
|
+
const segments = path.split("/");
|
|
46
|
+
if (segments.length > DB_LIMITS.maxSegments ||
|
|
47
|
+
segments.some((each) => !SEGMENT.test(each) || each === "." || each === "..")) {
|
|
48
|
+
return null;
|
|
49
|
+
}
|
|
50
|
+
return segments;
|
|
51
|
+
}
|
|
52
|
+
/** Whether `path` names a document (`even`) or a collection (`odd`). */
|
|
53
|
+
export function dbPathKind(segments) {
|
|
54
|
+
return segments.length % 2 === 0 ? "doc" : "collection";
|
|
55
|
+
}
|
|
56
|
+
/** Field names a document never holds: a host merging them could set a prototype (P088). */
|
|
57
|
+
const RESERVED_FIELDS = new Set(["__proto__", "constructor", "prototype"]);
|
|
58
|
+
/**
|
|
59
|
+
* Whether `value` is plain JSON data within `budget` nodes, no deeper than the limit, with no
|
|
60
|
+
* object or array reached twice (P088, after the review: structured clone keeps shared
|
|
61
|
+
* references, so a walk without this is exponential in a message of a few dozen objects). Each
|
|
62
|
+
* node is visited once: linear in what was sent, and stopped at the budget.
|
|
63
|
+
*/
|
|
64
|
+
function plainJson(value, budget, depth) {
|
|
65
|
+
budget.nodes -= 1;
|
|
66
|
+
if (budget.nodes < 0 || depth > DB_LIMITS.maxDepth) {
|
|
67
|
+
return false;
|
|
68
|
+
}
|
|
69
|
+
if (value === null || typeof value === "boolean" || typeof value === "string") {
|
|
70
|
+
return true;
|
|
71
|
+
}
|
|
72
|
+
if (typeof value === "number") {
|
|
73
|
+
return Number.isFinite(value);
|
|
74
|
+
}
|
|
75
|
+
if (typeof value !== "object") {
|
|
76
|
+
return false;
|
|
77
|
+
}
|
|
78
|
+
if (budget.seen.has(value)) {
|
|
79
|
+
return false;
|
|
80
|
+
}
|
|
81
|
+
budget.seen.add(value);
|
|
82
|
+
if (Array.isArray(value)) {
|
|
83
|
+
for (const each of value) {
|
|
84
|
+
if (!plainJson(each, budget, depth + 1)) {
|
|
85
|
+
return false;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return true;
|
|
89
|
+
}
|
|
90
|
+
const proto = Object.getPrototypeOf(value);
|
|
91
|
+
if (proto !== Object.prototype && proto !== null) {
|
|
92
|
+
return false;
|
|
93
|
+
}
|
|
94
|
+
for (const field of Object.keys(value)) {
|
|
95
|
+
if (field === "" || field.length > 256 || RESERVED_FIELDS.has(field)) {
|
|
96
|
+
return false;
|
|
97
|
+
}
|
|
98
|
+
if (!plainJson(value[field], budget, depth + 1)) {
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return true;
|
|
103
|
+
}
|
|
104
|
+
/** Whether `value` is plain JSON within `nodes` nodes (a document's, a `where` operand's). */
|
|
105
|
+
export function isPlainJson(value, nodes = DB_LIMITS.maxNodes) {
|
|
106
|
+
return plainJson(value, { nodes, seen: new WeakSet() }, 0);
|
|
107
|
+
}
|
|
108
|
+
const encoder = new TextEncoder();
|
|
109
|
+
/** The bytes `value` takes as JSON. */
|
|
110
|
+
export const jsonBytes = (value) => encoder.encode(JSON.stringify(value)).length;
|
|
111
|
+
/** A document's data: a plain object, within the limits; "too_large" past them. */
|
|
112
|
+
function dbData(value, budget = {
|
|
113
|
+
nodes: DB_LIMITS.maxNodes,
|
|
114
|
+
seen: new WeakSet(),
|
|
115
|
+
}) {
|
|
116
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
117
|
+
return null;
|
|
118
|
+
}
|
|
119
|
+
if (!plainJson(value, budget, 0)) {
|
|
120
|
+
return null;
|
|
121
|
+
}
|
|
122
|
+
return jsonBytes(value) > DB_LIMITS.maxDocBytes ? "too_large" : value;
|
|
123
|
+
}
|
|
124
|
+
const version = (value) => value === undefined
|
|
125
|
+
? undefined
|
|
126
|
+
: typeof value === "number" && Number.isSafeInteger(value) && value >= 0
|
|
127
|
+
? value
|
|
128
|
+
: null;
|
|
129
|
+
const WHERE_OPS = ["==", "!=", "<", "<=", ">", ">=", "in", "array-contains"];
|
|
130
|
+
function parseWrite(value, op, budget) {
|
|
131
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
132
|
+
return null;
|
|
133
|
+
}
|
|
134
|
+
const raw = value;
|
|
135
|
+
const kind = op ?? raw.op;
|
|
136
|
+
const segments = dbSegments(raw.path);
|
|
137
|
+
const ifVersion = version(raw.ifVersion);
|
|
138
|
+
if (segments === null || dbPathKind(segments) !== "doc" || ifVersion === null) {
|
|
139
|
+
return null;
|
|
140
|
+
}
|
|
141
|
+
const path = segments.join("/");
|
|
142
|
+
const at = ifVersion === undefined ? {} : { ifVersion };
|
|
143
|
+
if (kind === "delete") {
|
|
144
|
+
return { op: "delete", path, ...at };
|
|
145
|
+
}
|
|
146
|
+
if (kind !== "set" && kind !== "update") {
|
|
147
|
+
return null;
|
|
148
|
+
}
|
|
149
|
+
const data = dbData(raw.data, budget);
|
|
150
|
+
if (data === null || data === "too_large") {
|
|
151
|
+
return data;
|
|
152
|
+
}
|
|
153
|
+
return { op: kind, path, data, ...at };
|
|
154
|
+
}
|
|
155
|
+
function parseWhere(value) {
|
|
156
|
+
if (value === undefined) {
|
|
157
|
+
return undefined;
|
|
158
|
+
}
|
|
159
|
+
if (!Array.isArray(value) || value.length > DB_LIMITS.maxWhere) {
|
|
160
|
+
return null;
|
|
161
|
+
}
|
|
162
|
+
const out = [];
|
|
163
|
+
for (const each of value) {
|
|
164
|
+
if (!Array.isArray(each) || each.length !== 3) {
|
|
165
|
+
return null;
|
|
166
|
+
}
|
|
167
|
+
const [field, op, operand] = each;
|
|
168
|
+
if (typeof field !== "string" ||
|
|
169
|
+
field === "" ||
|
|
170
|
+
field.length > 256 ||
|
|
171
|
+
!WHERE_OPS.includes(op) ||
|
|
172
|
+
!isPlainJson(operand, DB_LIMITS.maxOperandNodes) ||
|
|
173
|
+
jsonBytes(operand) > DB_LIMITS.maxOperandBytes ||
|
|
174
|
+
(op === "in" && (!Array.isArray(operand) || operand.length > DB_LIMITS.maxIn))) {
|
|
175
|
+
return null;
|
|
176
|
+
}
|
|
177
|
+
out.push([field, op, operand]);
|
|
178
|
+
}
|
|
179
|
+
return out;
|
|
180
|
+
}
|
|
181
|
+
/** A `db` call's arguments as content sent them, checked: null (malformed), "too_large", or the call. */
|
|
182
|
+
export function parseDbRequest(args) {
|
|
183
|
+
if (args === null || typeof args !== "object" || Array.isArray(args)) {
|
|
184
|
+
return null;
|
|
185
|
+
}
|
|
186
|
+
const raw = args;
|
|
187
|
+
switch (raw.op) {
|
|
188
|
+
case "get":
|
|
189
|
+
case "watch": {
|
|
190
|
+
const segments = dbSegments(raw.path);
|
|
191
|
+
if (segments === null || (raw.op === "get" && dbPathKind(segments) !== "doc")) {
|
|
192
|
+
return null;
|
|
193
|
+
}
|
|
194
|
+
return { op: raw.op, path: segments.join("/") };
|
|
195
|
+
}
|
|
196
|
+
case "set":
|
|
197
|
+
case "update":
|
|
198
|
+
case "delete":
|
|
199
|
+
return parseWrite(raw, raw.op);
|
|
200
|
+
case "query": {
|
|
201
|
+
const segments = dbSegments(raw.collection);
|
|
202
|
+
const where = parseWhere(raw.where);
|
|
203
|
+
if (segments === null || dbPathKind(segments) !== "collection" || where === null) {
|
|
204
|
+
return null;
|
|
205
|
+
}
|
|
206
|
+
let orderBy;
|
|
207
|
+
if (raw.orderBy !== undefined) {
|
|
208
|
+
const order = raw.orderBy;
|
|
209
|
+
if (order === null ||
|
|
210
|
+
typeof order !== "object" ||
|
|
211
|
+
typeof order.field !== "string" ||
|
|
212
|
+
order.field === "" ||
|
|
213
|
+
order.field.length > 256 ||
|
|
214
|
+
(order.direction !== undefined && order.direction !== "asc" && order.direction !== "desc")) {
|
|
215
|
+
return null;
|
|
216
|
+
}
|
|
217
|
+
orderBy = { field: order.field, direction: order.direction === "desc" ? "desc" : "asc" };
|
|
218
|
+
}
|
|
219
|
+
const limit = raw.limit;
|
|
220
|
+
if (limit !== undefined &&
|
|
221
|
+
(typeof limit !== "number" ||
|
|
222
|
+
!Number.isInteger(limit) ||
|
|
223
|
+
limit < 1 ||
|
|
224
|
+
limit > DB_LIMITS.maxQueryLimit)) {
|
|
225
|
+
return null;
|
|
226
|
+
}
|
|
227
|
+
return {
|
|
228
|
+
op: "query",
|
|
229
|
+
collection: segments.join("/"),
|
|
230
|
+
...(where === undefined ? {} : { where }),
|
|
231
|
+
...(orderBy === undefined ? {} : { orderBy }),
|
|
232
|
+
...(limit === undefined ? {} : { limit }),
|
|
233
|
+
};
|
|
234
|
+
}
|
|
235
|
+
case "batch": {
|
|
236
|
+
const writes = raw.writes;
|
|
237
|
+
if (!Array.isArray(writes) || writes.length === 0) {
|
|
238
|
+
return null;
|
|
239
|
+
}
|
|
240
|
+
if (writes.length > DB_LIMITS.maxBatchWrites) {
|
|
241
|
+
return "too_large";
|
|
242
|
+
}
|
|
243
|
+
const parsed = [];
|
|
244
|
+
// One budget for the whole batch, and one write a path: a batch is checked against one
|
|
245
|
+
// state, so two writes to a path would both pass it.
|
|
246
|
+
const budget = { nodes: DB_LIMITS.maxNodes, seen: new WeakSet() };
|
|
247
|
+
const paths = new Set();
|
|
248
|
+
for (const each of writes) {
|
|
249
|
+
const write = parseWrite(each, undefined, budget);
|
|
250
|
+
if (write === null || write === "too_large") {
|
|
251
|
+
return write;
|
|
252
|
+
}
|
|
253
|
+
if (paths.has(write.path)) {
|
|
254
|
+
return null;
|
|
255
|
+
}
|
|
256
|
+
paths.add(write.path);
|
|
257
|
+
parsed.push(write);
|
|
258
|
+
}
|
|
259
|
+
if (jsonBytes(parsed) > DB_LIMITS.maxBatchBytes) {
|
|
260
|
+
return "too_large";
|
|
261
|
+
}
|
|
262
|
+
return { op: "batch", writes: parsed };
|
|
263
|
+
}
|
|
264
|
+
default:
|
|
265
|
+
return null;
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
/** A rules object's problem, or null. */
|
|
269
|
+
export function dbRulesProblem(value) {
|
|
270
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
271
|
+
return "must be an object of { read?, write } levels by collection";
|
|
272
|
+
}
|
|
273
|
+
const entries = Object.entries(value);
|
|
274
|
+
if (entries.length > 100) {
|
|
275
|
+
return "may name at most 100 collections";
|
|
276
|
+
}
|
|
277
|
+
for (const [collection, rule] of entries) {
|
|
278
|
+
if (collection !== "*" && !SEGMENT.test(collection)) {
|
|
279
|
+
return `${JSON.stringify(collection)} is not a collection name (or "*")`;
|
|
280
|
+
}
|
|
281
|
+
if (rule === null || typeof rule !== "object" || Array.isArray(rule)) {
|
|
282
|
+
return `${collection}: must be { read?, write? }`;
|
|
283
|
+
}
|
|
284
|
+
for (const [key, level] of Object.entries(rule)) {
|
|
285
|
+
if ((key !== "read" && key !== "write") || !isViewerLevel(level)) {
|
|
286
|
+
return `${collection}.${key}: must be read or write, a level (view, interact, admin, owner)`;
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
return null;
|
|
291
|
+
}
|
|
292
|
+
/** Whether an op reads or writes. */
|
|
293
|
+
const writes = (op) => op === "set" || op === "update" || op === "delete" || op === "batch";
|
|
294
|
+
/** The paths a call touches. */
|
|
295
|
+
function pathsOf(request) {
|
|
296
|
+
switch (request.op) {
|
|
297
|
+
case "query":
|
|
298
|
+
return [request.collection];
|
|
299
|
+
case "batch":
|
|
300
|
+
return request.writes.map((each) => each.path);
|
|
301
|
+
default:
|
|
302
|
+
return [request.path];
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
/** `path` with `me` resolved to the viewer, or null where it names someone else's data. */
|
|
306
|
+
function ownPath(path, viewer) {
|
|
307
|
+
const segments = path.split("/");
|
|
308
|
+
// `data`, however a store folds its case (after the review: `Data/users/<id>` is no way round).
|
|
309
|
+
if (segments[0]?.toLowerCase() !== "data") {
|
|
310
|
+
return path;
|
|
311
|
+
}
|
|
312
|
+
if (segments[0] !== "data") {
|
|
313
|
+
return null;
|
|
314
|
+
}
|
|
315
|
+
// `data` holds only per-user trees: `data/users/<id>/…`, the viewer's own.
|
|
316
|
+
if (segments[1] !== "users" || segments.length < 3) {
|
|
317
|
+
return null;
|
|
318
|
+
}
|
|
319
|
+
if (!isDbSegment(viewer?.id)) {
|
|
320
|
+
return null;
|
|
321
|
+
}
|
|
322
|
+
const id = segments[2] === "me" ? viewer?.id : segments[2];
|
|
323
|
+
if (id === undefined || viewer?.id === undefined || id !== viewer.id) {
|
|
324
|
+
return null;
|
|
325
|
+
}
|
|
326
|
+
segments[2] = id;
|
|
327
|
+
return segments.join("/");
|
|
328
|
+
}
|
|
329
|
+
/** The least level a rule asks for `path`. */
|
|
330
|
+
function ruleLevel(rules, path, write) {
|
|
331
|
+
const base = write ? "interact" : "view";
|
|
332
|
+
const top = path.split("/")[0] ?? "";
|
|
333
|
+
// Own rules only: a collection named `constructor` or `__proto__` is no rule (after the review).
|
|
334
|
+
const own = (key) => rules !== undefined && Object.hasOwn(rules, key) ? rules[key] : undefined;
|
|
335
|
+
const rule = own(top) ?? own("*");
|
|
336
|
+
const asked = write ? rule?.write : rule?.read;
|
|
337
|
+
return asked === undefined ? base : higher(base, asked);
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Whether `viewer` may make `request` under `rules` (P088), and the call with `me` resolved:
|
|
341
|
+
* someone else's per-user data is refused at every level, and so is any path under `data` that
|
|
342
|
+
* isn't `data/users/<own id>/…`; then each path's rule. The bridge applies it before the host's
|
|
343
|
+
* handler; a host applies it again in its own API (its data's wall).
|
|
344
|
+
*/
|
|
345
|
+
export function dbAccess(request, viewer, rules) {
|
|
346
|
+
if (viewer === undefined) {
|
|
347
|
+
return { ok: false };
|
|
348
|
+
}
|
|
349
|
+
const resolve = (path) => ownPath(path, viewer);
|
|
350
|
+
for (const path of pathsOf(request)) {
|
|
351
|
+
const own = resolve(path);
|
|
352
|
+
if (own === null || !atLeast(viewer.level, ruleLevel(rules, own, writes(request.op)))) {
|
|
353
|
+
return { ok: false };
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
switch (request.op) {
|
|
357
|
+
case "query":
|
|
358
|
+
return { ok: true, request: { ...request, collection: resolve(request.collection) ?? "" } };
|
|
359
|
+
case "batch":
|
|
360
|
+
return {
|
|
361
|
+
ok: true,
|
|
362
|
+
request: {
|
|
363
|
+
op: "batch",
|
|
364
|
+
writes: request.writes.map((each) => ({ ...each, path: resolve(each.path) ?? "" })),
|
|
365
|
+
},
|
|
366
|
+
};
|
|
367
|
+
default:
|
|
368
|
+
return { ok: true, request: { ...request, path: resolve(request.path) ?? "" } };
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
/**
|
|
372
|
+
* A `db` answer as content gets it (P088, after the review): every path in the viewer's own tree
|
|
373
|
+
* says `data/users/me`, never their id, so a page that didn't declare `user` doesn't learn who is
|
|
374
|
+
* viewing from its own data's paths. Snapshots and `{ docs }`; anything else as it is.
|
|
375
|
+
*/
|
|
376
|
+
export function withMe(value, viewer) {
|
|
377
|
+
const id = viewer?.id;
|
|
378
|
+
if (id === undefined || value === null || typeof value !== "object") {
|
|
379
|
+
return value;
|
|
380
|
+
}
|
|
381
|
+
const own = `${DB_USERS_PREFIX}${id}`;
|
|
382
|
+
const path = (each) => {
|
|
383
|
+
if (each === null || typeof each !== "object" || Array.isArray(each)) {
|
|
384
|
+
return each;
|
|
385
|
+
}
|
|
386
|
+
const snapshot = each;
|
|
387
|
+
if (typeof snapshot.path === "string" &&
|
|
388
|
+
(snapshot.path === own || snapshot.path.startsWith(`${own}/`))) {
|
|
389
|
+
return { ...snapshot, path: `${DB_USERS_PREFIX}me${snapshot.path.slice(own.length)}` };
|
|
390
|
+
}
|
|
391
|
+
return each;
|
|
392
|
+
};
|
|
393
|
+
const docs = value.docs;
|
|
394
|
+
if (Array.isArray(docs)) {
|
|
395
|
+
return { ...value, docs: docs.map(path) };
|
|
396
|
+
}
|
|
397
|
+
return path(value);
|
|
398
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import { type RuntimeVersion } from "./contract.ts";
|
|
3
|
+
import { type DbRules } from "./db.ts";
|
|
4
|
+
import { type ViewerLevel } from "./levels.ts";
|
|
5
|
+
/**
|
|
6
|
+
* A page's declaration (P086): the capabilities it uses, by name, each with its own config,
|
|
7
|
+
* stored with the artifact when it is published and handed to `mount` when it is shown; and the
|
|
8
|
+
* runtime contract it was written against, pinned. Built-ins are never declared.
|
|
9
|
+
*
|
|
10
|
+
* At publish (`declareCapabilities`): omitted carries the stored declaration forward (and its
|
|
11
|
+
* pin); `{}` clears it; a non-empty object replaces it whole. A page can't change its own: a
|
|
12
|
+
* publish from the page (`artifact.publish`) carries none.
|
|
13
|
+
*/
|
|
14
|
+
/** Every capability's config may raise its methods' levels (never lower them). */
|
|
15
|
+
export interface DeclaredCapability {
|
|
16
|
+
readonly levels?: Readonly<Record<string, ViewerLevel>>;
|
|
17
|
+
}
|
|
18
|
+
/** `data`: which of the host's resources and tools the page uses (absent: all it serves). */
|
|
19
|
+
export interface DeclaredData extends DeclaredCapability {
|
|
20
|
+
/** URIs, exact, or a prefix ending in `*` (`app://tasks/*`). */
|
|
21
|
+
readonly resources?: readonly string[];
|
|
22
|
+
readonly tools?: readonly string[];
|
|
23
|
+
}
|
|
24
|
+
/** `db`: the page's rules for its data, by top-level collection (`DbRules`). */
|
|
25
|
+
export interface DeclaredDb extends DeclaredCapability {
|
|
26
|
+
readonly rules?: DbRules;
|
|
27
|
+
}
|
|
28
|
+
/** What a page declares, by runtime capability name. */
|
|
29
|
+
export interface CapabilityDeclaration {
|
|
30
|
+
readonly user?: DeclaredCapability;
|
|
31
|
+
readonly chat?: DeclaredCapability;
|
|
32
|
+
readonly data?: DeclaredData;
|
|
33
|
+
readonly context?: DeclaredCapability;
|
|
34
|
+
readonly artifact?: DeclaredCapability;
|
|
35
|
+
readonly assets?: DeclaredCapability;
|
|
36
|
+
readonly db?: DeclaredDb;
|
|
37
|
+
}
|
|
38
|
+
/** A declaration as an artifact stores it and a mount is given it. */
|
|
39
|
+
export interface PageDeclaration {
|
|
40
|
+
readonly capabilities: CapabilityDeclaration;
|
|
41
|
+
readonly runtime: RuntimeVersion;
|
|
42
|
+
}
|
|
43
|
+
export interface DeclarationProblem {
|
|
44
|
+
/** Where, as `capabilities.db.rules.votes`. */
|
|
45
|
+
readonly path: string;
|
|
46
|
+
readonly message: string;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The problems with a declaration, against the host's offer (`config`): each name one the
|
|
50
|
+
* runtime knows, the config offers and isn't built in; each config of its own shape. Empty: fine.
|
|
51
|
+
*/
|
|
52
|
+
export declare function declarationProblems(given: unknown, config: PortholeConfig, runtime?: RuntimeVersion): DeclarationProblem[];
|
|
53
|
+
/** A declaration checked (a host's stored one, given to `mount`); throws a `TypeError` naming its problems. */
|
|
54
|
+
export declare function checkDeclaration(given: unknown, config: PortholeConfig): PageDeclaration;
|
|
55
|
+
/**
|
|
56
|
+
* At publish (P086): the declaration a new version leaves the artifact with.
|
|
57
|
+
* - `given` undefined: the stored one, unchanged (its pin too); none stored: an empty one.
|
|
58
|
+
* - `given` `{}`: cleared.
|
|
59
|
+
* - `given` non-empty: it replaces the stored one whole (anything not restated is revoked).
|
|
60
|
+
* The pin moves only when the author asks (`runtime`). Checked against the host's offer.
|
|
61
|
+
*/
|
|
62
|
+
export declare function declareCapabilities(options: {
|
|
63
|
+
readonly stored?: PageDeclaration | null;
|
|
64
|
+
readonly given?: unknown;
|
|
65
|
+
readonly config: PortholeConfig;
|
|
66
|
+
readonly runtime?: unknown;
|
|
67
|
+
}): {
|
|
68
|
+
readonly ok: true;
|
|
69
|
+
readonly declaration: PageDeclaration;
|
|
70
|
+
/** Whether it differs from the stored one. */
|
|
71
|
+
readonly changed: boolean;
|
|
72
|
+
} | {
|
|
73
|
+
readonly ok: false;
|
|
74
|
+
readonly problems: readonly DeclarationProblem[];
|
|
75
|
+
};
|
|
76
|
+
/** Whether `name` matches a declared list's entry (exact, or a prefix ending in `*`). */
|
|
77
|
+
export declare function declaredMatch(list: readonly string[] | undefined, name: string): boolean;
|
|
78
|
+
/**
|
|
79
|
+
* What a version may do when it is shown (after the review): what it declared when it was
|
|
80
|
+
* published AND what the artifact declares now. A host stores each version's declaration with
|
|
81
|
+
* it (`declareCapabilities` at its publish) and mounts a version with this, so an old version
|
|
82
|
+
* never keeps what the artifact has since revoked, nor gains what it declared later. Each
|
|
83
|
+
* capability only where both declare it, at the stricter levels, the narrower `data` names and
|
|
84
|
+
* the stricter `db` rules; the version's own pinned runtime.
|
|
85
|
+
*/
|
|
86
|
+
export declare function intersectDeclarations(version: PageDeclaration, current: PageDeclaration): PageDeclaration;
|