@tokenoftrust/storefront-runner 2.4.25 → 2.4.26

package/apps/storefront/src/lib/publication/mountedDiscovery.ts

@@ -28,6 +28,7 @@ import {
   PUBLICATION_DISCOVERY_ENTRY_KINDS_V1,
   type PublicationDiscoveryEntryKindV1,
 } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
 import { rawPageCanonicalUrl } from "../rawMarketingHtml.js";
 
 export type DiscoverySurfaceV1 = "sitemap" | "feeds" | "publicSearch" | "llms";
@@ -135,14 +136,18 @@ export async function readMountedPublicationDiscoveryV1(input: {
   if (mounts.size === 0 || !input.store) return [];
   let projectionJson: string | null;
   let stateJson: string | null;
+  let recoveryJson: string | null;
   try {
-    [projectionJson, stateJson] = await Promise.all([
+    [projectionJson, stateJson, recoveryJson] = await Promise.all([
       input.store.get(publicationMountedDiscoveryKeyV1(input.tenant.tenant_id)),
       input.store.get(publicationVersionStateKey(input.tenant.tenant_id)),
+      input.store.get(publicationRecoveryKeyV1(input.tenant.tenant_id)),
     ]);
   } catch {
     return [];
   }
+  // Under a whole-site recovery the mounts serve the whole-site release, which lists itself.
+  if (publicationRecoveryActiveV1(recoveryJson)) return [];
   if (!projectionJson || !stateJson || projectionJson.length > MAX_PROJECTION_CHARS) return [];
   const state = parsePublicationVersionStateV1Json(stateJson);
   if (!state.ok) return [];

package/apps/storefront/src/lib/publication/runtimeSource.ts

@@ -12,6 +12,7 @@ import {
   type PublicationRoutePlanV1,
   type RouteTierIndexV1,
 } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
 
 export interface PublicationStateStoreV1 {
   get(key: string): Promise<string | null>;
@@ -110,7 +111,9 @@ export type PublicationRuntimeSourceV1 =
  * Resolve one live request from the public KV state projection into its exact
  * immutable artifact. A carried plan is checked against current route authority
  * before state or object-store I/O. Only an unselected root keeps the legacy
- * adapter; a mounted space never falls through to root content.
+ * adapter; a mounted space never falls through to root content — except under a
+ * whole-site recovery (`publicationRecoveryKeyV1`), when every public space serves
+ * the tenant's whole-site release on `live`, exactly as before its spaces went live.
  */
 export async function resolvePublicationRuntimeSourceV1(input: {
   index: RouteTierIndexV1;
@@ -132,11 +135,18 @@ export async function resolvePublicationRuntimeSourceV1(input: {
   }
 
   let stateJson: string | null;
+  let recoveryJson: string | null = null;
   try {
-    stateJson = await input.store.get(publicationVersionStateKey(input.plan.manifest.tenant));
+    [stateJson, recoveryJson] = await Promise.all([
+      input.store.get(publicationVersionStateKey(input.plan.manifest.tenant)),
+      input.channel === "live" && input.plan.manifest.visibility === "public"
+        ? input.store.get(publicationRecoveryKeyV1(input.plan.manifest.tenant))
+        : Promise.resolve(null),
+    ]);
   } catch {
     return { status: "unavailable", code: "publication_artifact_source_unavailable" };
   }
+  if (publicationRecoveryActiveV1(recoveryJson)) return { status: "legacy-root" };
   if (stateJson === null) {
     return isRoot
       ? { status: "legacy-root" }

package/apps/storefront/src/lib/publication/servingMode.ts

@@ -0,0 +1,52 @@
+/**
+ * Whether a tenant's ROOT is served by a publication space, which decides what a whole-site
+ * promotion (ship, rollback, hotfix, re-publish, platform reconcile) can do for it.
+ *
+ * While the root public space is live and no whole-site recovery holds, a whole-site promotion
+ * cannot reach visitors: on Cloudflare the selected root space shadows the whole-site live channel
+ * (the job would report success while visitors kept the space), and on CloudFront the aggregate
+ * pointer refuses a whole-site publish after minutes of rendering. So it refuses up front with
+ * `publication_root_is_space`, naming the root space and how its content goes live instead.
+ *
+ * Behaviour follows the declared topology and the editorial state, never the tenant id.
+ */
+import type { PublicationVersionStateV1, TenantConfig } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
+
+export const PUBLICATION_ROOT_IS_SPACE = "publication_root_is_space";
+
+export type PublicationServingModeV1 =
+  | { mode: "whole-site"; reason: "no-root-space" | "root-not-live" | "recovered" }
+  | { mode: "spaces"; root: { spaceId: string; versionId: string; revision: number; source: string } };
+
+export async function publicationServingModeV1(input: {
+  tenant: Pick<TenantConfig, "tenant_id" | "publicationSpaces">;
+  readState(): Promise<PublicationVersionStateV1>;
+  kvGet(key: string): Promise<string | null>;
+}): Promise<PublicationServingModeV1> {
+  const root = input.tenant.publicationSpaces?.find((space) => space.tenant === input.tenant.tenant_id &&
+    space.visibility === "public" && space.routes.canonicalMount === "/");
+  if (!root) return { mode: "whole-site", reason: "no-root-space" };
+  if (publicationRecoveryActiveV1(await input.kvGet(publicationRecoveryKeyV1(input.tenant.tenant_id)))) {
+    return { mode: "whole-site", reason: "recovered" };
+  }
+  const pointer = (await input.readState()).pointers.find((candidate) =>
+    candidate.tenant === input.tenant.tenant_id && candidate.spaceId === root.id && candidate.channel === "live");
+  if (!pointer) return { mode: "whole-site", reason: "root-not-live" };
+  return { mode: "spaces", root: { spaceId: root.id, versionId: pointer.versionId, revision: pointer.revision,
+    source: `${root.source.forge}:${root.source.repo}` } };
+}
+
+/** The refusal a whole-site promotion gets while the root is a live publication space. */
+export function publicationRootIsSpaceRefusalV1(
+  tenantId: string,
+  mode: Extract<PublicationServingModeV1, { mode: "spaces" }>,
+): string {
+  const { spaceId, versionId, revision, source } = mode.root;
+  return `${PUBLICATION_ROOT_IS_SPACE}: ${tenantId}'s root is served by publication space "${spaceId}" ` +
+    `(source ${source}, live ${versionId} at revision ${revision}), so a whole-site release would never reach visitors. ` +
+    `Put root content live by activating a root-space version: build it ` +
+    `(scripts/publish/build-publication-space-version.ts --tenant ${tenantId} --space ${spaceId} --source-sha <sha>), then ` +
+    `POST /api/publication-spaces/${spaceId}/review and /api/publication-spaces/${spaceId}/activate. ` +
+    `To serve the whole site instead, recover it first (scripts/publish/recover-publication-tenant.mjs recover).`;
+}

package/apps/storefront/src/pages/tenants/[id]/[...path].ts

@@ -41,6 +41,7 @@ import {
   type R2BucketLike,
   type TenantConfig,
 } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
 import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
 import { readR2, readKv, readEnv } from "@/lib/env";
 import {
@@ -95,8 +96,12 @@ async function tryServePublicationRootAsset(input: {
   const tenant = input.tenant;
   if (!tenant || tenant.tenant_id !== input.tenantId ||
     !tenant.publicationSpaces?.some((space) => space.routes.canonicalMount === "/")) return null;
-  const stateJson = await input.kvGet(publicationVersionStateKey(input.tenantId));
-  if (stateJson === null) return null;
+  const [stateJson, recoveryJson] = await Promise.all([
+    input.kvGet(publicationVersionStateKey(input.tenantId)),
+    input.channel === "live" ? input.kvGet(publicationRecoveryKeyV1(input.tenantId)) : Promise.resolve(null),
+  ]);
+  // A whole-site recovery serves the whole-site release's assets, through the legacy pointer.
+  if (stateJson === null || publicationRecoveryActiveV1(recoveryJson)) return null;
   const state = parsePublicationVersionStateV1Json(stateJson);
   if (!state.ok) return null;
   const read = await readPublicationRootAssetV1({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.25",
+  "version": "2.4.26",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -21,6 +21,7 @@
     "./embed-catalog": "./src/embed-catalog.mjs",
     "./retention-holds": "./src/retention-holds.ts",
     "./publication-content-redirects": "./src/publication-content-redirects.ts",
+    "./publication-recovery": "./src/publication-recovery.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./declared-tenant-config": "./src/declared-tenant-config.mjs",
     "./compliance-coherence": "./src/compliance-coherence.mjs",

package/packages/public-runtime/src/publication-recovery.ts

@@ -0,0 +1,132 @@
+/**
+ * A whole-site recovery: a tenant served by its public publication spaces is put back on a
+ * whole-site release, and later resumed onto its spaces, each in one reviewed action
+ * (scripts/publish/recover-publication-tenant.mjs).
+ *
+ * The Worker holds the record under `publicationRecoveryKeyV1(tenant)`. While it is present every
+ * public space of the tenant serves through the whole-site path instead (`legacy-root`), whatever
+ * its live pointer selects; the editorial state is untouched, so a resume serves exactly what was
+ * live before plus anything activated during the recovery. On CloudFront the same fence rides in
+ * the KVS `live` value (scripts/publish/lib/cloudfront-live-pointer.mjs).
+ *
+ * Every recover and resume also writes an immutable audit record under
+ * `publicationRecoveryAuditKeyV1`, which is never deleted.
+ */
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+import type { PublicationVersionStateV1 } from "./publication-version.js";
+
+export const PUBLICATION_RECOVERY_ID_RE = /^rcv_[a-z0-9][a-z0-9-]{6,78}[a-z0-9]$/;
+const SHA40_RE = /^[0-9a-f]{40}$/;
+const DIGEST_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const PRINCIPAL_RE = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/;
+const INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+/** One public space as it was serving when the recovery replaced it. */
+export interface PublicationRecoverySpaceV1 {
+  spaceId: string;
+  revision: number;
+  versionId: string;
+}
+
+export interface PublicationRecoveryV1 {
+  schemaVersion: 1;
+  tenant: string;
+  recoveryId: string;
+  /**
+   * The whole-site release now served: its version (a tenant commit sha) and bundle digest, each
+   * null when the tenant has none on that plane (a tenant whose whole site is its committed
+   * baseline has neither).
+   */
+  wholeSite: { versionId: string | null; digest: string | null };
+  /** The public spaces' live pointers it replaced, and their generation (the sum of revisions). */
+  fromSpaces: { generation: number; spaces: PublicationRecoverySpaceV1[] };
+  principal: string;
+  at: string;
+}
+
+export type PublicationRecoveryEventV1 = "recover" | "resume";
+
+export function publicationRecoveryKeyV1(tenant: string): string {
+  return `cust:publication-recovery:${tenant}`;
+}
+
+export function publicationRecoveryAuditKeyV1(tenant: string, recoveryId: string, event: PublicationRecoveryEventV1): string {
+  if (!PUBLICATION_RECOVERY_ID_RE.test(recoveryId)) throw new Error("publication recovery id is malformed");
+  return `cust:publication-recovery-audit:${tenant}:${recoveryId}:${event}`;
+}
+
+function exactKeys(value: object, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function nullable(value: unknown, re: RegExp): value is string | null {
+  return value === null || (typeof value === "string" && re.test(value));
+}
+
+export function validatePublicationRecoveryV1(value: unknown): value is PublicationRecoveryV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (!exactKeys(record, ["schemaVersion", "tenant", "recoveryId", "wholeSite", "fromSpaces", "principal", "at"])) return false;
+  const wholeSite = record.wholeSite as Record<string, unknown> | null;
+  const fromSpaces = record.fromSpaces as Record<string, unknown> | null;
+  if (record.schemaVersion !== 1 || typeof record.tenant !== "string" || !record.tenant ||
+    typeof record.recoveryId !== "string" || !PUBLICATION_RECOVERY_ID_RE.test(record.recoveryId) ||
+    typeof record.principal !== "string" || !PRINCIPAL_RE.test(record.principal) ||
+    typeof record.at !== "string" || !INSTANT_RE.test(record.at) || new Date(record.at).toISOString() !== record.at ||
+    !wholeSite || typeof wholeSite !== "object" || !exactKeys(wholeSite, ["versionId", "digest"]) ||
+    !nullable(wholeSite.versionId, SHA40_RE) || !nullable(wholeSite.digest, DIGEST_RE) ||
+    !fromSpaces || typeof fromSpaces !== "object" || !exactKeys(fromSpaces, ["generation", "spaces"]) ||
+    !Array.isArray(fromSpaces.spaces) || fromSpaces.spaces.length === 0 ||
+    !Number.isSafeInteger(fromSpaces.generation)) return false;
+  let sum = 0;
+  const ids = new Set<string>();
+  for (const space of fromSpaces.spaces as unknown[]) {
+    if (!space || typeof space !== "object" || !exactKeys(space, ["spaceId", "revision", "versionId"])) return false;
+    const { spaceId, revision, versionId } = space as Record<string, unknown>;
+    if (typeof spaceId !== "string" || !spaceId || ids.has(spaceId) || typeof versionId !== "string" || !versionId ||
+      !Number.isSafeInteger(revision) || (revision as number) < 1) return false;
+    ids.add(spaceId);
+    sum += revision as number;
+  }
+  return sum === fromSpaces.generation;
+}
+
+export function parsePublicationRecoveryV1Json(json: string | null): PublicationRecoveryV1 | null {
+  if (json === null) return null;
+  try {
+    const value = JSON.parse(json) as unknown;
+    return validatePublicationRecoveryV1(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The tenant's public spaces as they serve on `live`, sorted by space, and their generation. This
+ * is what a recovery replaces and what its caller must name (a compare-and-set): for a CloudFront
+ * tenant it is the aggregate generation its publish wrote.
+ */
+export function publicationServingSpacesV1(
+  tenant: { tenant_id: string; publicationSpaces?: readonly PublicationSpaceManifestV1[] },
+  state: PublicationVersionStateV1,
+): { generation: number; spaces: PublicationRecoverySpaceV1[] } {
+  const spaces: PublicationRecoverySpaceV1[] = [];
+  for (const manifest of [...(tenant.publicationSpaces ?? [])].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+    if (manifest.visibility !== "public" || manifest.tenant !== tenant.tenant_id) continue;
+    const pointer = state.pointers.find((candidate) =>
+      candidate.tenant === tenant.tenant_id && candidate.spaceId === manifest.id && candidate.channel === "live");
+    if (pointer) spaces.push({ spaceId: manifest.id, revision: pointer.revision, versionId: pointer.versionId });
+  }
+  return { generation: spaces.reduce((sum, space) => sum + space.revision, 0), spaces };
+}
+
+/**
+ * Whether the tenant is recovered to its whole site, read fail-safe: a record that exists but does
+ * not validate still counts as recovered, because serving the whole site is the direction a
+ * recovery exists to guarantee. Only an absent record means the spaces serve.
+ */
+export function publicationRecoveryActiveV1(json: string | null): boolean {
+  return json !== null;
+}