@tokenoftrust/storefront-runner 2.4.24 → 2.4.26

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

@@ -1,12 +1,13 @@
 import {
-  publicationArtifactBundleKeyV1,
-  publicationArtifactFileBytesV1,
-  publicationArtifactKeyV1,
-  validatePublicationArtifactBundleV1,
-  type PublicationArtifactBundleV1,
-  type PublicationArtifactFileV1,
+  readPublicationArtifactFileV1,
+  readPublicationArtifactIndexV1,
+  type PublicationArtifactIndexFileV1,
+  type PublicationArtifactIndexV1,
+  type PublicationArtifactReadBucketV1,
+  type PublicationArtifactStoredObjectV1,
 } from "./publication-artifact.js";
 import {
+  resolvePublicationRoutePlanV1,
   selectPublicationRouteVersionV1,
   type PublicationRouteFailureCodeV1,
   type PublicationRoutePlanV1,
@@ -18,15 +19,10 @@ import type {
 } from "./publication-version.js";
 import type { RouteTierIndexV1 } from "./route-tier.js";
 
-export interface PublicationStoredObjectV1 {
-  text(): Promise<string>;
-  arrayBuffer(): Promise<ArrayBuffer>;
-}
+export type PublicationStoredObjectV1 = PublicationArtifactStoredObjectV1;
 
 /** Provider-neutral object-store read surface; R2 and test stores both satisfy it. */
-export interface PublicationArtifactBucketV1 {
-  get(key: string): Promise<PublicationStoredObjectV1 | null>;
-}
+export type PublicationArtifactBucketV1 = PublicationArtifactReadBucketV1;
 
 export type PublicationArtifactOpenFailureCodeV1 =
   | PublicationRouteFailureCodeV1
@@ -38,13 +34,17 @@ export type PublicationArtifactOpenFailureCodeV1 =
 
 export interface OpenPublicationArtifactV1 {
   selection: SelectedPublicationRouteV1;
-  bundle: PublicationArtifactBundleV1;
+  /** The admitted file index of the selected version. */
+  index: PublicationArtifactIndexV1;
   /** Read a UTF-8 artifact relative to the selected space's content/ root. */
   readContent(relativePath: string): string | null;
   /** List paths relative to the selected space's content/ root. */
   listContentPaths(prefix?: string): string[];
-  /** Read bytes relative to this space's declared asset namespace. */
-  readAsset(relativePath: string): Uint8Array | null;
+  /**
+   * Read bytes relative to this space's declared asset namespace. Fetched on demand and proven
+   * against the index, so opening a version never reads its assets.
+   */
+  readAsset(relativePath: string): Promise<Uint8Array | null>;
 }
 
 export type OpenPublicationArtifactResultV1 =
@@ -57,11 +57,6 @@ function safeRelativePath(path: string, allowEmpty = false): boolean {
     path.split("/").every((part) => !!part && part !== "." && part !== "..");
 }
 
-function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
-  return left.byteLength === right.byteLength &&
-    left.every((value, index) => value === right[index]);
-}
-
 /**
  * Open exactly one selected publication version and validate every physical
  * object before rendering from it. A route/state/provenance/object failure is
@@ -91,25 +86,7 @@ async function openSelectedPublicationArtifactV1(
   bucket: PublicationArtifactBucketV1,
 ): Promise<OpenPublicationArtifactResultV1> {
   const { manifest, publicationVersion } = selection;
-  let marker: PublicationStoredObjectV1 | null;
-  try {
-    marker = await bucket.get(publicationArtifactBundleKeyV1(
-      manifest.tenant,
-      manifest.id,
-      publicationVersion.versionId,
-    ));
-  } catch {
-    return { ok: false, code: "publication_artifact_source_unavailable" };
-  }
-  if (!marker) return { ok: false, code: "publication_artifact_marker_missing" };
-
-  let markerValue: unknown;
-  try {
-    markerValue = JSON.parse(await marker.text());
-  } catch {
-    return { ok: false, code: "publication_artifact_marker_malformed" };
-  }
-  const checked = await validatePublicationArtifactBundleV1(markerValue, {
+  const admitted = await readPublicationArtifactIndexV1(bucket, {
     tenant: manifest.tenant,
     spaceId: manifest.id,
     versionId: publicationVersion.versionId,
@@ -121,55 +98,38 @@ async function openSelectedPublicationArtifactV1(
     assetNamespace: manifest.assets.namespace,
     assetAccess: manifest.assets.access,
   });
-  if (!checked.ok) return { ok: false, code: "publication_artifact_marker_malformed" };
+  if (!admitted.ok) return { ok: false, code: admitted.code };
+  const { index } = admitted;
 
-  const physical = new Map<string, Uint8Array>();
-  for (const file of checked.value.files) {
-    const expected = publicationArtifactFileBytesV1(file);
-    if (!expected) return { ok: false, code: "publication_artifact_marker_malformed" };
-    let stored: PublicationStoredObjectV1 | null;
-    try {
-      stored = await bucket.get(publicationArtifactKeyV1(
-        manifest.tenant,
-        manifest.id,
-        publicationVersion.versionId,
-        file.lane,
-        file.path,
-      ));
-    } catch {
-      return { ok: false, code: "publication_artifact_source_unavailable" };
-    }
-    if (!stored) return { ok: false, code: "publication_artifact_file_missing" };
-    let actual: Uint8Array;
+  // The renderer reads content synchronously, so the content lane is loaded and proven up front.
+  // Assets are not: a page never needs every image its space carries.
+  const contentFiles = index.files.filter(
+    (file): file is PublicationArtifactIndexFileV1 & { encoding: "utf8" } =>
+      file.lane === "content" && file.encoding === "utf8" && file.path.startsWith("content/"),
+  );
+  const content = new Map<string, string>();
+  for (const file of contentFiles) {
+    const read = await readPublicationArtifactFileV1(bucket, index, file);
+    if (!read.ok) return { ok: false, code: read.code };
     try {
-      actual = new Uint8Array(await stored.arrayBuffer());
+      content.set(file.path, new TextDecoder("utf-8", { fatal: true }).decode(read.bytes));
     } catch {
-      return { ok: false, code: "publication_artifact_file_missing" };
-    }
-    if (!equalBytes(actual, expected)) {
       return { ok: false, code: "publication_artifact_file_mismatch" };
     }
-    physical.set(`${file.lane}\0${file.path}`, actual);
   }
-
-  const contentFiles = checked.value.files.filter(
-    (file): file is PublicationArtifactFileV1 & { encoding: "utf8" } =>
-      file.lane === "content" && file.encoding === "utf8" && file.path.startsWith("content/"),
-  );
   const assetLane = manifest.assets.access === "public" ? "public-asset" : "authorized-asset";
   const assetPrefix = `${manifest.assets.namespace}/`;
+  const assets = new Map(index.files
+    .filter((file) => file.lane === assetLane && file.path.startsWith(assetPrefix))
+    .map((file) => [file.path.slice(assetPrefix.length), file]));
   return {
     ok: true,
     value: {
       selection,
-      bundle: checked.value,
+      index,
       readContent(relativePath) {
         if (!safeRelativePath(relativePath)) return null;
-        const path = `content/${relativePath}`;
-        const file = contentFiles.find((candidate) => candidate.path === path);
-        if (!file) return null;
-        const bytes = physical.get(`content\0${path}`);
-        return bytes ? new TextDecoder().decode(bytes) : null;
+        return content.get(`content/${relativePath}`) ?? null;
       },
       listContentPaths(prefix = "") {
         if (!safeRelativePath(prefix.replace(/\/$/, ""), true)) return [];
@@ -178,10 +138,62 @@ async function openSelectedPublicationArtifactV1(
           .filter((path) => path.startsWith(prefix))
           .sort();
       },
-      readAsset(relativePath) {
+      async readAsset(relativePath) {
         if (!safeRelativePath(relativePath)) return null;
-        return physical.get(`${assetLane}\0${assetPrefix}${relativePath}`) ?? null;
+        const file = assets.get(relativePath);
+        if (!file) return null;
+        const read = await readPublicationArtifactFileV1(bucket, index, file);
+        return read.ok ? read.bytes : null;
       },
     },
   };
 }
+
+export type PublicationRootAssetReadV1 =
+  | { status: "legacy-root" }
+  | { status: "found"; bytes: Uint8Array; sha256: string }
+  | { status: "absent" };
+
+/**
+ * One file of the ROOT space's public asset lane, by its path under the namespace — what a
+ * whole-site tenant serves at `/tenants/<tenant>/<path>`. Reads the selected version's index and
+ * that one object, never the content lane. `legacy-root` when the tenant's root is not a public
+ * publication space this channel selected, so the legacy asset pointer still answers.
+ */
+export async function readPublicationRootAssetV1(input: {
+  index: RouteTierIndexV1;
+  state: PublicationVersionStateV1;
+  channel: PublicationChannelV1;
+  bucket: PublicationArtifactBucketV1;
+  relativePath: string;
+}): Promise<PublicationRootAssetReadV1> {
+  const plan = resolvePublicationRoutePlanV1(input.index, "/");
+  if (plan.action !== "render" || plan.manifest.routes.canonicalMount !== "/" ||
+    plan.manifest.visibility !== "public" || plan.manifest.assets.access !== "public") {
+    return { status: "legacy-root" };
+  }
+  const selected = selectPublicationRouteVersionV1(input.index, "/", plan, input.state, input.channel);
+  if (!selected.ok) {
+    return selected.code === "publication_channel_unselected" ? { status: "legacy-root" } : { status: "absent" };
+  }
+  if (!safeRelativePath(input.relativePath)) return { status: "absent" };
+  const { manifest, publicationVersion } = selected.value;
+  const admitted = await readPublicationArtifactIndexV1(input.bucket, {
+    tenant: manifest.tenant,
+    spaceId: manifest.id,
+    versionId: publicationVersion.versionId,
+    sourceSha: publicationVersion.source.commitSha,
+    artifactDigest: publicationVersion.artifactDigest,
+    forge: manifest.source.forge,
+    repo: manifest.source.repo,
+    visibility: manifest.visibility,
+    assetNamespace: manifest.assets.namespace,
+    assetAccess: manifest.assets.access,
+  });
+  if (!admitted.ok) return { status: "absent" };
+  const path = `${manifest.assets.namespace}/${input.relativePath}`;
+  const row = admitted.index.files.find((file) => file.lane === "public-asset" && file.path === path);
+  if (!row) return { status: "absent" };
+  const read = await readPublicationArtifactFileV1(input.bucket, admitted.index, row);
+  return read.ok ? { status: "found", bytes: read.bytes, sha256: row.sha256 } : { status: "absent" };
+}

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;
+}

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

@@ -12,6 +12,7 @@ import {
   publicationCollectionBaseV1,
   type PublicationCollectionV1,
 } from "./blog-visibility.mjs";
+import { normalizeRedirectPath } from "./publication-redirects.mjs";
 import {
   ANNOTATION_KEYS,
   type ContractResult,
@@ -113,6 +114,14 @@ export interface PublicationSpaceAliasV1 {
   to?: string;
 }
 
+/** One exact path the root space sends to another origin. */
+export interface PublicationSpaceExternalRedirectV1 {
+  /** Normalized exact request path (`/my-account/`), never a rule. */
+  from: string;
+  /** Absolute `https:` destination without credentials, query, or fragment. */
+  to: string;
+}
+
 export interface PublicationSpaceManifestV1 {
   version: typeof PUBLICATION_SPACE_MANIFEST_VERSION;
   id: string;
@@ -127,6 +136,11 @@ export interface PublicationSpaceManifestV1 {
      * it by `publicationCollectionPathV1`.
      */
     collections?: Partial<Record<PublicationCollectionV1, string>>;
+    /**
+     * Exact paths sent off the site, as a whole-site publish does. Only the ROOT space may declare
+     * them: a mounted space owns only its mount, and its redirects stay on the tenant's origin.
+     */
+    externalRedirects?: PublicationSpaceExternalRedirectV1[];
   };
   visibility: PublicationSpaceVisibilityV1;
   authorization:
@@ -500,6 +514,62 @@ function validateCollections(
   return Object.keys(out).length ? out : undefined;
 }
 
+function isExternalDestination(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash &&
+      url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "") === value;
+  } catch {
+    return false;
+  }
+}
+
+/** The root space's exact off-site redirects; a mounted space declaring any is refused. */
+function validateExternalRedirects(
+  raw: unknown,
+  canonicalMount: string | undefined,
+  v: Violations,
+  path: string,
+): PublicationSpaceExternalRedirectV1[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    v.add(path, "type", "Expected externalRedirects to be an array.");
+    return undefined;
+  }
+  if (canonicalMount !== undefined && canonicalMount !== "/") {
+    v.add(path, "publication_external_redirect_on_mount",
+      "Only the root space may redirect off the site; a mounted space owns only its mount.");
+  }
+  const out: PublicationSpaceExternalRedirectV1[] = [];
+  const seen = new Set<string>();
+  raw.forEach((item, index) => {
+    const at = `${path}[${index}]`;
+    const entry = reqObject(item, v, at);
+    if (!entry) return;
+    rejectPublicationUnknownKeys(entry, ["from", "to"], v, at);
+    const from = reqString(entry, "from", v, at);
+    const to = reqString(entry, "to", v, at);
+    if (from !== undefined && (normalizeRedirectPath(from) !== from || from === "/")) {
+      v.add(`${at}.from`, "publication_external_redirect_source",
+        "An off-site redirect source is one normalized exact path, never the site root or a rule.");
+      return;
+    }
+    if (to !== undefined && !isExternalDestination(to)) {
+      v.add(`${at}.to`, "publication_external_redirect_target",
+        "An off-site redirect target is an absolute https URL without credentials, query, or fragment.");
+      return;
+    }
+    if (from === undefined || to === undefined) return;
+    if (seen.has(from)) {
+      v.add(`${at}.from`, "publication_external_redirect_duplicate", "An off-site redirect source is declared twice.");
+      return;
+    }
+    seen.add(from);
+    out.push({ from, to });
+  });
+  return out.length ? out.sort((left, right) => left.from < right.from ? -1 : left.from > right.from ? 1 : 0) : undefined;
+}
+
 /** Validate, close, and normalize one serialized publication-space manifest. */
 export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult<PublicationSpaceManifestV1> {
   const v = new Violations();
@@ -519,8 +589,10 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
   let canonicalMount: string | undefined;
   let aliases: PublicationSpaceAliasV1[] | undefined;
   let collections: PublicationSpaceManifestV1["routes"]["collections"];
+  let externalRedirects: PublicationSpaceExternalRedirectV1[] | undefined;
   if (routes) {
-    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases", "collections"], v, "routes");
+    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases", "collections", "externalRedirects"], v,
+      "routes");
     const rawMount = reqString(routes, "canonicalMount", v, "routes");
     canonicalMount = rawMount
       ? append(v, "routes.canonicalMount", normalizePublicationPath(rawMount, { mode: "mount" }))
@@ -530,6 +602,8 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
     }
     aliases = validateAliases(routes["aliases"], canonicalMount, v, "routes.aliases");
     collections = validateCollections(routes["collections"], canonicalMount, v, "routes.collections");
+    externalRedirects = validateExternalRedirects(routes["externalRedirects"], canonicalMount, v,
+      "routes.externalRedirects");
   }
   const visibility = reqEnum<PublicationSpaceVisibilityV1>(root, "visibility", ["public", "internal"], v, "");
   const authorization = validateAuthorization(root["authorization"], v, "authorization");
@@ -581,6 +655,7 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
         canonicalMount,
         ...(aliases === undefined ? {} : { aliases }),
         ...(collections === undefined ? {} : { collections }),
+        ...(externalRedirects === undefined ? {} : { externalRedirects }),
       },
       visibility,
       authorization,