@caelo-cms/shared 0.11.13 → 0.11.14

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.
@@ -0,0 +1,295 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * Issue #1330 — the staged site as staging storage holds it, shared by the
5
+ * admin (which writes it at every Stage) and the staging gateway (which
6
+ * serves it behind the gate).
7
+ *
8
+ * Staging storage always holds complete builds (decision 2026-11-04, D1):
9
+ * on the cloud providers two slots of the private staging bucket
10
+ * (`_slots/a`, `_slots/b`), on a self-hosted install the run's build
11
+ * directory. A Stage syncs the slot staging does not serve (only changed
12
+ * files are written, removed ones deleted) and then points the projection
13
+ * at it, so a half-synced build is never served. Every build location has a
14
+ * manifest next to it, {@link stagedManifestKey}: the files it serves, each
15
+ * with its Content-Type and a content hash (the next Stage's diff), plus the
16
+ * run, the page URL style and the origin the pages were rendered for.
17
+ *
18
+ * The gateway serves only paths the manifest lists, so a request can never
19
+ * name a storage key outside the location (prefix-bound by construction),
20
+ * and every manifest key is a plain path ({@link isSafeStagedPath}).
21
+ *
22
+ * Content-Type and Cache-Control follow the same rules the live publishers
23
+ * use (moved here from admin-core `static-file-policy.ts`, which re-exports
24
+ * them), so staging answers like production does.
25
+ */
26
+
27
+ import { z } from "zod";
28
+ import {
29
+ HTML_CACHE_CONTROL,
30
+ IMMUTABLE_CACHE_CONTROL,
31
+ isContentHashedPath,
32
+ } from "./static-cache-policy.js";
33
+
34
+ /** The two cloud slots a Stage alternates between. */
35
+ export const STAGING_SLOTS = ["a", "b"] as const;
36
+ export type StagingSlot = (typeof STAGING_SLOTS)[number];
37
+
38
+ /** Storage location of a cloud slot (`_slots/a`). */
39
+ export function stagingSlotLocation(slot: StagingSlot): string {
40
+ return `_slots/${slot}`;
41
+ }
42
+
43
+ /** The slot a Stage fills next: the one `servedLocation` does not name. */
44
+ export function nextStagingSlot(servedLocation: string | null): StagingSlot {
45
+ return servedLocation === stagingSlotLocation("a") ? "b" : "a";
46
+ }
47
+
48
+ /**
49
+ * A build location as the projection publishes it (`_slots/a`,
50
+ * `builds/<runId>`): relative, plain segments, no traversal.
51
+ */
52
+ export const STAGED_LOCATION_PATTERN = /^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_.-]+)*$/;
53
+
54
+ /** True when `location` is a location {@link STAGED_LOCATION_PATTERN} admits and no segment is `.`/`..`. */
55
+ export function isSafeStagedLocation(location: string): boolean {
56
+ return (
57
+ location.length <= 200 &&
58
+ STAGED_LOCATION_PATTERN.test(location) &&
59
+ location.split("/").every((s) => s !== "." && s !== "..")
60
+ );
61
+ }
62
+
63
+ /** Storage key of the manifest of the build at `location`. */
64
+ export function stagedManifestKey(location: string): string {
65
+ return `${location}.manifest.json`;
66
+ }
67
+
68
+ /** Storage key of `path` (a manifest path) of the build at `location`. */
69
+ export function stagedFileKey(location: string, path: string): string {
70
+ return `${location}/${path}`;
71
+ }
72
+
73
+ /**
74
+ * A build-relative path a staged build may serve: plain `/`-separated
75
+ * segments, no `.`/`..`, no backslash, NUL or control character, no leading
76
+ * slash.
77
+ */
78
+ export function isSafeStagedPath(path: string): boolean {
79
+ if (path.length === 0 || path.length > 1024 || path.startsWith("/")) return false;
80
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point
81
+ if (path.includes("\\") || /[\u0000-\u001f\u007f]/.test(path)) return false;
82
+ return path.split("/").every((s) => s.length > 0 && s !== "." && s !== "..");
83
+ }
84
+
85
+ const stagedFileSchema = z.object({
86
+ /** Content-Type the file is served with. */
87
+ type: z.string().min(1).max(200),
88
+ /** Content hash; only compared for equality by the next Stage's diff. */
89
+ hash: z.string().min(1).max(200),
90
+ });
91
+
92
+ /** The manifest of one staged build ({@link stagedManifestKey}). */
93
+ export const stagedManifestSchema = z.object({
94
+ version: z.literal(1),
95
+ runId: z.string().uuid(),
96
+ pageUrlStyle: z.enum(["directory", "no-extension"]),
97
+ files: z
98
+ .record(z.string(), stagedFileSchema)
99
+ .refine((files) => Object.keys(files).every(isSafeStagedPath), {
100
+ message: "every path must be a plain build-relative path",
101
+ }),
102
+ });
103
+
104
+ export type StagedManifest = z.infer<typeof stagedManifestSchema>;
105
+ export type StagedFileEntry = z.infer<typeof stagedFileSchema>;
106
+
107
+ /**
108
+ * Map a request path to the manifest paths to try, or null when the path is
109
+ * not a plain, safe site path. Pure.
110
+ *
111
+ * `/` → `index.html`; `/about/` → `about/index.html`; `/about` → `about`
112
+ * (no-extension builds) then `about/index.html`.
113
+ */
114
+ export function stagedKeysFor(requestPath: string): string[] | null {
115
+ const pathOnly = requestPath.split("?")[0]?.split("#")[0] ?? "";
116
+ let decoded: string;
117
+ try {
118
+ decoded = decodeURIComponent(pathOnly);
119
+ } catch {
120
+ return null;
121
+ }
122
+ if (!decoded.startsWith("/") || decoded.includes("\0") || decoded.includes("\\")) return null;
123
+ const segments = decoded.split("/").filter((s) => s.length > 0);
124
+ if (segments.some((s) => s === "." || s === "..")) return null;
125
+ const key = segments.join("/");
126
+ if (key === "") return ["index.html"];
127
+ if (decoded.endsWith("/")) return [`${key}/index.html`];
128
+ return [key, `${key}/index.html`];
129
+ }
130
+
131
+ function extensionOf(key: string): string {
132
+ const name = key.slice(key.lastIndexOf("/") + 1);
133
+ const dot = name.lastIndexOf(".");
134
+ return dot <= 0 ? "" : name.slice(dot).toLowerCase();
135
+ }
136
+
137
+ /** Content-Type by file extension (`application/octet-stream` when unknown). */
138
+ export function contentTypeFor(key: string): string {
139
+ switch (extensionOf(key)) {
140
+ case ".html":
141
+ return "text/html; charset=utf-8";
142
+ case ".css":
143
+ return "text/css; charset=utf-8";
144
+ case ".js":
145
+ case ".mjs":
146
+ return "application/javascript; charset=utf-8";
147
+ case ".json":
148
+ return "application/json; charset=utf-8";
149
+ case ".svg":
150
+ return "image/svg+xml";
151
+ case ".ico":
152
+ return "image/x-icon";
153
+ case ".png":
154
+ return "image/png";
155
+ case ".jpg":
156
+ case ".jpeg":
157
+ return "image/jpeg";
158
+ case ".webp":
159
+ return "image/webp";
160
+ case ".woff2":
161
+ return "font/woff2";
162
+ case ".woff":
163
+ return "font/woff";
164
+ case ".txt":
165
+ return "text/plain; charset=utf-8";
166
+ case ".xml":
167
+ return "application/xml; charset=utf-8";
168
+ default:
169
+ return "application/octet-stream";
170
+ }
171
+ }
172
+
173
+ /** Cache-Control for a file of `contentType` served at site path `key`. */
174
+ export function cacheControlForContentType(contentType: string, key: string): string {
175
+ // Content-hashed outputs (fonts, plugin bundles, media, Vite chunks)
176
+ // are immutable regardless of content-type — the hash in the path is
177
+ // the signal. Anything else under `_assets/` stays on the 1h default.
178
+ if (isContentHashedPath(key)) {
179
+ return IMMUTABLE_CACHE_CONTROL;
180
+ }
181
+ if (contentType.startsWith("text/html")) {
182
+ return HTML_CACHE_CONTROL;
183
+ }
184
+ if (key === "routing-manifest.json" || key === "_content-types.json") {
185
+ return "public, max-age=10";
186
+ }
187
+ if (contentType.startsWith("application/json")) {
188
+ return "public, max-age=60";
189
+ }
190
+ if (key === "robots.txt" || key === "sitemap.xml") {
191
+ return "public, max-age=300";
192
+ }
193
+ return "public, max-age=3600";
194
+ }
195
+
196
+ /**
197
+ * Whether a staged file of `contentType` carries absolute URLs the staging
198
+ * gateway rewrites to the staging host: pages, sitemaps, feeds, styles,
199
+ * scripts, JSON and plain text. Binary files pass through untouched.
200
+ */
201
+ export function isRewritableContentType(contentType: string): boolean {
202
+ const t = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
203
+ return (
204
+ t.startsWith("text/") ||
205
+ t === "application/xml" ||
206
+ t === "application/javascript" ||
207
+ t === "application/json" ||
208
+ t === "application/manifest+json" ||
209
+ t === "application/rss+xml" ||
210
+ t === "application/atom+xml" ||
211
+ t === "image/svg+xml"
212
+ );
213
+ }
214
+
215
+ /**
216
+ * The byte-level replacements that point a build rendered for `fromOrigin`
217
+ * (the live site, `https://example.com`) at `toOrigin` (the staging host):
218
+ * the origin as written, and as JSON escapes it inside inline data.
219
+ */
220
+ export function originRewritePairs(
221
+ fromOrigin: string,
222
+ toOrigin: string,
223
+ ): readonly (readonly [string, string])[] {
224
+ const jsonEscaped = (o: string) => o.replaceAll("/", "\\/");
225
+ return [
226
+ [fromOrigin, toOrigin],
227
+ [jsonEscaped(fromOrigin), jsonEscaped(toOrigin)],
228
+ ];
229
+ }
230
+
231
+ /** Characters that may follow an origin in a URL or around one (never a host or port character). */
232
+ const AFTER_ORIGIN = String.raw`(?=[/"'?#\s<>),;\\\]}&|]|$)`;
233
+
234
+ function escapeRegExp(literal: string): string {
235
+ return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
236
+ }
237
+
238
+ /**
239
+ * A stream transform that replaces every occurrence of each `from` origin
240
+ * with its `to`, also across chunk boundaries. An origin only matches as a
241
+ * whole: `https://example.com` is not rewritten inside
242
+ * `https://example.community` or `https://example.com:8443`. The transform
243
+ * holds back the last bytes of each chunk until the next one (or the end)
244
+ * shows whether they are, or start, a match. Works on UTF-8 text; the
245
+ * origins are ASCII, so a match never splits a multi-byte character.
246
+ *
247
+ * @example
248
+ * body.pipeThrough(originRewriteStream(originRewritePairs("https://example.com", "https://staging.example.com")))
249
+ */
250
+ export function originRewriteStream(
251
+ pairs: readonly (readonly [string, string])[],
252
+ ): TransformStream<Uint8Array, Uint8Array> {
253
+ const usable = pairs.filter(([from]) => from.length > 0);
254
+ const patterns = usable.map(
255
+ ([from, to]) => [new RegExp(`${escapeRegExp(from)}${AFTER_ORIGIN}`, "g"), to] as const,
256
+ );
257
+ // A match plus the one character that decides whether it is whole.
258
+ const keep = Math.max(0, ...usable.map(([from]) => from.length));
259
+ const decoder = new TextDecoder();
260
+ const encoder = new TextEncoder();
261
+ let pending = "";
262
+ const replaceAll = (text: string): string => {
263
+ let out = text;
264
+ for (const [re, to] of patterns) out = out.replace(re, to);
265
+ return out;
266
+ };
267
+ return new TransformStream<Uint8Array, Uint8Array>({
268
+ transform(chunk, controller) {
269
+ pending += decoder.decode(chunk, { stream: true });
270
+ let cut = pending.length - keep;
271
+ if (cut <= 0) return;
272
+ // An occurrence that reaches the cut (or ends right at it, its next
273
+ // character unseen by the head) moves the cut to its start; it is
274
+ // decided with the next chunk.
275
+ for (const [from] of usable) {
276
+ let at = pending.indexOf(from, Math.max(0, cut - from.length));
277
+ while (at !== -1 && at < cut) {
278
+ if (at + from.length >= cut) {
279
+ cut = at;
280
+ break;
281
+ }
282
+ at = pending.indexOf(from, at + 1);
283
+ }
284
+ }
285
+ if (cut <= 0) return;
286
+ const head = pending.slice(0, cut);
287
+ pending = pending.slice(cut);
288
+ controller.enqueue(encoder.encode(replaceAll(head)));
289
+ },
290
+ flush(controller) {
291
+ pending += decoder.decode();
292
+ if (pending.length > 0) controller.enqueue(encoder.encode(replaceAll(pending)));
293
+ },
294
+ });
295
+ }
@@ -1,6 +1,7 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  import { describe, expect, it } from "bun:test";
4
+ import { sessionCookieValue } from "./session-cookie.js";
4
5
  import {
5
6
  constantTimeEqual,
6
7
  DEFAULT_STAGING_HEADER_NAME,
@@ -12,19 +13,28 @@ import {
12
13
  normalizeStagingHost,
13
14
  parseBasicAuthorization,
14
15
  parseCidr,
15
- readCookie,
16
- STAGING_SESSION_COOKIE,
16
+ STAGING_RUN_TOKEN_HEADER,
17
+ STAGING_RUN_TOKEN_MAX_TTL_SECONDS,
18
+ STAGING_SESSION_ENTRY,
17
19
  type StagingAccessRequest,
18
20
  type StagingAccessSettings,
19
21
  safeStagingNextPath,
22
+ signStagingRunToken,
20
23
  signStagingToken,
21
24
  stagingHostProblem,
25
+ stagingIpAllowlistSupported,
26
+ verifyStagingRunToken,
22
27
  verifyStagingToken,
23
28
  } from "./staging-gate.js";
24
29
 
25
30
  const SECRET = "test-gate-secret-0123456789abcdef";
26
31
  const NOW = 1_800_000_000;
27
32
 
33
+ /** The staging session as the gateway stores it: the `staging` entry of `__session`. */
34
+ function gateCookie(token: string): string {
35
+ return `a=1; __session=${sessionCookieValue(new Map([[STAGING_SESSION_ENTRY, { value: token, expiresAt: NOW + 3600 }]]))}; b=2`;
36
+ }
37
+
28
38
  const OFF: StagingAccessSettings = {
29
39
  cookieEnabled: false,
30
40
  basicAuthEnabled: false,
@@ -147,11 +157,6 @@ describe("header parsing", () => {
147
157
  expect(parseBasicAuthorization(`Basic ${btoa("nocolon")}`)).toBeNull();
148
158
  expect(parseBasicAuthorization(null)).toBeNull();
149
159
  });
150
-
151
- it("reads one cookie", () => {
152
- expect(readCookie("a=1; caelo_staging_access=tok; b=2", STAGING_SESSION_COOKIE)).toBe("tok");
153
- expect(readCookie("a=1", STAGING_SESSION_COOKIE)).toBeNull();
154
- });
155
160
  });
156
161
 
157
162
  describe("decideStagingAccess", () => {
@@ -165,23 +170,17 @@ describe("decideStagingAccess", () => {
165
170
  it("cookie mode: a valid session cookie gets in, an expired or open token does not", async () => {
166
171
  const s = { ...OFF, cookieEnabled: true };
167
172
  const session = await signStagingToken(SECRET, "session", NOW + 100);
168
- expect(await decide(s, req({ cookieHeader: `${STAGING_SESSION_COOKIE}=${session}` }))).toEqual({
173
+ expect(await decide(s, req({ cookieHeader: gateCookie(session) }))).toEqual({
169
174
  allowed: true,
170
175
  via: "cookie",
171
176
  satisfied: ["cookie"],
172
177
  });
173
178
  const expired = await signStagingToken(SECRET, "session", NOW - 1);
174
- expect(
175
- (await decide(s, req({ cookieHeader: `${STAGING_SESSION_COOKIE}=${expired}` }))).allowed,
176
- ).toBe(false);
179
+ expect((await decide(s, req({ cookieHeader: gateCookie(expired) }))).allowed).toBe(false);
177
180
  const open = await signStagingToken(SECRET, "open", NOW + 100);
178
- expect(
179
- (await decide(s, req({ cookieHeader: `${STAGING_SESSION_COOKIE}=${open}` }))).allowed,
180
- ).toBe(false);
181
+ expect((await decide(s, req({ cookieHeader: gateCookie(open) }))).allowed).toBe(false);
181
182
  // Cookie mode off: the same valid cookie is ignored.
182
- expect(
183
- (await decide(OFF, req({ cookieHeader: `${STAGING_SESSION_COOKIE}=${session}` }))).allowed,
184
- ).toBe(false);
183
+ expect((await decide(OFF, req({ cookieHeader: gateCookie(session) }))).allowed).toBe(false);
185
184
  });
186
185
 
187
186
  it("basic-auth mode: right user + derived password only; 401 otherwise", async () => {
@@ -255,7 +254,7 @@ describe("decideStagingAccess", () => {
255
254
  await decide(
256
255
  s,
257
256
  req({
258
- cookieHeader: `${STAGING_SESSION_COOKIE}=${session}`,
257
+ cookieHeader: gateCookie(session),
259
258
  headers: { "x-caelo-staging-key": value },
260
259
  authorizationHeader: basic("crawler", "the-sites-own-password"),
261
260
  }),
@@ -309,15 +308,60 @@ describe("staging host setting", () => {
309
308
  expect(stagingHostProblem("WWW.example.com", reserved)).toContain("live site");
310
309
  expect(stagingHostProblem("admin.example.com", reserved)).toContain("admin");
311
310
  });
312
- it("on gcp-firebase refuses hosts a Cloud Run domain mapping cannot take (> 64 chars)", () => {
311
+ it("takes a long host on every provider (#1331: no Cloud Run domain mapping any more)", () => {
313
312
  const long = `staging.${"a".repeat(50)}.example.com`; // 70 characters
314
313
  expect(stagingHostProblem(long, reserved)).toBeNull();
315
- expect(stagingHostProblem(long, reserved, { provider: "self-hosted" })).toBeNull();
316
- const problem = stagingHostProblem(long, reserved, { provider: "gcp-firebase" });
317
- expect(problem).toContain("at most 64");
318
- expect(problem).toContain("pick a shorter host");
319
- const fits = `s.${"a".repeat(50)}.example.com`; // 64 characters
320
- expect(fits.length).toBe(64);
321
- expect(stagingHostProblem(fits, reserved, { provider: "gcp-firebase" })).toBeNull();
314
+ });
315
+ });
316
+
317
+ describe("#1330 per-run tokens", () => {
318
+ const decide = (request: StagingAccessRequest) =>
319
+ decideStagingAccess({ settings: OFF, secret: SECRET, request, nowSeconds: NOW });
320
+ const run = "0b7c0d6e-1111-4111-8111-111111111111";
321
+
322
+ it("admits a valid capture token even with every mode off; a check token opens nothing", async () => {
323
+ const capture = await signStagingRunToken(SECRET, "capture", run, NOW + 300, NOW);
324
+ expect(await verifyStagingRunToken(SECRET, capture, NOW)).toEqual({
325
+ purpose: "capture",
326
+ runId: run,
327
+ });
328
+ expect(await decide(req({ headers: { [STAGING_RUN_TOKEN_HEADER]: capture } }))).toEqual({
329
+ allowed: true,
330
+ via: "run-token",
331
+ satisfied: ["run-token"],
332
+ });
333
+ const check = await signStagingRunToken(SECRET, "check", run, NOW + 300, NOW);
334
+ expect(await verifyStagingRunToken(SECRET, check, NOW)).toEqual({
335
+ purpose: "check",
336
+ runId: run,
337
+ });
338
+ expect((await decide(req({ headers: { [STAGING_RUN_TOKEN_HEADER]: check } }))).allowed).toBe(
339
+ false,
340
+ );
341
+ });
342
+
343
+ it("refuses an expired, forged, other-key or over-long token", async () => {
344
+ const expired = await signStagingRunToken(SECRET, "capture", run, NOW - 1, NOW - 100);
345
+ expect(await verifyStagingRunToken(SECRET, expired, NOW)).toBeNull();
346
+ const token = await signStagingRunToken(SECRET, "capture", run, NOW + 60, NOW);
347
+ expect(await verifyStagingRunToken("another-key-0123456789abcdef0123", token, NOW)).toBeNull();
348
+ expect(await verifyStagingRunToken(SECRET, token.replace("capture", "check"), NOW)).toBeNull();
349
+ expect(await verifyStagingRunToken(SECRET, `${token}x`, NOW)).toBeNull();
350
+ await expect(
351
+ signStagingRunToken(SECRET, "capture", run, NOW + STAGING_RUN_TOKEN_MAX_TTL_SECONDS + 1, NOW),
352
+ ).rejects.toThrow(/exceeds/);
353
+ // A session or open token is not a run token.
354
+ const session = await signStagingToken(SECRET, "session", NOW + 60);
355
+ expect(await verifyStagingRunToken(SECRET, session, NOW)).toBeNull();
356
+ expect((await decide(req({ headers: { [STAGING_RUN_TOKEN_HEADER]: session } }))).allowed).toBe(
357
+ false,
358
+ );
359
+ });
360
+
361
+ it("turns the IP allowlist off only on gcp-firebase", () => {
362
+ expect(stagingIpAllowlistSupported("gcp-firebase")).toBe(false);
363
+ for (const p of ["gcp", "self-hosted", "aws", "azure", undefined]) {
364
+ expect(stagingIpAllowlistSupported(p)).toBe(true);
365
+ }
322
366
  });
323
367
  });