@decocms/blocks 7.72.0 → 8.0.0-next.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.
Files changed (148) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +32 -3
  3. package/src/cms/schema.ts +1 -1
  4. package/src/hooks/LiveControls.tsx +2 -0
  5. package/src/hooks/useLoadMore.ts +2 -0
  6. package/src/index.ts +37 -0
  7. package/src/protocol/assets.ts +124 -0
  8. package/src/protocol/canonical.ts +7 -0
  9. package/src/protocol/ciphertext.ts +6 -0
  10. package/src/protocol/client.ts +170 -0
  11. package/src/protocol/conformance/cases/assets.ts +81 -0
  12. package/src/protocol/conformance/cases/guards.ts +314 -0
  13. package/src/protocol/conformance/cases/reads.ts +168 -0
  14. package/src/protocol/conformance/cases/types.ts +9 -0
  15. package/src/protocol/conformance/cases/wire.ts +138 -0
  16. package/src/protocol/conformance/cases/writes.ts +345 -0
  17. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  18. package/src/protocol/conformance/context.ts +222 -0
  19. package/src/protocol/conformance/index.ts +140 -0
  20. package/src/protocol/errors.ts +142 -0
  21. package/src/protocol/index.ts +39 -0
  22. package/src/protocol/keys.ts +279 -0
  23. package/src/protocol/params.ts +67 -0
  24. package/src/protocol/secrets.ts +231 -0
  25. package/src/protocol/server/assets.ts +119 -0
  26. package/src/protocol/server/auth.ts +49 -0
  27. package/src/protocol/server/bodyCache.ts +84 -0
  28. package/src/protocol/server/content.ts +175 -0
  29. package/src/protocol/server/core.ts +112 -0
  30. package/src/protocol/server/handler.ts +102 -0
  31. package/src/protocol/server/http.ts +139 -0
  32. package/src/protocol/server/index.ts +11 -0
  33. package/src/protocol/server/methods/apply.ts +341 -0
  34. package/src/protocol/server/methods/read.ts +156 -0
  35. package/src/protocol/server/rpc.ts +136 -0
  36. package/src/protocol/storage/fs/hash.ts +21 -0
  37. package/src/protocol/storage/fs/index.ts +338 -0
  38. package/src/protocol/storage/fs/lock.ts +68 -0
  39. package/src/protocol/storage/fs/transaction.ts +183 -0
  40. package/src/protocol/storage/fs/unsupported.ts +15 -0
  41. package/src/protocol/storage/memory.ts +238 -0
  42. package/src/protocol/storage.ts +182 -0
  43. package/src/protocol/types.ts +172 -0
  44. package/src/v8/analytics.ts +50 -0
  45. package/src/v8/background.ts +107 -0
  46. package/src/v8/builtins/data.ts +23 -0
  47. package/src/v8/builtins/index.ts +26 -0
  48. package/src/v8/builtins/lazy.ts +23 -0
  49. package/src/v8/builtins/legacy.ts +65 -0
  50. package/src/v8/builtins/matchers.ts +31 -0
  51. package/src/v8/builtins/multivariate.ts +25 -0
  52. package/src/v8/builtins/secret.ts +82 -0
  53. package/src/v8/canonical.ts +117 -0
  54. package/src/v8/ciphertext.ts +158 -0
  55. package/src/v8/cli/builtins.ts +20 -0
  56. package/src/v8/cli/check/index.ts +774 -0
  57. package/src/v8/cli/check/messages.ts +168 -0
  58. package/src/v8/cli/content.ts +287 -0
  59. package/src/v8/cli/index.ts +17 -0
  60. package/src/v8/cli/log.ts +18 -0
  61. package/src/v8/cli/main.ts +12 -0
  62. package/src/v8/cli/root.ts +66 -0
  63. package/src/v8/cli/run.ts +236 -0
  64. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  65. package/src/v8/cli/schema/generate.ts +507 -0
  66. package/src/v8/cli/schema/index.ts +63 -0
  67. package/src/v8/cli/schema/tsProgram.ts +497 -0
  68. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  69. package/src/v8/cli/serve/server.ts +303 -0
  70. package/src/v8/cli/watch.ts +86 -0
  71. package/src/v8/client.ts +147 -0
  72. package/src/v8/cms.ts +237 -0
  73. package/src/v8/content.ts +195 -0
  74. package/src/v8/draft.ts +136 -0
  75. package/src/v8/errors.ts +59 -0
  76. package/src/v8/fetch.ts +152 -0
  77. package/src/v8/identity.ts +65 -0
  78. package/src/v8/index.ts +39 -0
  79. package/src/v8/json.ts +74 -0
  80. package/src/v8/matchRoute.ts +204 -0
  81. package/src/v8/remoteLoader.ts +282 -0
  82. package/src/v8/resolver.ts +278 -0
  83. package/src/v8/secrets.ts +17 -0
  84. package/src/v8/telemetry.ts +533 -0
  85. package/src/v8/types.ts +240 -0
  86. package/src/cms/blockSource.test.ts +0 -76
  87. package/src/cms/client.browserBundle.test.ts +0 -44
  88. package/src/cms/deferredTrigger.test.ts +0 -32
  89. package/src/cms/draftSource.test.ts +0 -519
  90. package/src/cms/layoutCacheRace.test.ts +0 -181
  91. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  92. package/src/cms/loader.test.ts +0 -557
  93. package/src/cms/registry.test.ts +0 -110
  94. package/src/cms/renderJson.test.ts +0 -167
  95. package/src/cms/resolve.test.ts +0 -1492
  96. package/src/cms/schema.test.ts +0 -356
  97. package/src/cms/sectionLoaderContext.test.ts +0 -111
  98. package/src/cms/sectionLoaders.test.ts +0 -625
  99. package/src/cms/sectionMixins.test.ts +0 -167
  100. package/src/cms/stickyFlags.test.ts +0 -117
  101. package/src/flags/flags.test.ts +0 -148
  102. package/src/hooks/Image.test.ts +0 -239
  103. package/src/hooks/RenderSection.test.tsx +0 -81
  104. package/src/hooks/Stats.test.ts +0 -112
  105. package/src/hooks/useLoadMore.test.ts +0 -205
  106. package/src/matchers/builtins.test.ts +0 -318
  107. package/src/matchers/override.test.ts +0 -205
  108. package/src/middleware/hydrationContext.test.ts +0 -61
  109. package/src/middleware/observability.test.ts +0 -335
  110. package/src/middleware/validateSection.test.ts +0 -147
  111. package/src/preview/DraftPreviewBadge.render.test.tsx +0 -67
  112. package/src/preview/DraftPreviewBadge.test.ts +0 -55
  113. package/src/sdk/abTesting.test.ts +0 -381
  114. package/src/sdk/cacheHeaders.test.ts +0 -258
  115. package/src/sdk/cacheStorage.test.ts +0 -242
  116. package/src/sdk/cachedLoader.test.ts +0 -122
  117. package/src/sdk/cachedLoaderMaxBytes.test.ts +0 -23
  118. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  119. package/src/sdk/cachedLoaderSizeMetric.test.ts +0 -93
  120. package/src/sdk/cn.test.ts +0 -34
  121. package/src/sdk/composite.test.ts +0 -121
  122. package/src/sdk/cookie.test.ts +0 -108
  123. package/src/sdk/crypto.test.ts +0 -65
  124. package/src/sdk/deepOmit.test.ts +0 -45
  125. package/src/sdk/encoding.test.ts +0 -71
  126. package/src/sdk/env.test.ts +0 -33
  127. package/src/sdk/experiments.test.ts +0 -328
  128. package/src/sdk/fetchCache.test.ts +0 -164
  129. package/src/sdk/flags.test.ts +0 -91
  130. package/src/sdk/http.test.ts +0 -71
  131. package/src/sdk/inflightTimeout.test.ts +0 -35
  132. package/src/sdk/instrumentedFetch.test.ts +0 -559
  133. package/src/sdk/invoke.test.ts +0 -115
  134. package/src/sdk/logger.test.ts +0 -432
  135. package/src/sdk/otel.test.ts +0 -691
  136. package/src/sdk/otelAdapters.test.ts +0 -89
  137. package/src/sdk/otelHttpLog.test.ts +0 -457
  138. package/src/sdk/otelHttpMeter.test.ts +0 -395
  139. package/src/sdk/otelHttpTracer.test.ts +0 -474
  140. package/src/sdk/replaceStream.test.ts +0 -117
  141. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  142. package/src/sdk/splitExactRedirects.test.ts +0 -154
  143. package/src/sdk/urlRedaction.test.ts +0 -73
  144. package/src/sdk/urlUtils.test.ts +0 -34
  145. package/src/sdk/useDevice.test.ts +0 -130
  146. package/src/sdk/useScript.test.ts +0 -128
  147. package/src/sdk/useSuggestions.test.ts +0 -230
  148. package/tsconfig.json +0 -7
@@ -0,0 +1,231 @@
1
+ /**
2
+ * The secret guard: the content protocol refuses plain text in a `Secret`
3
+ * field, so the site editor and agents can't save a credential by mistake.
4
+ *
5
+ * A `Secret` field must hold a `secret` block with a well-formed
6
+ * `ciphertext` (`{ "__resolveType": "secret", "ciphertext": "v1.…" }`, in the
7
+ * format `./ciphertext` pins: three base64url segments of checked lengths), or a
8
+ * variant block whose every value does. Every `secret` block anywhere in an
9
+ * entry must carry a well-formed `ciphertext`, whatever its field.
10
+ *
11
+ * The schema marks a `Secret` field with `"format": "secret"` — the contract
12
+ * `deco schema` emits for the `Secret` type. Browser-safe.
13
+ */
14
+ import { parseCiphertext } from "./ciphertext";
15
+ import type { BlockViolation } from "./errors";
16
+ import type { DecoMeta } from "./types";
17
+
18
+ /** The built-in block type that holds an encrypted value. */
19
+ export const SECRET_BLOCK_TYPE = "secret";
20
+
21
+ /** The JSON Schema `format` that marks a `Secret` field. */
22
+ export const SECRET_FORMAT = "secret";
23
+
24
+ const MULTIVARIATE_TYPES = new Set(["multivariate", "website/flags/multivariate.ts"]);
25
+ const LAZY_TYPE = "lazy";
26
+ const MAX_DEPTH = 512;
27
+
28
+ type Json = Record<string, unknown>;
29
+
30
+ const isObject = (value: unknown): value is Json =>
31
+ typeof value === "object" && value !== null && !Array.isArray(value);
32
+
33
+ const resolveTypeOf = (value: unknown): string | undefined =>
34
+ isObject(value) && typeof value.__resolveType === "string" ? value.__resolveType : undefined;
35
+
36
+ const escapePointer = (key: string) => key.replace(/~/g, "~0").replace(/\//g, "~1");
37
+
38
+ /**
39
+ * True when `ciphertext` is a well-formed secret ciphertext:
40
+ * `v1.<wrappedKey>.<iv>.<ciphertext>` with segment lengths an RSA-OAEP and
41
+ * AES-256-GCM encryption produces. Checking it needs no key.
42
+ */
43
+ export function isWellFormedCiphertext(ciphertext: unknown): ciphertext is string {
44
+ return parseCiphertext(ciphertext) !== null;
45
+ }
46
+
47
+ /** True when a JSON Schema node describes a `Secret` field. */
48
+ export function isSecretFieldSchema(schema: unknown): boolean {
49
+ return isObject(schema) && schema.format === SECRET_FORMAT;
50
+ }
51
+
52
+ /** True when `value` is a `secret` block with a well-formed `ciphertext`. */
53
+ export function isSecretBlock(value: unknown): boolean {
54
+ return (
55
+ resolveTypeOf(value) === SECRET_BLOCK_TYPE && isWellFormedCiphertext((value as Json).ciphertext)
56
+ );
57
+ }
58
+
59
+ const blockIndexCache = new WeakMap<object, Map<string, unknown>>();
60
+
61
+ /** Every block type in the schema's manifest, by key, to the schema of its arguments. */
62
+ function blockIndex(meta: DecoMeta): Map<string, unknown> {
63
+ const cached = blockIndexCache.get(meta);
64
+ if (cached) return cached;
65
+ const index = new Map<string, unknown>();
66
+ for (const group of Object.values(meta.manifest?.blocks ?? {})) {
67
+ if (!isObject(group)) continue;
68
+ for (const [key, schema] of Object.entries(group)) {
69
+ if (!index.has(key)) index.set(key, schema);
70
+ }
71
+ }
72
+ blockIndexCache.set(meta, index);
73
+ return index;
74
+ }
75
+
76
+ class SecretWalker {
77
+ readonly violations: BlockViolation[] = [];
78
+
79
+ constructor(
80
+ private readonly name: string,
81
+ private readonly meta: DecoMeta | null,
82
+ ) {}
83
+
84
+ private report(pointer: string, rule: string, message: string) {
85
+ this.violations.push({ name: this.name, pointer, rule, message });
86
+ }
87
+
88
+ /** Follows local `$ref`s into `schema.definitions`. */
89
+ private deref(schema: unknown): unknown {
90
+ let current = schema;
91
+ for (let hops = 0; hops < 32 && isObject(current) && typeof current.$ref === "string"; hops++) {
92
+ const match = /^#\/definitions\/(.+)$/.exec(current.$ref);
93
+ if (!match) return current;
94
+ const key = decodeURIComponent(match[1]!).replace(/~1/g, "/").replace(/~0/g, "~");
95
+ current = this.meta?.schema?.definitions?.[key];
96
+ }
97
+ return current;
98
+ }
99
+
100
+ /** The schemas of a node, flattened through `allOf`/`anyOf`/`oneOf`. */
101
+ private branches(schema: unknown, depth = 0): Json[] {
102
+ const node = this.deref(schema);
103
+ if (!isObject(node) || depth > 16) return [];
104
+ const out: Json[] = [node];
105
+ for (const combinator of ["allOf", "anyOf", "oneOf"] as const) {
106
+ const list = node[combinator];
107
+ if (Array.isArray(list)) for (const item of list) out.push(...this.branches(item, depth + 1));
108
+ }
109
+ return out;
110
+ }
111
+
112
+ private isSecretField(schema: unknown): boolean {
113
+ return this.branches(schema).some(isSecretFieldSchema);
114
+ }
115
+
116
+ private propertySchema(schema: unknown, key: string): unknown {
117
+ for (const branch of this.branches(schema)) {
118
+ const properties = branch.properties;
119
+ if (isObject(properties) && key in properties) return properties[key];
120
+ }
121
+ for (const branch of this.branches(schema)) {
122
+ if (isObject(branch.additionalProperties)) return branch.additionalProperties;
123
+ }
124
+ return undefined;
125
+ }
126
+
127
+ private itemSchema(schema: unknown): unknown {
128
+ for (const branch of this.branches(schema)) {
129
+ if (isObject(branch.items)) return branch.items;
130
+ }
131
+ return undefined;
132
+ }
133
+
134
+ /** A value stored in a `Secret` field. */
135
+ checkSecretValue(value: unknown, pointer: string, depth: number) {
136
+ if (depth > MAX_DEPTH)
137
+ return this.report(pointer, "too-deep", "the value is nested too deeply");
138
+ const type = resolveTypeOf(value);
139
+ if (type === SECRET_BLOCK_TYPE) return this.walkBlock(value as Json, pointer, depth);
140
+ if (type !== undefined && MULTIVARIATE_TYPES.has(type)) {
141
+ const variants = (value as Json).variants;
142
+ if (!Array.isArray(variants)) {
143
+ return this.report(
144
+ pointer,
145
+ "secret-field",
146
+ "a Secret field holds a variant block without variants",
147
+ );
148
+ }
149
+ for (const [index, variant] of variants.entries()) {
150
+ const at = `${pointer}/variants/${index}`;
151
+ if (!isObject(variant)) {
152
+ this.report(at, "secret-field", "a variant must be an object");
153
+ continue;
154
+ }
155
+ if (variant.rule !== undefined) this.walkAny(variant.rule, `${at}/rule`, depth + 1);
156
+ let inner = variant.value;
157
+ let innerAt = `${at}/value`;
158
+ if (resolveTypeOf(inner) === LAZY_TYPE) {
159
+ inner = (inner as Json).value;
160
+ innerAt = `${innerAt}/value`;
161
+ }
162
+ this.checkSecretValue(inner, innerAt, depth + 1);
163
+ }
164
+ return;
165
+ }
166
+ this.report(
167
+ pointer,
168
+ "secret-field",
169
+ 'a Secret field must hold a "secret" block with a well-formed ciphertext, never plain text',
170
+ );
171
+ }
172
+
173
+ /** A block value: its own definition (from the manifest) describes its arguments. */
174
+ walkBlock(block: Json, pointer: string, depth: number) {
175
+ const type = block.__resolveType as string;
176
+ if (type === SECRET_BLOCK_TYPE && !isWellFormedCiphertext(block.ciphertext)) {
177
+ this.report(
178
+ pointer,
179
+ "secret-ciphertext",
180
+ 'a "secret" block must carry a well-formed "ciphertext" (v1.<wrappedKey>.<iv>.<ciphertext>)',
181
+ );
182
+ }
183
+ const definition = this.meta ? blockIndex(this.meta).get(type) : undefined;
184
+ this.walkObject(block, definition, pointer, depth);
185
+ }
186
+
187
+ private walkObject(object: Json, schema: unknown, pointer: string, depth: number) {
188
+ for (const [key, child] of Object.entries(object)) {
189
+ if (key === "__resolveType") continue;
190
+ const childSchema = schema === undefined ? undefined : this.propertySchema(schema, key);
191
+ this.walk(child, childSchema, `${pointer}/${escapePointer(key)}`, depth + 1);
192
+ }
193
+ }
194
+
195
+ walk(value: unknown, schema: unknown, pointer: string, depth: number) {
196
+ if (depth > MAX_DEPTH)
197
+ return this.report(pointer, "too-deep", "the value is nested too deeply");
198
+ if (schema !== undefined && this.isSecretField(schema)) {
199
+ return this.checkSecretValue(value, pointer, depth);
200
+ }
201
+ if (Array.isArray(value)) {
202
+ const items = schema === undefined ? undefined : this.itemSchema(schema);
203
+ for (const [index, item] of value.entries()) {
204
+ this.walk(item, items, `${pointer}/${index}`, depth + 1);
205
+ }
206
+ return;
207
+ }
208
+ if (!isObject(value)) return;
209
+ // A nested block is described by its own definition, not the field's union.
210
+ if (resolveTypeOf(value) !== undefined) return this.walkBlock(value, pointer, depth);
211
+ this.walkObject(value, schema, pointer, depth);
212
+ }
213
+
214
+ walkAny(value: unknown, pointer: string, depth: number) {
215
+ this.walk(value, undefined, pointer, depth);
216
+ }
217
+ }
218
+
219
+ /**
220
+ * Checks one entry against the secret guard. `meta` is the parsed schema;
221
+ * without one, only the `secret` blocks' ciphertexts can be checked.
222
+ */
223
+ export function checkSecrets(
224
+ name: string,
225
+ entry: unknown,
226
+ meta: DecoMeta | null,
227
+ ): BlockViolation[] {
228
+ const walker = new SecretWalker(name, meta);
229
+ walker.walk(entry, undefined, "", 0);
230
+ return walker.violations;
231
+ }
@@ -0,0 +1,119 @@
1
+ /**
2
+ * `createAssetHandler(storage)`: uploads beside the content protocol.
3
+ *
4
+ * Uploads aren't one of the four methods. The site editor sends each file to
5
+ * `PUT /assets/<name>` with the same token as the protocol; on that path the
6
+ * file's own image, video, font or PDF content type is accepted instead of
7
+ * JSON, and the name's extension must match it (`banner.html` sent as
8
+ * `image/png` is refused; a name without an extension gets the type's). SVG
9
+ * is refused unless `allowSvg` is set, since it can carry scripts that would
10
+ * run on the site's origin. The storage writes it to its asset folder, never overwriting an
11
+ * existing file (a taken name gets a short suffix), and the response carries
12
+ * the path the site editor stores in the field: always `/assets/<name>`.
13
+ */
14
+
15
+ import {
16
+ type AssetTypeOptions,
17
+ assetNameForType,
18
+ isAcceptedAssetType,
19
+ sanitizeAssetName,
20
+ } from "../assets";
21
+ import {
22
+ type ContentProtocolError,
23
+ ErrorCode,
24
+ forbidden,
25
+ invalidRequest,
26
+ limitExceeded,
27
+ readOnly,
28
+ unauthorized,
29
+ unsupported,
30
+ } from "../errors";
31
+ import type { ContentStorage } from "../storage";
32
+ import { ASSETS_URL_PREFIX } from "../types";
33
+ import { type AuthOptions, assertAuthOptions, authenticate } from "./auth";
34
+ import { BodyEncodingError, BodyTooLargeError, jsonResponse, readBody } from "./http";
35
+
36
+ const STATUS: Record<number, number> = {
37
+ [ErrorCode.Unauthorized]: 401,
38
+ [ErrorCode.Forbidden]: 403,
39
+ [ErrorCode.ReadOnly]: 403,
40
+ [ErrorCode.Unsupported]: 404,
41
+ [ErrorCode.LimitExceeded]: 413,
42
+ [ErrorCode.InvalidRequest]: 400,
43
+ };
44
+
45
+ export type AssetHandler = (request: Request) => Promise<Response>;
46
+
47
+ export type AssetHandlerOptions = AuthOptions & AssetTypeOptions;
48
+
49
+ export function createAssetHandler(
50
+ storage: ContentStorage,
51
+ options: AssetHandlerOptions = {},
52
+ ): AssetHandler {
53
+ assertAuthOptions(options);
54
+ const fail = (request: Request, error: ContentProtocolError, status?: number) =>
55
+ jsonResponse(
56
+ request,
57
+ JSON.stringify({ error: error.toJSON() }),
58
+ status ?? STATUS[error.code] ?? 400,
59
+ );
60
+
61
+ return async (request) => {
62
+ if (request.method !== "PUT") {
63
+ return jsonResponse(
64
+ request,
65
+ JSON.stringify({ error: invalidRequest("use PUT").toJSON() }),
66
+ 405,
67
+ {
68
+ allow: "PUT",
69
+ },
70
+ );
71
+ }
72
+ const auth = await authenticate(request, options);
73
+ if (!auth.ok)
74
+ return fail(request, auth.reason === "unauthorized" ? unauthorized() : forbidden());
75
+
76
+ const description = await storage.describe();
77
+ if (description.readOnly) return fail(request, readOnly());
78
+ if (description.assets === null || !storage.putAsset) {
79
+ return fail(request, unsupported("this endpoint doesn't accept uploads"));
80
+ }
81
+ const contentType = request.headers.get("content-type");
82
+ if (!isAcceptedAssetType(contentType, options)) {
83
+ return fail(request, invalidRequest("uploads must be an image, video, font or PDF"), 415);
84
+ }
85
+ const path = new URL(request.url).pathname;
86
+ const marker = path.lastIndexOf(ASSETS_URL_PREFIX);
87
+ const sanitized =
88
+ marker === -1 ? null : sanitizeAssetName(path.slice(marker + ASSETS_URL_PREFIX.length));
89
+ if (!sanitized) return fail(request, invalidRequest("PUT /assets/<name> needs a file name"));
90
+ const name = assetNameForType(sanitized, contentType, options);
91
+ if (!name) {
92
+ return fail(
93
+ request,
94
+ invalidRequest(`the file name's extension doesn't match its content type (${contentType})`),
95
+ 415,
96
+ );
97
+ }
98
+
99
+ const maxBytes = description.assets.maxBytes;
100
+ let body: Uint8Array;
101
+ try {
102
+ body = await readBody(request, maxBytes);
103
+ } catch (error) {
104
+ if (error instanceof BodyTooLargeError) {
105
+ return fail(request, limitExceeded(`uploads are limited to ${maxBytes} bytes`));
106
+ }
107
+ if (error instanceof BodyEncodingError)
108
+ return fail(request, invalidRequest(error.message), 415);
109
+ throw error;
110
+ }
111
+ if (body.byteLength === 0) return fail(request, invalidRequest("the upload is empty"));
112
+ const stored = await storage.putAsset(name, body);
113
+ return jsonResponse(
114
+ request,
115
+ JSON.stringify({ path: `${ASSETS_URL_PREFIX}${stored.name}` }),
116
+ 201,
117
+ );
118
+ };
119
+ }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Request authorization shared by the content handler and the asset handler.
3
+ */
4
+ import { bearerToken, timingSafeEqualStrings } from "./http";
5
+
6
+ /**
7
+ * What an `authorize` hook decides:
8
+ * - `true` or `{ scope }` — allowed. `scope` names the tenant and principal,
9
+ * and scopes request-key receipts, so one tenant never replays another's.
10
+ * - `false` or `"unauthorized"` — a missing or invalid bearer token (HTTP 401).
11
+ * - `"forbidden"` — authenticated, but not allowed for this project.
12
+ */
13
+ export type AuthorizeResult = boolean | "unauthorized" | "forbidden" | { scope?: string };
14
+
15
+ export interface AuthOptions {
16
+ /** When set, every request must carry `Authorization: Bearer <token>`. */
17
+ token?: string;
18
+ /** Decides whether a request may proceed (runs after the token check). */
19
+ authorize?: (request: Request) => AuthorizeResult | Promise<AuthorizeResult>;
20
+ }
21
+
22
+ /**
23
+ * Refuses options that would lock every client out by accident: an empty
24
+ * token can never be presented, so every request would be 401.
25
+ */
26
+ export function assertAuthOptions(options: AuthOptions): void {
27
+ if (options.token !== undefined && (typeof options.token !== "string" || options.token === "")) {
28
+ throw new TypeError("token must be a non-empty string; omit it to accept requests without one");
29
+ }
30
+ }
31
+
32
+ type AuthOutcome =
33
+ | { ok: true; scope: string }
34
+ | { ok: false; reason: "unauthorized" | "forbidden" };
35
+
36
+ export async function authenticate(request: Request, options: AuthOptions): Promise<AuthOutcome> {
37
+ if (options.token !== undefined) {
38
+ const presented = bearerToken(request);
39
+ if (presented === null || !(await timingSafeEqualStrings(presented, options.token))) {
40
+ return { ok: false, reason: "unauthorized" };
41
+ }
42
+ }
43
+ if (!options.authorize) return { ok: true, scope: "" };
44
+ const result = await options.authorize(request);
45
+ if (result === true) return { ok: true, scope: "" };
46
+ if (result === false || result === "unauthorized") return { ok: false, reason: "unauthorized" };
47
+ if (result === "forbidden") return { ok: false, reason: "forbidden" };
48
+ return { ok: true, scope: result.scope ?? "" };
49
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * A bounded cache of parsed entry bodies, keyed by file and version.
3
+ *
4
+ * Versions identify content, so a polling client that sees a new revision
5
+ * only costs a read and a parse for the files that actually changed.
6
+ */
7
+
8
+ export type ParsedBody =
9
+ | { ok: true; value: Record<string, unknown>; bytes: number }
10
+ | {
11
+ ok: false;
12
+ kind: "invalid-json" | "not-an-object" | "too-large";
13
+ message: string;
14
+ bytes: number;
15
+ };
16
+
17
+ export class BodyCache {
18
+ private readonly entries = new Map<string, ParsedBody>();
19
+ private total = 0;
20
+
21
+ constructor(private readonly maxBytes: number) {}
22
+
23
+ private static key(file: string, version: string) {
24
+ return `${file}\0${version}`;
25
+ }
26
+
27
+ get(file: string, version: string): ParsedBody | undefined {
28
+ const key = BodyCache.key(file, version);
29
+ const hit = this.entries.get(key);
30
+ if (hit) {
31
+ // Refresh recency.
32
+ this.entries.delete(key);
33
+ this.entries.set(key, hit);
34
+ }
35
+ return hit;
36
+ }
37
+
38
+ set(file: string, version: string, body: ParsedBody): void {
39
+ if (body.bytes > this.maxBytes) return;
40
+ const key = BodyCache.key(file, version);
41
+ const previous = this.entries.get(key);
42
+ if (previous) {
43
+ this.total -= previous.bytes;
44
+ this.entries.delete(key);
45
+ }
46
+ this.entries.set(key, body);
47
+ this.total += body.bytes;
48
+ for (const [oldest, value] of this.entries) {
49
+ if (this.total <= this.maxBytes) break;
50
+ this.entries.delete(oldest);
51
+ this.total -= value.bytes;
52
+ }
53
+ }
54
+ }
55
+
56
+ const utf8 = new TextEncoder();
57
+
58
+ /** Parses one stored entry, enforcing the per-entry byte limit. */
59
+ export function parseBody(text: string, maxBlockBytes: number): ParsedBody {
60
+ const bytes = utf8.encode(text).byteLength;
61
+ if (bytes > maxBlockBytes) {
62
+ return {
63
+ ok: false,
64
+ kind: "too-large",
65
+ bytes,
66
+ message: `the file is over ${maxBlockBytes} bytes`,
67
+ };
68
+ }
69
+ let value: unknown;
70
+ try {
71
+ value = JSON.parse(text);
72
+ } catch (error) {
73
+ return { ok: false, kind: "invalid-json", bytes, message: (error as Error).message };
74
+ }
75
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
76
+ return {
77
+ ok: false,
78
+ kind: "not-an-object",
79
+ bytes,
80
+ message: "the file doesn't hold a JSON object",
81
+ };
82
+ }
83
+ return { ok: true, value: value as Record<string, unknown>, bytes };
84
+ }
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Turns a storage snapshot (files and versions) into the entry map, applying
3
+ * the one file-name rule: decode once, resolve spellings, report the rest.
4
+ * Shared by `blocks.list` (which needs every body) and `blocks.apply` (which
5
+ * needs bodies only to break ties between spellings).
6
+ */
7
+ import { limitExceeded, unavailable } from "../errors";
8
+ import { entryHasPath, fullyDecodeFileName, isBlockFileName, resolveSpellings } from "../keys";
9
+ import type { ContentStorage, StorageFile, StorageSnapshot } from "../storage";
10
+ import type { Diagnostic, Limits } from "../types";
11
+ import { type BodyCache, type ParsedBody, parseBody } from "./bodyCache";
12
+
13
+ export interface LoadedEntry {
14
+ file: string;
15
+ version: string;
16
+ /** The parsed entry; absent when the body wasn't needed. */
17
+ value?: Record<string, unknown>;
18
+ }
19
+
20
+ export interface LoadedContent {
21
+ snapshot: StorageSnapshot;
22
+ /** Every entry, by name, in file-name order of the winning files. */
23
+ entries: Map<string, LoadedEntry>;
24
+ /** Every saved-block file, valid or not, by spelling key. */
25
+ groups: Map<string, StorageFile[]>;
26
+ /** Files skipped or shadowed. */
27
+ diagnostics: Diagnostic[];
28
+ /** Uncompressed bytes of the bodies read. */
29
+ bytes: number;
30
+ /**
31
+ * True when a body read didn't match the snapshot (the file changed or
32
+ * vanished in between): the content isn't one consistent snapshot, so the
33
+ * caller takes a new one.
34
+ */
35
+ moved: boolean;
36
+ }
37
+
38
+ interface Options {
39
+ /** Read every body (`blocks.list`), not only the ones that break ties. */
40
+ readAll: boolean;
41
+ limits: Limits;
42
+ cache: BodyCache;
43
+ }
44
+
45
+ async function loadContent(
46
+ storage: ContentStorage,
47
+ snapshot: StorageSnapshot,
48
+ { readAll, limits, cache }: Options,
49
+ ): Promise<LoadedContent> {
50
+ const files = snapshot.files.filter((f) => isBlockFileName(f.file));
51
+ const groups = new Map<string, StorageFile[]>();
52
+ for (const file of files) {
53
+ const key = fullyDecodeFileName(file.file).name;
54
+ const group = groups.get(key);
55
+ if (group) group.push(file);
56
+ else groups.set(key, [file]);
57
+ }
58
+
59
+ const diagnostics: Diagnostic[] = [];
60
+ let moved = false;
61
+ const parsed = new Map<string, ParsedBody>();
62
+ const toRead: StorageFile[] = [];
63
+ let knownBytes = 0;
64
+ for (const group of groups.values()) {
65
+ if (!readAll && group.length < 2) continue;
66
+ for (const file of group) {
67
+ // An existing file over maxBlockBytes is unreadable, like invalid JSON: it's
68
+ // left out of the map and reported as a `too-large` diagnostic, so one
69
+ // oversized hand edit can't take the whole editor down. The map plus its
70
+ // diagnostics still accounts for every file in the snapshot; only the
71
+ // aggregate (maxListBytes) answers LimitExceeded.
72
+ if (file.size !== undefined && file.size > limits.maxBlockBytes) {
73
+ parsed.set(file.file, {
74
+ ok: false,
75
+ kind: "too-large",
76
+ bytes: file.size,
77
+ message: `the file is over ${limits.maxBlockBytes} bytes`,
78
+ });
79
+ continue;
80
+ }
81
+ knownBytes += file.size ?? 0;
82
+ const hit = cache.get(file.file, file.version);
83
+ if (hit) parsed.set(file.file, hit);
84
+ else toRead.push(file);
85
+ }
86
+ }
87
+ if (readAll && knownBytes > limits.maxListBytes) {
88
+ throw limitExceeded(`the block list is over ${limits.maxListBytes} bytes`, {
89
+ limit: "maxListBytes",
90
+ });
91
+ }
92
+ if (toRead.length > 0) {
93
+ const bodies = await storage.readFiles(
94
+ snapshot,
95
+ toRead.map((f) => f.file),
96
+ );
97
+ for (const file of toRead) {
98
+ const read = bodies[file.file];
99
+ if (read === undefined) {
100
+ moved = true; // vanished since the snapshot
101
+ continue;
102
+ }
103
+ const body = parseBody(read.text, limits.maxBlockBytes);
104
+ // Cache under the version of the bytes actually read, never the snapshot's.
105
+ cache.set(file.file, read.version, body);
106
+ if (read.version !== file.version) {
107
+ moved = true;
108
+ continue;
109
+ }
110
+ parsed.set(file.file, body);
111
+ }
112
+ }
113
+
114
+ let bytes = 0;
115
+ const candidates: Array<StorageFile & { hasPath: boolean; value?: Record<string, unknown> }> = [];
116
+ for (const file of files) {
117
+ const body = parsed.get(file.file);
118
+ if (body === undefined) {
119
+ // Not read: a single spelling whose body wasn't needed, or a file that vanished.
120
+ if (!readAll) candidates.push({ ...file, hasPath: false });
121
+ continue;
122
+ }
123
+ if (!body.ok) {
124
+ diagnostics.push({ file: file.file, kind: body.kind, message: body.message });
125
+ continue;
126
+ }
127
+ bytes += body.bytes;
128
+ candidates.push({ ...file, hasPath: entryHasPath(body.value), value: body.value });
129
+ }
130
+ if (readAll && bytes > limits.maxListBytes) {
131
+ throw limitExceeded(`the block list is over ${limits.maxListBytes} bytes`, {
132
+ limit: "maxListBytes",
133
+ });
134
+ }
135
+
136
+ const entries = new Map<string, LoadedEntry>();
137
+ for (const { name, winner, shadowed } of resolveSpellings(candidates).values()) {
138
+ entries.set(name, { file: winner.file, version: winner.version, value: winner.value });
139
+ for (const loser of shadowed) {
140
+ diagnostics.push({
141
+ file: loser.file,
142
+ kind: "shadowed",
143
+ name,
144
+ winner: winner.file,
145
+ message: `another spelling of "${name}" wins: ${winner.file}`,
146
+ });
147
+ }
148
+ }
149
+ diagnostics.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
150
+ return { snapshot, entries, groups, diagnostics, bytes, moved };
151
+ }
152
+
153
+ /** How many snapshots a read takes before giving up on files that keep changing. */
154
+ const MAX_SNAPSHOT_READS = 3;
155
+
156
+ /**
157
+ * Takes a snapshot and loads its content, taking a new snapshot when a file
158
+ * changed while its body was being read, so the bodies always match the
159
+ * versions and revision they're reported with. `shortCircuit` can end the
160
+ * read right after the snapshot (a conditional read that's "not modified").
161
+ */
162
+ export async function loadCurrentContent(
163
+ storage: ContentStorage,
164
+ ref: string | undefined,
165
+ options: Options,
166
+ shortCircuit?: (snapshot: StorageSnapshot) => boolean,
167
+ ): Promise<{ snapshot: StorageSnapshot; content: LoadedContent | null }> {
168
+ for (let read = 1; read <= MAX_SNAPSHOT_READS; read++) {
169
+ const snapshot = await storage.snapshot({ ref });
170
+ if (shortCircuit?.(snapshot)) return { snapshot, content: null };
171
+ const content = await loadContent(storage, snapshot, options);
172
+ if (!content.moved) return { snapshot, content };
173
+ }
174
+ throw unavailable("saved blocks kept changing while being read; retry shortly", 250);
175
+ }