@caelo-cms/shared 0.10.48 → 0.10.49

package/src/platform-updates.ts

@@ -163,7 +163,15 @@ export const updatePolicySchema = z
     windowStart: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
     windowEnd: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
     windowTimezone: z.string().min(1).max(64).refine(isKnownTimeZone, "unknown time zone"),
+    /** Hours after publication before a non-security release installs automatically. */
     soakHours: z.number().int().min(0).max(720),
+    /**
+     * The same for a release whose signed manifest names a published GitHub
+     * Security Advisory (auto-update.ts `isSecurityRelease`). Shorter by
+     * default (2 h vs 24 h): the fix is public, so every hour unpatched is
+     * exposure, while two hours still let a broken release be pulled first.
+     */
+    securitySoakHours: z.number().int().min(0).max(720),
   })
   .strict()
   .refine((p) => (p.windowStart === null) === (p.windowEnd === null), {
@@ -171,6 +179,9 @@ export const updatePolicySchema = z
   })
   .refine((p) => p.mode !== "auto" || p.channel === "stable", {
     message: "automatic installs follow the stable channel only",
+  })
+  .refine((p) => p.securitySoakHours <= p.soakHours, {
+    message: "security fixes cannot wait longer than other releases",
   });
 export type UpdatePolicy = z.infer<typeof updatePolicySchema>;
 
@@ -179,6 +190,10 @@ export interface StoredUpdatePolicy extends UpdatePolicy {
   readonly paused: boolean;
   readonly pausedReason: string | null;
   readonly pausedAt: string | null;
+  /** End of the Owner's pause; null = until resumed (or not paused). */
+  readonly pausedUntil: string | null;
+  /** True when the Owner paused; false when the upgrader paused after a failure. */
+  readonly pausedByOwner: boolean;
   readonly updatedAt: string;
 }
 
@@ -238,6 +253,7 @@ export function autoInstallRefusal(
     | "autoPatch"
     | "autoMinor"
     | "paused"
+    | "pausedUntil"
     | "windowStart"
     | "windowEnd"
     | "windowTimezone"
@@ -246,7 +262,14 @@ export function autoInstallRefusal(
   at: Date,
 ): string | null {
   if (policy.mode !== "auto") return "automatic installs are switched off in the update policy";
-  if (policy.paused) return "automatic installs are paused after a failed install";
+  // An Owner pause with an end that has passed no longer holds (the
+  // scheduler lifts it on its next tick; this keeps the job consistent).
+  if (
+    policy.paused &&
+    (policy.pausedUntil === null || Date.parse(policy.pausedUntil) > at.getTime())
+  ) {
+    return "automatic installs are paused";
+  }
   if (candidate.channel !== "stable") return "only stable releases install automatically";
   if (candidate.contractMigrations) {
     return "the release carries destructive database changes; the Owner installs it by hand";

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.49";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this