@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,650 @@
|
|
|
1
|
+
import { atLeast, higher, isViewerLevel, type ViewerInfo, type ViewerLevel } from "./levels.ts";
|
|
2
|
+
import { SEGMENT, isDbSegment } from "./segments.ts";
|
|
3
|
+
|
|
4
|
+
export { isDbSegment };
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The `db` capability's contract (P088): a document store the host keeps for an artifact, which
|
|
8
|
+
* its page reads and writes as the person viewing it. Porthole checks what crosses the frame (the
|
|
9
|
+
* shape, the sizes, the paths), resolves `me`, keeps a viewer to their own per-user data
|
|
10
|
+
* (`data/users/<id>`), and applies the page's per-level rules; the host stores, versions and
|
|
11
|
+
* evaluates them again on its own side (`dbAccess`), since its API is the wall for its data.
|
|
12
|
+
*
|
|
13
|
+
* Paths are slash-separated: a collection is an odd number of segments (`votes`,
|
|
14
|
+
* `rooms/r1/messages`), a document an even number (`votes/ada`). Every write to a document that
|
|
15
|
+
* exists names the version it read (`ifVersion`); a mismatch is a `conflict`.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
export const DB_LIMITS = {
|
|
19
|
+
/** The most a document's data holds, JSON bytes. */
|
|
20
|
+
maxDocBytes: 1_048_576,
|
|
21
|
+
/** The most writes one batch holds, and their bytes together. */
|
|
22
|
+
maxBatchWrites: 50,
|
|
23
|
+
maxBatchBytes: 1_048_576,
|
|
24
|
+
/** The most documents one query answers. */
|
|
25
|
+
maxQueryLimit: 500,
|
|
26
|
+
maxWhere: 10,
|
|
27
|
+
/** The most values an `in` holds. */
|
|
28
|
+
maxIn: 30,
|
|
29
|
+
/** The most segments a path holds (a document: 16; a collection: 15). */
|
|
30
|
+
maxSegments: 16,
|
|
31
|
+
/** The deepest a document's data nests. */
|
|
32
|
+
maxDepth: 32,
|
|
33
|
+
/** The most watches one frame keeps at once. */
|
|
34
|
+
maxWatches: 50,
|
|
35
|
+
/** The most values (objects, arrays, scalars) one document holds, and one batch. */
|
|
36
|
+
maxNodes: 100_000,
|
|
37
|
+
/** The most a `where` operand holds: values, and JSON bytes. */
|
|
38
|
+
maxOperandNodes: 1_000,
|
|
39
|
+
maxOperandBytes: 16_384,
|
|
40
|
+
} as const;
|
|
41
|
+
|
|
42
|
+
/** The per-user subtree: `data/users/<id>/…`, the viewer's own; `me` names the viewer. */
|
|
43
|
+
export const DB_USERS_PREFIX = "data/users/";
|
|
44
|
+
|
|
45
|
+
/** A path's segments, or null for one that names nothing (empty, dot segments, odd characters). */
|
|
46
|
+
export function dbSegments(path: unknown): string[] | null {
|
|
47
|
+
if (typeof path !== "string" || path === "" || path.length > 2_048) {
|
|
48
|
+
return null;
|
|
49
|
+
}
|
|
50
|
+
const segments = path.split("/");
|
|
51
|
+
if (
|
|
52
|
+
segments.length > DB_LIMITS.maxSegments ||
|
|
53
|
+
segments.some((each) => !SEGMENT.test(each) || each === "." || each === "..")
|
|
54
|
+
) {
|
|
55
|
+
return null;
|
|
56
|
+
}
|
|
57
|
+
return segments;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Whether `path` names a document (`even`) or a collection (`odd`). */
|
|
61
|
+
export function dbPathKind(segments: readonly string[]): "doc" | "collection" {
|
|
62
|
+
return segments.length % 2 === 0 ? "doc" : "collection";
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** A JSON value Porthole passes on: plain data, no cycles, no deeper than `maxDepth`. */
|
|
66
|
+
export type DbValue =
|
|
67
|
+
| null
|
|
68
|
+
| boolean
|
|
69
|
+
| number
|
|
70
|
+
| string
|
|
71
|
+
| readonly DbValue[]
|
|
72
|
+
| { readonly [field: string]: DbValue };
|
|
73
|
+
|
|
74
|
+
export type DbData = { readonly [field: string]: DbValue };
|
|
75
|
+
|
|
76
|
+
/** Field names a document never holds: a host merging them could set a prototype (P088). */
|
|
77
|
+
const RESERVED_FIELDS = new Set(["__proto__", "constructor", "prototype"]);
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Whether `value` is plain JSON data within `budget` nodes, no deeper than the limit, with no
|
|
81
|
+
* object or array reached twice (P088, after the review: structured clone keeps shared
|
|
82
|
+
* references, so a walk without this is exponential in a message of a few dozen objects). Each
|
|
83
|
+
* node is visited once: linear in what was sent, and stopped at the budget.
|
|
84
|
+
*/
|
|
85
|
+
function plainJson(
|
|
86
|
+
value: unknown,
|
|
87
|
+
budget: { nodes: number; readonly seen: WeakSet<object> },
|
|
88
|
+
depth: number,
|
|
89
|
+
): boolean {
|
|
90
|
+
budget.nodes -= 1;
|
|
91
|
+
if (budget.nodes < 0 || depth > DB_LIMITS.maxDepth) {
|
|
92
|
+
return false;
|
|
93
|
+
}
|
|
94
|
+
if (value === null || typeof value === "boolean" || typeof value === "string") {
|
|
95
|
+
return true;
|
|
96
|
+
}
|
|
97
|
+
if (typeof value === "number") {
|
|
98
|
+
return Number.isFinite(value);
|
|
99
|
+
}
|
|
100
|
+
if (typeof value !== "object") {
|
|
101
|
+
return false;
|
|
102
|
+
}
|
|
103
|
+
if (budget.seen.has(value)) {
|
|
104
|
+
return false;
|
|
105
|
+
}
|
|
106
|
+
budget.seen.add(value);
|
|
107
|
+
if (Array.isArray(value)) {
|
|
108
|
+
for (const each of value) {
|
|
109
|
+
if (!plainJson(each, budget, depth + 1)) {
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
return true;
|
|
114
|
+
}
|
|
115
|
+
const proto = Object.getPrototypeOf(value) as unknown;
|
|
116
|
+
if (proto !== Object.prototype && proto !== null) {
|
|
117
|
+
return false;
|
|
118
|
+
}
|
|
119
|
+
for (const field of Object.keys(value)) {
|
|
120
|
+
if (field === "" || field.length > 256 || RESERVED_FIELDS.has(field)) {
|
|
121
|
+
return false;
|
|
122
|
+
}
|
|
123
|
+
if (!plainJson((value as Record<string, unknown>)[field], budget, depth + 1)) {
|
|
124
|
+
return false;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
return true;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Whether `value` is plain JSON within `nodes` nodes (a document's, a `where` operand's). */
|
|
131
|
+
export function isPlainJson(value: unknown, nodes: number = DB_LIMITS.maxNodes): boolean {
|
|
132
|
+
return plainJson(value, { nodes, seen: new WeakSet() }, 0);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const encoder = new TextEncoder();
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The fewest bytes checked plain JSON takes written out: each string's and key's characters (a
|
|
139
|
+
* character is a byte or more in UTF-8, an escape more), a byte a scalar. Stops past `max`.
|
|
140
|
+
*/
|
|
141
|
+
function leastJsonBytes(value: unknown, max: number): number {
|
|
142
|
+
if (typeof value === "string") {
|
|
143
|
+
return value.length + 2;
|
|
144
|
+
}
|
|
145
|
+
if (value === null || typeof value !== "object") {
|
|
146
|
+
return 1;
|
|
147
|
+
}
|
|
148
|
+
// The brackets, and a separator before each value but the first.
|
|
149
|
+
let total = 2;
|
|
150
|
+
let first = true;
|
|
151
|
+
if (Array.isArray(value)) {
|
|
152
|
+
for (const each of value as readonly unknown[]) {
|
|
153
|
+
total += (first ? 0 : 1) + leastJsonBytes(each, max - total);
|
|
154
|
+
first = false;
|
|
155
|
+
if (total > max) {
|
|
156
|
+
return total;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
return total;
|
|
160
|
+
}
|
|
161
|
+
for (const [field, each] of Object.entries(value)) {
|
|
162
|
+
// `"field":` and the value.
|
|
163
|
+
total += (first ? 0 : 1) + field.length + 3 + leastJsonBytes(each, max - total);
|
|
164
|
+
first = false;
|
|
165
|
+
if (total > max) {
|
|
166
|
+
return total;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
return total;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* The bytes checked plain JSON takes (`plainJson` first: no cycles, bounded nodes and depth), or
|
|
174
|
+
* `max + 1` once it surely takes more: written out only within its limit (P095: a string of
|
|
175
|
+
* control characters is six times its length as JSON, and could pass a string's longest).
|
|
176
|
+
*/
|
|
177
|
+
export const jsonBytes = (value: unknown, max: number): number =>
|
|
178
|
+
leastJsonBytes(value, max) > max ? max + 1 : encoder.encode(JSON.stringify(value)).length;
|
|
179
|
+
|
|
180
|
+
/** A document's data: a plain object, within the limits; "too_large" past them. */
|
|
181
|
+
function dbData(
|
|
182
|
+
value: unknown,
|
|
183
|
+
budget: { nodes: number; readonly seen: WeakSet<object> } = {
|
|
184
|
+
nodes: DB_LIMITS.maxNodes,
|
|
185
|
+
seen: new WeakSet(),
|
|
186
|
+
},
|
|
187
|
+
): DbData | "too_large" | null {
|
|
188
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
189
|
+
return null;
|
|
190
|
+
}
|
|
191
|
+
if (!plainJson(value, budget, 0)) {
|
|
192
|
+
return null;
|
|
193
|
+
}
|
|
194
|
+
return jsonBytes(value, DB_LIMITS.maxDocBytes) > DB_LIMITS.maxDocBytes
|
|
195
|
+
? "too_large"
|
|
196
|
+
: (value as DbData);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
const version = (value: unknown): number | null | undefined =>
|
|
200
|
+
value === undefined
|
|
201
|
+
? undefined
|
|
202
|
+
: typeof value === "number" && Number.isSafeInteger(value) && value >= 0
|
|
203
|
+
? value
|
|
204
|
+
: null;
|
|
205
|
+
|
|
206
|
+
export type DbWhereOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "array-contains";
|
|
207
|
+
|
|
208
|
+
const WHERE_OPS: readonly DbWhereOp[] = ["==", "!=", "<", "<=", ">", ">=", "in", "array-contains"];
|
|
209
|
+
|
|
210
|
+
export type DbWhere = readonly [field: string, op: DbWhereOp, value: DbValue];
|
|
211
|
+
|
|
212
|
+
export type DbWrite =
|
|
213
|
+
| {
|
|
214
|
+
readonly op: "set";
|
|
215
|
+
readonly path: string;
|
|
216
|
+
readonly data: DbData;
|
|
217
|
+
/** The version read (0: it must not exist yet). Needed to replace one that exists. */
|
|
218
|
+
readonly ifVersion?: number;
|
|
219
|
+
}
|
|
220
|
+
| {
|
|
221
|
+
readonly op: "update";
|
|
222
|
+
readonly path: string;
|
|
223
|
+
/** Fields merged over the document's (top level). */
|
|
224
|
+
readonly data: DbData;
|
|
225
|
+
readonly ifVersion?: number;
|
|
226
|
+
}
|
|
227
|
+
| { readonly op: "delete"; readonly path: string; readonly ifVersion?: number };
|
|
228
|
+
|
|
229
|
+
/** A `db` call, as the host's handler gets it (paths checked, `me` resolved). */
|
|
230
|
+
export type DbRequest =
|
|
231
|
+
| { readonly op: "get"; readonly path: string }
|
|
232
|
+
| DbWrite
|
|
233
|
+
| {
|
|
234
|
+
readonly op: "query";
|
|
235
|
+
readonly collection: string;
|
|
236
|
+
readonly where?: readonly DbWhere[];
|
|
237
|
+
readonly orderBy?: { readonly field: string; readonly direction: "asc" | "desc" };
|
|
238
|
+
readonly limit?: number;
|
|
239
|
+
}
|
|
240
|
+
| { readonly op: "batch"; readonly writes: readonly DbWrite[] }
|
|
241
|
+
/** A document or a collection, kept current: the handler calls `changed` with each new state. */
|
|
242
|
+
| { readonly op: "watch"; readonly path: string };
|
|
243
|
+
|
|
244
|
+
/** A document as the host answers it. `version` counts its writes (1 for the first). */
|
|
245
|
+
export interface DbSnapshot {
|
|
246
|
+
readonly path: string;
|
|
247
|
+
readonly id: string;
|
|
248
|
+
readonly exists: boolean;
|
|
249
|
+
readonly version: number;
|
|
250
|
+
readonly data?: DbData;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** What each op answers. */
|
|
254
|
+
export type DbResult =
|
|
255
|
+
/** get */
|
|
256
|
+
| DbSnapshot
|
|
257
|
+
/** set, update */
|
|
258
|
+
| { readonly version: number }
|
|
259
|
+
/** query, a collection's watch */
|
|
260
|
+
| { readonly docs: readonly DbSnapshot[] }
|
|
261
|
+
/** batch: each write's new version (null for a delete) */
|
|
262
|
+
| { readonly versions: readonly (number | null)[] }
|
|
263
|
+
/** delete, watch */
|
|
264
|
+
| undefined;
|
|
265
|
+
|
|
266
|
+
type Parsed<T> = T | "too_large" | null;
|
|
267
|
+
|
|
268
|
+
function parseWrite(
|
|
269
|
+
value: unknown,
|
|
270
|
+
op?: string,
|
|
271
|
+
budget?: { nodes: number; readonly seen: WeakSet<object> },
|
|
272
|
+
): Parsed<DbWrite> {
|
|
273
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
274
|
+
return null;
|
|
275
|
+
}
|
|
276
|
+
const raw = value as Record<string, unknown>;
|
|
277
|
+
const kind = op ?? raw.op;
|
|
278
|
+
const segments = dbSegments(raw.path);
|
|
279
|
+
const ifVersion = version(raw.ifVersion);
|
|
280
|
+
if (segments === null || dbPathKind(segments) !== "doc" || ifVersion === null) {
|
|
281
|
+
return null;
|
|
282
|
+
}
|
|
283
|
+
const path = segments.join("/");
|
|
284
|
+
const at = ifVersion === undefined ? {} : { ifVersion };
|
|
285
|
+
if (kind === "delete") {
|
|
286
|
+
return { op: "delete", path, ...at };
|
|
287
|
+
}
|
|
288
|
+
if (kind !== "set" && kind !== "update") {
|
|
289
|
+
return null;
|
|
290
|
+
}
|
|
291
|
+
const data = dbData(raw.data, budget);
|
|
292
|
+
if (data === null || data === "too_large") {
|
|
293
|
+
return data;
|
|
294
|
+
}
|
|
295
|
+
return { op: kind, path, data, ...at };
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
function parseWhere(value: unknown): readonly DbWhere[] | undefined | null {
|
|
299
|
+
if (value === undefined) {
|
|
300
|
+
return undefined;
|
|
301
|
+
}
|
|
302
|
+
if (!Array.isArray(value) || value.length > DB_LIMITS.maxWhere) {
|
|
303
|
+
return null;
|
|
304
|
+
}
|
|
305
|
+
const out: DbWhere[] = [];
|
|
306
|
+
for (const each of value) {
|
|
307
|
+
if (!Array.isArray(each) || each.length !== 3) {
|
|
308
|
+
return null;
|
|
309
|
+
}
|
|
310
|
+
const [field, op, operand] = each as unknown[];
|
|
311
|
+
if (
|
|
312
|
+
typeof field !== "string" ||
|
|
313
|
+
field === "" ||
|
|
314
|
+
field.length > 256 ||
|
|
315
|
+
!(WHERE_OPS as readonly unknown[]).includes(op) ||
|
|
316
|
+
!isPlainJson(operand, DB_LIMITS.maxOperandNodes) ||
|
|
317
|
+
jsonBytes(operand, DB_LIMITS.maxOperandBytes) > DB_LIMITS.maxOperandBytes ||
|
|
318
|
+
(op === "in" && (!Array.isArray(operand) || operand.length > DB_LIMITS.maxIn))
|
|
319
|
+
) {
|
|
320
|
+
return null;
|
|
321
|
+
}
|
|
322
|
+
out.push([field, op as DbWhereOp, operand as DbValue]);
|
|
323
|
+
}
|
|
324
|
+
return out;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/** A `db` call's arguments as content sent them, checked: null (malformed), "too_large", or the call. */
|
|
328
|
+
export function parseDbRequest(args: unknown): Parsed<DbRequest> {
|
|
329
|
+
if (args === null || typeof args !== "object" || Array.isArray(args)) {
|
|
330
|
+
return null;
|
|
331
|
+
}
|
|
332
|
+
const raw = args as Record<string, unknown>;
|
|
333
|
+
switch (raw.op) {
|
|
334
|
+
case "get":
|
|
335
|
+
case "watch": {
|
|
336
|
+
const segments = dbSegments(raw.path);
|
|
337
|
+
if (segments === null || (raw.op === "get" && dbPathKind(segments) !== "doc")) {
|
|
338
|
+
return null;
|
|
339
|
+
}
|
|
340
|
+
return { op: raw.op, path: segments.join("/") };
|
|
341
|
+
}
|
|
342
|
+
case "set":
|
|
343
|
+
case "update":
|
|
344
|
+
case "delete":
|
|
345
|
+
return parseWrite(raw, raw.op);
|
|
346
|
+
case "query": {
|
|
347
|
+
const segments = dbSegments(raw.collection);
|
|
348
|
+
const where = parseWhere(raw.where);
|
|
349
|
+
if (segments === null || dbPathKind(segments) !== "collection" || where === null) {
|
|
350
|
+
return null;
|
|
351
|
+
}
|
|
352
|
+
let orderBy: { field: string; direction: "asc" | "desc" } | undefined;
|
|
353
|
+
if (raw.orderBy !== undefined) {
|
|
354
|
+
const order = raw.orderBy as Record<string, unknown> | null;
|
|
355
|
+
if (
|
|
356
|
+
order === null ||
|
|
357
|
+
typeof order !== "object" ||
|
|
358
|
+
typeof order.field !== "string" ||
|
|
359
|
+
order.field === "" ||
|
|
360
|
+
order.field.length > 256 ||
|
|
361
|
+
(order.direction !== undefined && order.direction !== "asc" && order.direction !== "desc")
|
|
362
|
+
) {
|
|
363
|
+
return null;
|
|
364
|
+
}
|
|
365
|
+
orderBy = { field: order.field, direction: order.direction === "desc" ? "desc" : "asc" };
|
|
366
|
+
}
|
|
367
|
+
const limit = raw.limit;
|
|
368
|
+
if (
|
|
369
|
+
limit !== undefined &&
|
|
370
|
+
(typeof limit !== "number" ||
|
|
371
|
+
!Number.isInteger(limit) ||
|
|
372
|
+
limit < 1 ||
|
|
373
|
+
limit > DB_LIMITS.maxQueryLimit)
|
|
374
|
+
) {
|
|
375
|
+
return null;
|
|
376
|
+
}
|
|
377
|
+
return {
|
|
378
|
+
op: "query",
|
|
379
|
+
collection: segments.join("/"),
|
|
380
|
+
...(where === undefined ? {} : { where }),
|
|
381
|
+
...(orderBy === undefined ? {} : { orderBy }),
|
|
382
|
+
...(limit === undefined ? {} : { limit }),
|
|
383
|
+
};
|
|
384
|
+
}
|
|
385
|
+
case "batch": {
|
|
386
|
+
const writes = raw.writes;
|
|
387
|
+
if (!Array.isArray(writes) || writes.length === 0) {
|
|
388
|
+
return null;
|
|
389
|
+
}
|
|
390
|
+
if (writes.length > DB_LIMITS.maxBatchWrites) {
|
|
391
|
+
return "too_large";
|
|
392
|
+
}
|
|
393
|
+
const parsed: DbWrite[] = [];
|
|
394
|
+
// One budget for the whole batch, and one write a path: a batch is checked against one
|
|
395
|
+
// state, so two writes to a path would both pass it.
|
|
396
|
+
const budget = { nodes: DB_LIMITS.maxNodes, seen: new WeakSet<object>() };
|
|
397
|
+
const paths = new Set<string>();
|
|
398
|
+
for (const each of writes) {
|
|
399
|
+
const write = parseWrite(each, undefined, budget);
|
|
400
|
+
if (write === null || write === "too_large") {
|
|
401
|
+
return write;
|
|
402
|
+
}
|
|
403
|
+
if (paths.has(write.path)) {
|
|
404
|
+
return null;
|
|
405
|
+
}
|
|
406
|
+
paths.add(write.path);
|
|
407
|
+
parsed.push(write);
|
|
408
|
+
}
|
|
409
|
+
if (jsonBytes(parsed, DB_LIMITS.maxBatchBytes) > DB_LIMITS.maxBatchBytes) {
|
|
410
|
+
return "too_large";
|
|
411
|
+
}
|
|
412
|
+
return { op: "batch", writes: parsed };
|
|
413
|
+
}
|
|
414
|
+
default:
|
|
415
|
+
return null;
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* The page's rules for its data (its `db` declaration, P086): by top-level collection (or `*`),
|
|
421
|
+
* the least level that may read and write it. They only raise the contract's (read: view, write:
|
|
422
|
+
* interact); the host evaluates them again on its side (`dbAccess`).
|
|
423
|
+
*/
|
|
424
|
+
export type DbRules = Readonly<Record<string, DbRule>>;
|
|
425
|
+
|
|
426
|
+
/** One collection's rule: the least level that may read it, and write it (absent: the contract's). */
|
|
427
|
+
export interface DbRule {
|
|
428
|
+
readonly read?: ViewerLevel;
|
|
429
|
+
readonly write?: ViewerLevel;
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
/**
|
|
433
|
+
* The most collections a page's rules name (P086). At publish, `DB_MAX_RULES`; where a
|
|
434
|
+
* declaration is shown (a mount, `intersectDeclarations`), an intersection of two: twice that, and
|
|
435
|
+
* `*` (P093, after its review).
|
|
436
|
+
*/
|
|
437
|
+
export const DB_MAX_RULES = 100;
|
|
438
|
+
export const DB_MAX_SHOWN_RULES = 2 * DB_MAX_RULES + 1;
|
|
439
|
+
|
|
440
|
+
/** Where a declaration is checked: at publish, or where it is shown (a mount, an intersection). */
|
|
441
|
+
export type DeclarationStage = "publish" | "shown";
|
|
442
|
+
|
|
443
|
+
/** A collection's name, ASCII case folded: a store that folds case keeps `Votes` where `votes` is. */
|
|
444
|
+
export const foldCollection = (name: string): string =>
|
|
445
|
+
name.replace(/[A-Z]+/gu, (run) => run.toLowerCase());
|
|
446
|
+
|
|
447
|
+
/** The level a rule asks to read or write (absent: the contract's, read view and write interact). */
|
|
448
|
+
export function dbRuleLevel(rule: DbRule | undefined, write: boolean): ViewerLevel {
|
|
449
|
+
const base: ViewerLevel = write ? "interact" : "view";
|
|
450
|
+
const asked = write ? rule?.write : rule?.read;
|
|
451
|
+
return asked === undefined ? base : higher(base, asked);
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/** The stricter of two rules, read and write each (absent: the contract's level). */
|
|
455
|
+
export function stricterDbRule(x: DbRule | undefined, y: DbRule | undefined): DbRule {
|
|
456
|
+
const out = Object.create(null) as { read?: ViewerLevel; write?: ViewerLevel };
|
|
457
|
+
for (const field of ["read", "write"] as const) {
|
|
458
|
+
const p = x?.[field];
|
|
459
|
+
const q = y?.[field];
|
|
460
|
+
const level = p === undefined ? q : q === undefined ? p : higher(p, q);
|
|
461
|
+
if (level !== undefined) {
|
|
462
|
+
out[field] = level;
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
return out;
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/**
|
|
469
|
+
* The rule a top-level collection is under (P086, P093): the rule object the rules give its exact
|
|
470
|
+
* name, else `*`'s, whole; never field by field (a collection's `{}` is the contract's levels,
|
|
471
|
+
* whatever `*` says). Then made stricter by every rule that names it in another ASCII case (a
|
|
472
|
+
* store that folds case keeps `Votes` where `votes` is): never looser than the exact name's
|
|
473
|
+
* lookup, and the same where nothing names it in another case. Own names only: a collection
|
|
474
|
+
* named `constructor` or `__proto__` is no rule unless the rules name it (P091). `dbAccess` and
|
|
475
|
+
* `intersectDeclarations` both read rules through this.
|
|
476
|
+
*/
|
|
477
|
+
export function dbRuleOf(rules: DbRules | undefined, collection: string): DbRule | undefined {
|
|
478
|
+
if (rules === undefined) {
|
|
479
|
+
return undefined;
|
|
480
|
+
}
|
|
481
|
+
const own = (key: string) => (Object.hasOwn(rules, key) ? rules[key] : undefined);
|
|
482
|
+
// After the re-review: `*` counts whenever the exact name is absent, variants or not.
|
|
483
|
+
let rule = own(collection) ?? own("*");
|
|
484
|
+
if (collection === "*") {
|
|
485
|
+
return rule;
|
|
486
|
+
}
|
|
487
|
+
const folded = foldCollection(collection);
|
|
488
|
+
for (const name of Object.keys(rules)) {
|
|
489
|
+
const each = rules[name];
|
|
490
|
+
if (
|
|
491
|
+
name !== "*" &&
|
|
492
|
+
name !== collection &&
|
|
493
|
+
typeof each === "object" &&
|
|
494
|
+
foldCollection(name) === folded
|
|
495
|
+
) {
|
|
496
|
+
rule = stricterDbRule(rule, each);
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
return rule;
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
/**
|
|
503
|
+
* A rules object's problem, or null. At publish (the default) at most `DB_MAX_RULES` names, none
|
|
504
|
+
* two that differ only in case (P093); where shown, an intersection's `DB_MAX_SHOWN_RULES`, and
|
|
505
|
+
* names in more than one case as a page from before P093 may have them.
|
|
506
|
+
*/
|
|
507
|
+
export function dbRulesProblem(value: unknown, stage: DeclarationStage = "publish"): string | null {
|
|
508
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
509
|
+
return "must be an object of { read?, write } levels by collection";
|
|
510
|
+
}
|
|
511
|
+
const entries = Object.entries(value as Record<string, unknown>);
|
|
512
|
+
const most = stage === "publish" ? DB_MAX_RULES : DB_MAX_SHOWN_RULES;
|
|
513
|
+
if (entries.length > most) {
|
|
514
|
+
return `may name at most ${most} collections`;
|
|
515
|
+
}
|
|
516
|
+
const folded = new Map<string, string>();
|
|
517
|
+
for (const [collection, rule] of entries) {
|
|
518
|
+
if (collection !== "*" && !SEGMENT.test(collection)) {
|
|
519
|
+
return `${JSON.stringify(collection)} is not a collection name (or "*")`;
|
|
520
|
+
}
|
|
521
|
+
const other = folded.get(foldCollection(collection));
|
|
522
|
+
if (stage === "publish" && other !== undefined) {
|
|
523
|
+
return `${JSON.stringify(other)} and ${JSON.stringify(collection)} differ only in case: name a collection once (a rule holds for its name in any case)`;
|
|
524
|
+
}
|
|
525
|
+
folded.set(foldCollection(collection), collection);
|
|
526
|
+
if (rule === null || typeof rule !== "object" || Array.isArray(rule)) {
|
|
527
|
+
return `${collection}: must be { read?, write? }`;
|
|
528
|
+
}
|
|
529
|
+
for (const [key, level] of Object.entries(rule as Record<string, unknown>)) {
|
|
530
|
+
if ((key !== "read" && key !== "write") || !isViewerLevel(level)) {
|
|
531
|
+
return `${collection}.${key}: must be read or write, a level (view, interact, admin, owner)`;
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
}
|
|
535
|
+
return null;
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
/** Whether an op reads or writes. */
|
|
539
|
+
const writes = (op: DbRequest["op"]): boolean =>
|
|
540
|
+
op === "set" || op === "update" || op === "delete" || op === "batch";
|
|
541
|
+
|
|
542
|
+
/** The paths a call touches. */
|
|
543
|
+
function pathsOf(request: DbRequest): string[] {
|
|
544
|
+
switch (request.op) {
|
|
545
|
+
case "query":
|
|
546
|
+
return [request.collection];
|
|
547
|
+
case "batch":
|
|
548
|
+
return request.writes.map((each) => each.path);
|
|
549
|
+
default:
|
|
550
|
+
return [request.path];
|
|
551
|
+
}
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
/** `path` with `me` resolved to the viewer, or null where it names someone else's data. */
|
|
555
|
+
function ownPath(path: string, viewer: ViewerInfo | undefined): string | null {
|
|
556
|
+
const segments = path.split("/");
|
|
557
|
+
// `data`, however a store folds its case (after the review: `Data/users/<id>` is no way round).
|
|
558
|
+
if (segments[0]?.toLowerCase() !== "data") {
|
|
559
|
+
return path;
|
|
560
|
+
}
|
|
561
|
+
if (segments[0] !== "data") {
|
|
562
|
+
return null;
|
|
563
|
+
}
|
|
564
|
+
// `data` holds only per-user trees: `data/users/<id>/…`, the viewer's own.
|
|
565
|
+
if (segments[1] !== "users" || segments.length < 3) {
|
|
566
|
+
return null;
|
|
567
|
+
}
|
|
568
|
+
if (!isDbSegment(viewer?.id)) {
|
|
569
|
+
return null;
|
|
570
|
+
}
|
|
571
|
+
const id = segments[2] === "me" ? viewer?.id : segments[2];
|
|
572
|
+
if (id === undefined || viewer?.id === undefined || id !== viewer.id) {
|
|
573
|
+
return null;
|
|
574
|
+
}
|
|
575
|
+
segments[2] = id;
|
|
576
|
+
return segments.join("/");
|
|
577
|
+
}
|
|
578
|
+
|
|
579
|
+
/** The least level a rule asks for `path`. */
|
|
580
|
+
function ruleLevel(rules: DbRules | undefined, path: string, write: boolean): ViewerLevel {
|
|
581
|
+
return dbRuleLevel(dbRuleOf(rules, path.split("/")[0] ?? ""), write);
|
|
582
|
+
}
|
|
583
|
+
|
|
584
|
+
/**
|
|
585
|
+
* Whether `viewer` may make `request` under `rules` (P088), and the call with `me` resolved:
|
|
586
|
+
* someone else's per-user data is refused at every level, and so is any path under `data` that
|
|
587
|
+
* isn't `data/users/<own id>/…`; then each path's rule. The bridge applies it before the host's
|
|
588
|
+
* handler; a host applies it again in its own API (its data's wall).
|
|
589
|
+
*/
|
|
590
|
+
export function dbAccess(
|
|
591
|
+
request: DbRequest,
|
|
592
|
+
viewer: ViewerInfo | undefined,
|
|
593
|
+
rules?: DbRules,
|
|
594
|
+
): { readonly ok: true; readonly request: DbRequest } | { readonly ok: false } {
|
|
595
|
+
if (viewer === undefined) {
|
|
596
|
+
return { ok: false };
|
|
597
|
+
}
|
|
598
|
+
const resolve = (path: string): string | null => ownPath(path, viewer);
|
|
599
|
+
for (const path of pathsOf(request)) {
|
|
600
|
+
const own = resolve(path);
|
|
601
|
+
if (own === null || !atLeast(viewer.level, ruleLevel(rules, own, writes(request.op)))) {
|
|
602
|
+
return { ok: false };
|
|
603
|
+
}
|
|
604
|
+
}
|
|
605
|
+
switch (request.op) {
|
|
606
|
+
case "query":
|
|
607
|
+
return { ok: true, request: { ...request, collection: resolve(request.collection) ?? "" } };
|
|
608
|
+
case "batch":
|
|
609
|
+
return {
|
|
610
|
+
ok: true,
|
|
611
|
+
request: {
|
|
612
|
+
op: "batch",
|
|
613
|
+
writes: request.writes.map((each) => ({ ...each, path: resolve(each.path) ?? "" })),
|
|
614
|
+
},
|
|
615
|
+
};
|
|
616
|
+
default:
|
|
617
|
+
return { ok: true, request: { ...request, path: resolve(request.path) ?? "" } };
|
|
618
|
+
}
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* A `db` answer as content gets it (P088, after the review): every path in the viewer's own tree
|
|
623
|
+
* says `data/users/me`, never their id, so a page that didn't declare `user` doesn't learn who is
|
|
624
|
+
* viewing from its own data's paths. Snapshots and `{ docs }`; anything else as it is.
|
|
625
|
+
*/
|
|
626
|
+
export function withMe(value: unknown, viewer: ViewerInfo | undefined): unknown {
|
|
627
|
+
const id = viewer?.id;
|
|
628
|
+
if (id === undefined || value === null || typeof value !== "object") {
|
|
629
|
+
return value;
|
|
630
|
+
}
|
|
631
|
+
const own = `${DB_USERS_PREFIX}${id}`;
|
|
632
|
+
const path = (each: unknown): unknown => {
|
|
633
|
+
if (each === null || typeof each !== "object" || Array.isArray(each)) {
|
|
634
|
+
return each;
|
|
635
|
+
}
|
|
636
|
+
const snapshot = each as { readonly path?: unknown };
|
|
637
|
+
if (
|
|
638
|
+
typeof snapshot.path === "string" &&
|
|
639
|
+
(snapshot.path === own || snapshot.path.startsWith(`${own}/`))
|
|
640
|
+
) {
|
|
641
|
+
return { ...snapshot, path: `${DB_USERS_PREFIX}me${snapshot.path.slice(own.length)}` };
|
|
642
|
+
}
|
|
643
|
+
return each;
|
|
644
|
+
};
|
|
645
|
+
const docs = (value as { readonly docs?: unknown }).docs;
|
|
646
|
+
if (Array.isArray(docs)) {
|
|
647
|
+
return { ...value, docs: docs.map(path) };
|
|
648
|
+
}
|
|
649
|
+
return path(value);
|
|
650
|
+
}
|