@caelo-cms/shared 0.10.48 → 0.10.50

package/src/redirect-plan.ts

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The redirect plan: what every serving layer answers for the rows of the
+ * `redirects` table (#587).
+ *
+ * Each provider serves redirects through its own edge mechanism (Caddy
+ * `map` + `redir`, a GCP URL map, Firebase Hosting `config.redirects`, a
+ * CloudFront Function with a KeyValueStore, Front Door rules). They all
+ * consume this one plan, so a redirect means the same thing on every
+ * provider:
+ *
+ * - **Exact paths.** A row matches its `from` path exactly (case-sensitive)
+ *   and the same path with a trailing slash — in the directory page style
+ *   `/old/` is the URL people link to. A from path whose last segment
+ *   looks like a file (`/old.html`) matches only as written.
+ * - **The build wins.** A row whose from path a file of the build serves
+ *   is left out (#575): a live page always beats a recorded redirect, as
+ *   in the admin's 404 fallback (`redirects.lookup`). The edge layers
+ *   evaluate redirects BEFORE static files, so without this a slug moved
+ *   back to its old path would be shadowed (or loop with the reverse row).
+ * - **Chains collapse.** `/a → /b` plus `/b → /c` serves `/a → /c` in one
+ *   hop; crawlers follow few hops and every hop costs a round-trip. A hop
+ *   is followed only through rows that are themselves in the plan. The
+ *   collapsed status is permanent only when every hop is, and preserves
+ *   the method (307/308) only when every hop does.
+ * - **Loops fail the build.** A cycle can only ever answer "too many
+ *   redirects"; the error names it.
+ * - **Location.** In the directory style a page's canonical URL ends in
+ *   `/`; the Location points there directly (the host would otherwise add
+ *   a second hop). The visitor's query string is carried over unless the
+ *   target has its own query or fragment.
+ * - **410.** Rows with status 410 become `gone` entries. Layers that can
+ *   answer a bare status (Caddy, CloudFront) send 410; the others answer
+ *   the 404 a path without a file gets anyway.
+ */
+
+import { redirectTargetIssue } from "./redirect-target.js";
+import { trimTrailingSlashes } from "./url.js";
+
+/** The redirect statuses the redirects table stores (besides 410). */
+export type RedirectStatusCode = 301 | 302 | 307 | 308;
+
+/** A row of the redirects table, as the static generator dumps it. */
+export interface RedirectTableRow {
+  readonly fromPath: string;
+  readonly toPath: string;
+  readonly statusCode: number;
+}
+
+/** How the deploy target emits page URLs (`DeployTarget.pageUrlStyle`). */
+export type RedirectPageUrlStyle = "directory" | "no-extension";
+
+/** One redirect the serving layer answers. */
+export interface PlannedRedirect {
+  /** The stored from path without a trailing slash (`/` for the root). */
+  readonly fromPath: string;
+  /** Every request path this entry answers, exactly (`/old`, `/old/`). */
+  readonly matchPaths: readonly string[];
+  /** The Location header value (a same-site path, see module comment). */
+  readonly location: string;
+  readonly statusCode: RedirectStatusCode;
+  /** Append the request's query string to {@link location}. */
+  readonly preserveQuery: boolean;
+}
+
+/** One path the serving layer answers with 410 Gone (where it can). */
+export interface PlannedGone {
+  readonly fromPath: string;
+  readonly matchPaths: readonly string[];
+}
+
+/** Everything a serving layer needs to answer the redirects table. */
+export interface RedirectPlan {
+  readonly redirects: readonly PlannedRedirect[];
+  readonly gone: readonly PlannedGone[];
+  /** From paths left out because a build file serves them (#575). */
+  readonly shadowedByBuild: readonly string[];
+}
+
+const REDIRECT_STATUSES: ReadonlySet<number> = new Set([301, 302, 307, 308]);
+const GONE_STATUS = 410;
+
+/**
+ * Parse the generator's `_redirects` file (`<from> <to> <status>` per line,
+ * `#` comments). Throws on a malformed line — a rule silently dropped is a
+ * 404 on a URL someone links to.
+ *
+ * @example
+ *   parseRedirectsFile("# generated\n/old /new 301\n")
+ *   // → [{ fromPath: "/old", toPath: "/new", statusCode: 301 }]
+ */
+export function parseRedirectsFile(text: string): RedirectTableRow[] {
+  const rows: RedirectTableRow[] = [];
+  for (const [index, raw] of text.split("\n").entries()) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const parts = line.split(" ");
+    const [fromPath, toPath, status] = parts;
+    const statusCode = Number(status);
+    if (parts.length !== 3 || !fromPath || !toPath || !Number.isInteger(statusCode)) {
+      throw new Error(
+        `redirect-plan: _redirects line ${index + 1} is not "<from> <to> <status>": ${JSON.stringify(raw)}. The static generator writes this file from the redirects table — fix the row there (find_redirects / bulk_create_redirects) and rebuild.`,
+      );
+    }
+    rows.push({ fromPath, toPath, statusCode });
+  }
+  return rows;
+}
+
+/**
+ * Serialise rows into the `_redirects` file format {@link parseRedirectsFile}
+ * reads (also the Netlify / Cloudflare Pages format).
+ */
+export function formatRedirectsFile(rows: readonly RedirectTableRow[]): string {
+  return [
+    "# Auto-generated by Caelo static-generator. Do not edit by hand.",
+    ...rows.map((r) => `${r.fromPath} ${r.toPath} ${r.statusCode}`),
+    "",
+  ].join("\n");
+}
+
+/** Arguments of {@link buildRedirectPlan}. */
+export interface BuildRedirectPlanArgs {
+  readonly rows: readonly RedirectTableRow[];
+  readonly pageUrlStyle: RedirectPageUrlStyle;
+  /**
+   * Every file of the build, relative to the build root without a leading
+   * slash (`de/preise/index.html`). A from path one of them serves is left
+   * out of the plan.
+   */
+  readonly servedFiles: ReadonlySet<string>;
+}
+
+interface NormalisedRow {
+  readonly bare: string;
+  readonly toPath: string;
+  readonly statusCode: number;
+}
+
+/**
+ * Build the redirect plan every provider serves (see the module comment for
+ * the semantics). Pure and deterministic: entries keep the rows' order.
+ * Throws with an actionable message on rows no edge layer can serve
+ * correctly — a malformed path, an unsafe target, conflicting duplicates, a
+ * loop.
+ */
+export function buildRedirectPlan(args: BuildRedirectPlanArgs): RedirectPlan {
+  const rows = normaliseRows(args.rows);
+  const shadowedByBuild: string[] = [];
+  const live = new Map<string, NormalisedRow>();
+  for (const row of rows) {
+    if (servedByBuild(row.bare, args.servedFiles)) {
+      shadowedByBuild.push(row.bare);
+      continue;
+    }
+    live.set(row.bare, row);
+  }
+
+  const redirects: PlannedRedirect[] = [];
+  const gone: PlannedGone[] = [];
+  for (const row of live.values()) {
+    const matchPaths = matchPathsFor(row.bare);
+    if (row.statusCode === GONE_STATUS) {
+      gone.push({ fromPath: row.bare, matchPaths });
+      continue;
+    }
+    const { target, statusCode } = collapseChain(row, live);
+    const location = locationFor(target, args.pageUrlStyle);
+    redirects.push({
+      fromPath: row.bare,
+      matchPaths,
+      location,
+      statusCode,
+      preserveQuery: !/[?#]/.test(location),
+    });
+  }
+  return { redirects, gone, shadowedByBuild };
+}
+
+function normaliseRows(rows: readonly RedirectTableRow[]): NormalisedRow[] {
+  const byBare = new Map<string, NormalisedRow>();
+  const out: NormalisedRow[] = [];
+  for (const row of rows) {
+    const { fromPath, toPath, statusCode } = row;
+    const shown = JSON.stringify(fromPath);
+    if (!fromPath.startsWith("/") || /[\s\p{Cc}]/u.test(fromPath)) {
+      throw new Error(
+        `redirect-plan: from path ${shown} must start with '/' and contain no whitespace or control characters. Fix the row with bulk_create_redirects (upsert) or delete it with bulk_delete_redirects, then rebuild.`,
+      );
+    }
+    if (/[?#]/.test(fromPath)) {
+      throw new Error(
+        `redirect-plan: from path ${shown} contains '?' or '#'. Redirects match the URL path only, so this row can never match. Re-create it for the path alone (e.g. '${pathBeforeQuery(fromPath)}') or delete it with bulk_delete_redirects, then rebuild.`,
+      );
+    }
+    if (statusCode !== GONE_STATUS && !REDIRECT_STATUSES.has(statusCode)) {
+      throw new Error(
+        `redirect-plan: the redirect for ${shown} has status ${statusCode}; the redirects table allows 301, 302, 307, 308 or 410. Fix the row and rebuild.`,
+      );
+    }
+    if (statusCode !== GONE_STATUS) {
+      const targetIssue = redirectTargetIssue(toPath);
+      if (targetIssue) throw new Error(`redirect-plan: the redirect for ${shown}: ${targetIssue}`);
+    }
+    const bare = stripTrailingSlash(fromPath);
+    const normalised: NormalisedRow = { bare, toPath, statusCode };
+    const existing = byBare.get(bare);
+    if (existing) {
+      if (existing.toPath === toPath && existing.statusCode === statusCode) continue;
+      throw new Error(
+        `redirect-plan: two redirects answer ${JSON.stringify(bare)} (with and without the trailing slash) differently: → ${existing.toPath} (${existing.statusCode}) and → ${toPath} (${statusCode}). Delete one with bulk_delete_redirects, then rebuild.`,
+      );
+    }
+    byBare.set(bare, normalised);
+    out.push(normalised);
+  }
+  return out;
+}
+
+/** Follow `row`'s target through the plan's own rows to the final hop. */
+function collapseChain(
+  row: NormalisedRow,
+  live: ReadonlyMap<string, NormalisedRow>,
+): { target: string; statusCode: RedirectStatusCode } {
+  const visited = [row.bare];
+  let target = row.toPath;
+  let permanent = isPermanent(row.statusCode);
+  let preservesMethod = preservesRequestMethod(row.statusCode);
+  for (;;) {
+    // A target with its own query or fragment is a different URL than the
+    // path the next row matches; the chain ends there.
+    if (/[?#]/.test(target)) break;
+    const next = live.get(stripTrailingSlash(target));
+    if (!next || next.statusCode === GONE_STATUS) break;
+    if (visited.includes(next.bare)) {
+      const cycle = [...visited.slice(visited.indexOf(next.bare)), next.bare].join(" → ");
+      throw new Error(
+        `redirect-plan: the redirects ${cycle} form a loop, which browsers answer with "too many redirects". Delete the row that should no longer apply with bulk_delete_redirects (find_redirects lists them), then rebuild.`,
+      );
+    }
+    visited.push(next.bare);
+    permanent &&= isPermanent(next.statusCode);
+    preservesMethod &&= preservesRequestMethod(next.statusCode);
+    target = next.toPath;
+  }
+  return { target, statusCode: combinedStatus(permanent, preservesMethod) };
+}
+
+function isPermanent(status: number): boolean {
+  return status === 301 || status === 308;
+}
+
+function preservesRequestMethod(status: number): boolean {
+  return status === 307 || status === 308;
+}
+
+function combinedStatus(permanent: boolean, preservesMethod: boolean): RedirectStatusCode {
+  if (permanent) return preservesMethod ? 308 : 301;
+  return preservesMethod ? 307 : 302;
+}
+
+function stripTrailingSlash(path: string): string {
+  return path.length > 1 ? trimTrailingSlashes(path) || "/" : path;
+}
+
+/** The part of a stored path before its first `?` or `#` (`/` if empty). */
+function pathBeforeQuery(path: string): string {
+  const cut = path.search(/[?#]/);
+  return (cut === -1 ? path : path.slice(0, cut)) || "/";
+}
+
+/** Whether the last path segment names a file (`/a/b.html`). */
+function looksLikeFile(path: string): boolean {
+  return path.slice(path.lastIndexOf("/") + 1).includes(".");
+}
+
+function matchPathsFor(bare: string): readonly string[] {
+  if (bare === "/" || looksLikeFile(bare)) return [bare];
+  return [bare, `${bare}/`];
+}
+
+/** Does a file of the build answer `bare`? Hosts serve `/x` from the file
+ *  `x` and from the directory index `x/index.html`. */
+function servedByBuild(bare: string, servedFiles: ReadonlySet<string>): boolean {
+  if (bare === "/") return servedFiles.has("index.html");
+  const rel = bare.slice(1);
+  return servedFiles.has(rel) || servedFiles.has(`${rel}/index.html`);
+}
+
+/** In the directory style, internal page paths end in "/"; files (anything
+ *  with an extension in its last segment) and URLs with a query or fragment
+ *  stay as they are. */
+function locationFor(toPath: string, pageUrlStyle: RedirectPageUrlStyle): string {
+  if (pageUrlStyle !== "directory" || toPath.endsWith("/")) return toPath;
+  if (/[?#]/.test(toPath) || looksLikeFile(toPath)) return toPath;
+  return `${toPath}/`;
+}

package/src/release-manifest.ts

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The release manifest's shape and where it lives (epic #696) — shared by
+ * the provisioning CLI / upgrader job, which verify its Sigstore signature
+ * with cosign before trusting it (provisioning release-manifest.ts), and
+ * the admin's auto-update scheduler, which only *reads* it to decide when
+ * to queue an install (the admin image ships no cosign; the job verifies).
+ *
+ * The artifact is one OCI manifest with two layers — the JSON manifest and
+ * its Sigstore bundle — pushed by `release.yml` on the release tag.
+ * {@link fetchReleaseArtifact} fetches both blobs and checks each against
+ * its content digest; it does NOT check the signature.
+ */
+
+import { z } from "zod";
+
+/** Release channels. Pre-release versions name theirs (`0.11.0-rc.1` → `rc`). */
+export const RELEASE_CHANNELS = ["stable", "rc", "beta", "alpha"] as const;
+export type ReleaseChannel = (typeof RELEASE_CHANNELS)[number];
+
+/** The services a release ships images for. */
+export const RELEASE_IMAGES = ["admin", "gateway", "ops"] as const;
+export type ReleaseImage = (typeof RELEASE_IMAGES)[number];
+
+/** A `sha256:<64 hex>` image / blob digest. */
+export const IMAGE_DIGEST = /^sha256:[0-9a-f]{64}$/;
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+const GHSA_ID = /^GHSA(-[23456789cfghjmpqrvwx]{4}){3}$/;
+
+const digest = z.string().regex(IMAGE_DIGEST, "expected sha256:<64 hex>");
+
+/** Zod schema of `release-manifest.json` (manifestVersion 1). */
+export const ReleaseManifestSchema = z.object({
+  manifestVersion: z.literal(1),
+  version: z.string().regex(SEMVER, "expected a SemVer version without a leading v"),
+  channel: z.enum(RELEASE_CHANNELS),
+  digests: z.object({ admin: digest, gateway: digest, ops: digest }),
+  minFromVersion: z.string().regex(SEMVER),
+  infraContractVersion: z.number().int().positive(),
+  migrations: z.object({
+    /** True when the release carries destructive (contract) migrations. */
+    contract: z.boolean(),
+    /**
+     * Newest release up to and including this one that carried contract
+     * migrations (null: none known). An install below it that jumps
+     * straight here would run those destructive steps while its old image
+     * still serves — so it is manual too, even when `contract` is false.
+     */
+    lastContractVersion: z.string().regex(SEMVER).nullable(),
+    /** Newest cms_admin migration in the release, e.g. `0262_tool_approval_branch`. */
+    head: z.string().min(1),
+  }),
+  /** Set only via the release-cut input, backed by published GitHub Security Advisories. */
+  security: z.boolean(),
+  advisories: z.array(z.string().regex(GHSA_ID, "expected a GHSA id")),
+});
+export type ReleaseManifest = z.infer<typeof ReleaseManifestSchema>;
+
+/** Registry the manifests are read from — the public AR mirror Cloud Run pulls from. */
+export const RELEASE_MANIFEST_REGISTRY = "europe-west1-docker.pkg.dev";
+/** Repository path of the manifest artifact inside {@link RELEASE_MANIFEST_REGISTRY}. */
+export const RELEASE_MANIFEST_REPOSITORY = "caelo-website/caelo-cms-images/release-manifest";
+
+/** OCI artifact type + layer media types of the pushed manifest. */
+export const RELEASE_MANIFEST_ARTIFACT_TYPE = "application/vnd.caelo.release-manifest.v1";
+export const RELEASE_MANIFEST_MEDIA_TYPE = "application/vnd.caelo.release-manifest.v1+json";
+export const SIGSTORE_BUNDLE_MEDIA_TYPE = "application/vnd.dev.sigstore.bundle.v0.3+json";
+
+/** Why fetching the artifact failed. */
+export type ReleaseArtifactErrorCode = "registry" | "artifact-shape" | "blob-digest";
+
+export type ReleaseArtifactResult =
+  | { readonly ok: true; readonly manifestBytes: Uint8Array; readonly bundleBytes: Uint8Array }
+  | {
+      readonly ok: false;
+      readonly error: { readonly code: ReleaseArtifactErrorCode; readonly message: string };
+    };
+
+/** Where and how {@link fetchReleaseArtifact} reaches the registry. */
+export interface ReleaseArtifactDeps {
+  readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+  /** Registry host + repository; default to the fixed public mirror. */
+  readonly registry?: string;
+  readonly repository?: string;
+}
+
+const OciManifestSchema = z.object({
+  artifactType: z.string().optional(),
+  layers: z.array(z.object({ mediaType: z.string(), digest: z.string().regex(IMAGE_DIGEST) })),
+});
+
+async function sha256Digest(bytes: Uint8Array<ArrayBuffer>): Promise<string> {
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+  return `sha256:${[...hash].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+const fail = (code: ReleaseArtifactErrorCode, message: string): ReleaseArtifactResult => ({
+  ok: false,
+  error: { code, message },
+});
+
+/**
+ * Fetch the release manifest artifact of `version` and both its layers,
+ * each checked against its content digest. Verifies NO signature: callers
+ * that act on the manifest verify the bundle (provisioning
+ * fetchVerifiedReleaseManifest); the admin's scheduler only plans with it.
+ *
+ * @param version - SemVer without a leading `v` (the caller validates it).
+ */
+export async function fetchReleaseArtifact(
+  version: string,
+  deps: ReleaseArtifactDeps,
+): Promise<ReleaseArtifactResult> {
+  const base = `https://${deps.registry ?? RELEASE_MANIFEST_REGISTRY}/v2/${deps.repository ?? RELEASE_MANIFEST_REPOSITORY}`;
+  let artifact: z.infer<typeof OciManifestSchema>;
+  try {
+    const res = await deps.fetch(`${base}/manifests/${version}`, {
+      headers: { Accept: "application/vnd.oci.image.manifest.v1+json" },
+    });
+    if (!res.ok) {
+      return fail(
+        "registry",
+        `no release manifest for v${version} at ${base} (HTTP ${res.status}). Releases before the signed manifest (epic #696) have none; otherwise check the version exists.`,
+      );
+    }
+    const parsed = OciManifestSchema.safeParse(await res.json());
+    if (!parsed.success) {
+      return fail("artifact-shape", `not an OCI manifest: ${parsed.error.message}`);
+    }
+    artifact = parsed.data;
+  } catch (e) {
+    return fail("registry", `registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  if (artifact.artifactType !== RELEASE_MANIFEST_ARTIFACT_TYPE) {
+    return fail(
+      "artifact-shape",
+      `artifactType is ${artifact.artifactType ?? "(none)"}, expected ${RELEASE_MANIFEST_ARTIFACT_TYPE}`,
+    );
+  }
+  const manifestLayers = artifact.layers.filter((l) => l.mediaType === RELEASE_MANIFEST_MEDIA_TYPE);
+  const bundleLayers = artifact.layers.filter((l) => l.mediaType === SIGSTORE_BUNDLE_MEDIA_TYPE);
+  const [manifestLayer] = manifestLayers;
+  const [bundleLayer] = bundleLayers;
+  if (manifestLayers.length !== 1 || bundleLayers.length !== 1 || !manifestLayer || !bundleLayer) {
+    return fail(
+      "artifact-shape",
+      "the artifact must hold exactly one release-manifest layer and one Sigstore bundle layer",
+    );
+  }
+
+  const blob = async (layerDigest: string): Promise<Uint8Array | ReleaseArtifactResult> => {
+    const res = await deps.fetch(`${base}/blobs/${layerDigest}`);
+    if (!res.ok) return fail("registry", `blob ${layerDigest}: HTTP ${res.status}`);
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const actual = await sha256Digest(bytes);
+    if (actual !== layerDigest) {
+      return fail(
+        "blob-digest",
+        `blob content does not match its digest (${layerDigest} expected, ${actual} served) — the registry or a proxy altered it`,
+      );
+    }
+    return bytes;
+  };
+  try {
+    const manifestBytes = await blob(manifestLayer.digest);
+    if (!(manifestBytes instanceof Uint8Array)) return manifestBytes;
+    const bundleBytes = await blob(bundleLayer.digest);
+    if (!(bundleBytes instanceof Uint8Array)) return bundleBytes;
+    return { ok: true, manifestBytes, bundleBytes };
+  } catch (e) {
+    return fail("registry", `registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+/**
+ * Parse manifest bytes against {@link ReleaseManifestSchema} and check they
+ * describe `version`.
+ *
+ * @returns the manifest, or a plain-words problem
+ */
+export function parseReleaseManifest(
+  bytes: Uint8Array,
+  version: string,
+):
+  | { readonly ok: true; readonly manifest: ReleaseManifest }
+  | { readonly ok: false; readonly code: "schema" | "version-mismatch"; readonly message: string } {
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return { ok: false, code: "schema", message: "the manifest is not valid JSON" };
+  }
+  const parsed = ReleaseManifestSchema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      code: "schema",
+      message: `the manifest does not match manifestVersion 1 — this Caelo may be too old to read it: ${parsed.error.message}`,
+    };
+  }
+  if (parsed.data.version !== version) {
+    return {
+      ok: false,
+      code: "version-mismatch",
+      message: `asked for v${version} but the manifest describes v${parsed.data.version}`,
+    };
+  }
+  return { ok: true, manifest: parsed.data };
+}

package/src/seo.ts

@@ -44,7 +44,10 @@ export type SeoSetInput = z.infer<typeof seoSetInputSchema>;
 export const seoAutofillInputSchema = z
   .object({
     pageId: z.string().uuid(),
-    metaDescription: z.string().min(1).max(SEO_DESCRIPTION_HARD_MAX),
+    // Trimmed before the length check: a whitespace-only description would
+    // stamp `autofilled_at` (the fill-once marker) while the page still
+    // ships without a description — and then refuse every later autofill.
+    metaDescription: z.string().trim().min(1).max(SEO_DESCRIPTION_HARD_MAX),
     ogImageAssetId: z.string().uuid().nullable().optional(),
   })
   .strict();

package/src/static-cache-policy.test.ts

@@ -8,8 +8,8 @@ const HASHED_PATHS = [
   // Lighthouse report on gcp-firebase staging (v0.10.28).
   "/_assets/fonts/inter/29ede7bd4be32ab0.woff2",
   "/_assets/fonts/manrope/f3a06e9b32049b82.woff2",
-  `/_assets/fonts/pinned/${"a".repeat(64)}.woff2`,
-  `/_assets/fonts/pinned/${"0".repeat(64)}.ttf`,
+  `/_assets/fonts/pinned/${"a".repeat(64)}.latin.0123456789ab.woff2`,
+  `/_assets/fonts/pinned/${"0".repeat(64)}.cyrillic-ext.0123456789ab.woff2`,
   "/_caelo/plugin/consent-manager/runtime.0123456789ab.js",
   "/_caelo/plugin/consent-manager/banner.abcdef012345.css",
   "/_app/immutable/chunks/abc.js",
@@ -40,6 +40,10 @@ const STABLE_PATHS = [
   // Pinned-font license file is id-named, not hashed.
   "/_assets/fonts/pinned/0b1f6c2e-9d7a-4c1e-8f3a-2b6d9e0c1a4f.license.txt",
   // Look-alikes that must not slip through.
+  // The registry source itself is never published; were a raw pinned file to
+  // appear, it must not be pinned in caches for a year.
+  `/_assets/fonts/pinned/${"0".repeat(64)}.ttf`,
+  `/_assets/fonts/pinned/${"a".repeat(64)}.latin.woff2`,
   "/_assets/fonts/inter/not-a-hash.woff2",
   "/_assets/fonts/inter/29ede7bd4be32ab0.woff2.html",
   "/_caelo/plugin/consent-manager/runtime.js",

package/src/static-cache-policy.ts

@@ -17,9 +17,12 @@
  *     Google Fonts faces; the name is a hash of the upstream face URL,
  *     which Google versions per file (a changed face gets a new URL,
  *     hence a new name).
- *   - `_assets/fonts/pinned/<sha256>.<ttf|otf|woff|woff2>` — library
- *     fonts pinned by the sha256 of their bytes. (The sibling
- *     `pinned/<font-id>.license.txt` is id-named, NOT hashed.)
+ *   - `_assets/fonts/pinned/<sha256>.<slice>.<12 hex>.woff2` — WOFF2
+ *     unicode-range slices derived from a registry font: the sha256 of
+ *     the pinned source plus the delivery-toolchain tag
+ *     (`font-service/src/delivery.ts`), which together determine the
+ *     bytes. (The sibling `pinned/<font-id>.license.txt` is id-named,
+ *     NOT hashed.)
  *   - `_caelo/plugin/<slug>/<stem>.<12 hex>.<js|css>` — plugin client
  *     assets, sha256 of the content in the name
  *     (`plugin-host/src/client-assets.ts`).
@@ -52,7 +55,7 @@ export const HTML_CACHE_CONTROL = "public, max-age=60, stale-while-revalidate=86
  * matcher and Caddy's `path_regexp` (both RE2) and to `RegExp` here.
  */
 export const CONTENT_HASHED_PATH_PATTERN =
-  "^/(?:_app/immutable/.+|_assets/fonts/[^/]+/[0-9a-f]{16,64}\\.(?:woff2|woff|ttf|otf)|_assets/[a-z0-9][a-z0-9-]*(?:/[a-z][a-z0-9-]*)?\\.[0-9a-f]{16}\\.[a-z0-9]{2,5}|_caelo/plugin/[^/]+/[^/]+\\.[0-9a-f]{12}\\.(?:js|css))$";
+  "^/(?:_app/immutable/.+|_assets/fonts/[^/]+/[0-9a-f]{16}\\.woff2|_assets/fonts/pinned/[0-9a-f]{64}\\.[a-z]+(?:-[a-z]+)?\\.[0-9a-f]{12}\\.woff2|_assets/[a-z0-9][a-z0-9-]*(?:/[a-z][a-z0-9-]*)?\\.[0-9a-f]{16}\\.[a-z0-9]{2,5}|_caelo/plugin/[^/]+/[^/]+\\.[0-9a-f]{12}\\.(?:js|css))$";
 
 /** Hex length of the content hash in published media names (#667). */
 export const MEDIA_CONTENT_HASH_HEX_LENGTH = 16;

package/src/version.ts

@@ -22,7 +22,7 @@
  * follow standard SemVer.
  */
 
-export const CAELO_VERSION = "0.10.48";
+export const CAELO_VERSION = "0.10.50";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this