@tokenoftrust/storefront-runner 2.4.24 → 2.4.26

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

@@ -62,8 +62,23 @@ export class PublicationSpaceContentProvider implements ContentProvider {
   constructor(
     private readonly sharedRoot: ContentProvider,
     private readonly publication: OpenPublicationArtifactV1,
+    /**
+     * A discovery document (sitemap, feeds, search index, llms.txt) lists every page of the space,
+     * so it reads any of them; a page request reads only the page its plan selected.
+     */
+    private readonly wholeSpace = false,
   ) {}
 
+  /** The space-relative slug a page request may read, or null. `""` is the space's home. */
+  private readableSlug(slug: string): string | null {
+    if (!this.wholeSpace) return selectedPageSlug(this.plan, slug);
+    const requested = stripSlashes(slug);
+    const mount = stripSlashes(this.plan.manifest.routes.canonicalMount);
+    if (!mount) return requested;
+    if (requested === mount) return "";
+    return requested.startsWith(`${mount}/`) ? requested.slice(mount.length + 1) : null;
+  }
+
   private get plan(): PublicationRouteRenderPlanV1 {
     return this.publication.selection;
   }
@@ -86,7 +101,7 @@ export class PublicationSpaceContentProvider implements ContentProvider {
   }
 
   async getPageHtml(slug: string): Promise<string | null> {
-    const selected = selectedPageSlug(this.plan, slug);
+    const selected = this.readableSlug(slug);
     if (selected === null) return null;
     const raw = this.publication.readContent(
       selected ? `pages-html/${selected}.html` : "home.html",
@@ -122,10 +137,11 @@ export class PublicationSpaceContentProvider implements ContentProvider {
   }
 
   async getPage(slug: string): Promise<EditorialPage | null> {
-    const selected = selectedPageSlug(this.plan, slug);
+    const selected = this.readableSlug(slug);
     if (!selected) return null;
     const page = (await this.sourcePages()).find((candidate) => candidate.slug === selected);
-    return page ? rebasePage(this.plan, page, stripSlashes(this.plan.canonicalPath)) : null;
+    if (!page) return null;
+    return this.wholeSpace ? rebasePage(this.plan, page) : rebasePage(this.plan, page, stripSlashes(this.plan.canonicalPath));
   }
 
   async listPages(): Promise<EditorialPage[]> {
@@ -152,8 +168,9 @@ export class PublicationSpaceContentProvider implements ContentProvider {
 export function bindPublicationSpaceContentProviderV1(
   sharedRoot: ContentProvider,
   publication?: OpenPublicationArtifactV1,
+  options: { wholeSpace?: boolean } = {},
 ): ContentProvider {
   return publication
-    ? new PublicationSpaceContentProvider(sharedRoot, publication)
+    ? new PublicationSpaceContentProvider(sharedRoot, publication, options.wholeSpace ?? false)
     : sharedRoot;
 }

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/middleware/index.ts

@@ -25,7 +25,7 @@ import { getTenantResolver } from "@/config/resolver";
 import { readEnv, readKv, readR2 } from "@/lib/runtimeEnv";
 import { resolveCdnForwardRouting, resolveTenantRouting } from "@/lib/tenantRouting";
 import { crossSiteFormRefusal, verifyCdnForward } from "@/lib/cdnForward";
-import { compileRouteTierIndexV1, type RouteTierIndexV1 } from "@tot/public-runtime";
+import { compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 } from "@tot/public-runtime";
 import type { PublicationArtifactBucketV1, TenantConfig } from "@tot/public-runtime";
 import { DEV_DRAFT_COOKIE } from "@/lib/dev/devDraft";
 import { applySecurityHeaders } from "@/lib/securityHeaders";
@@ -39,6 +39,7 @@ import { HEALTH_PATH, healthResponse } from "@/lib/health";
 import { observeDeployVersion } from "@/lib/activity/deployVersion";
 import { primeActivityKillSwitch } from "@/lib/activity/killSwitch";
 import {
+  isPlatformPublicDiscoveryPath,
   platformStaticRootLocationV1,
   publicationRedirectLocationV1,
   resolveMiddlewareBranchV1,
@@ -314,6 +315,14 @@ async function serveRequest(
     return asset;
   }
 
+  // A tenant's discovery documents (sitemap, feeds, search index, llms.txt, robots) are the root's:
+  // when the root is a publication space, they render from its selected version, as its pages do.
+  const discoveryRoot = isPlatformPublicDiscoveryPath(renderPath)
+    ? resolvePublicationRoutePlanV1(routeTierIndexFor(tenant), "/")
+    : null;
+  const publicationSourceRoute = discoveryRoot?.action === "render" ? discoveryRoot : publication;
+  const publicationSourcePath = discoveryRoot?.action === "render" ? "/" : renderPath;
+
   if (branch === "public-render") {
     return await servePublicRender({
       context,
@@ -326,9 +335,11 @@ async function serveRequest(
       cache,
       kv,
       routeTierIndex: routeTierIndexFor(tenant),
-      publicationRequestPath: renderPath,
-      publicationRoute: publication,
-      publicationBucket,
+      publicationRequestPath: publicationSourcePath,
+      publicationRoute: publicationSourceRoute,
+      publicationBucket: discoveryRoot?.action === "render"
+        ? await readR2("TENANT_ASSETS") as unknown as PublicationArtifactBucketV1 | undefined
+        : publicationBucket,
     });
   }
 

package/apps/storefront/src/middleware/renderChain.ts

@@ -14,6 +14,7 @@ import { mergeTheme, themeToCssVars } from "@/themes/schema";
 import { createToTClient } from "@/lib/tot/ToTClient";
 import { readEnv, readR2 } from "@/lib/runtimeEnv";
 import { tryServeStaticBundle } from "./staticBundle.js";
+import { isPlatformPublicDiscoveryPath } from "./routeBranch.js";
 import { resolveCandidateContentPin, type CandidateContentPin } from "./candidatePin.js";
 import { createContentProvider, DevDraftContentProvider } from "@/lib/storyblok/provider";
 import { bindPublicationSpaceContentProviderV1 } from "@/lib/publication/contentProvider.js";
@@ -82,6 +83,7 @@ import {
   HTML_CACHE_POLICY_CAPTURE_HEADER,
   HTML_CACHE_POLICY_CAPTURE_PROBE,
 } from "@tot/public-runtime";
+import { publicationContentRedirectLocationV1 } from "@tot/public-runtime/publication-content-redirects";
 import { loadTenantIntegrationDeclarations } from "@/lib/integration/tenantDeclarations";
 import { resolveTenantCommerce } from "@/lib/checkoutCommerce";
 import {
@@ -236,6 +238,21 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
     return response;
   }
+  // The owning space's content-declared redirects answer before anything renders, as the CloudFront
+  // redirect plane does for the same declarations: a same-origin target keeps the path-routing prefix
+  // and the query; an off-site target (the root space only) is sent as declared.
+  if (publicationSource.status === "selected") {
+    const location = publicationContentRedirectLocationV1(publicationSource.artifact, input.publicationRequestPath);
+    if (location) {
+      const response = new Response(null, {
+        status: 308,
+        headers: { location: location.startsWith("/") ? `${url.origin}${basePath}${location}${url.search}` : location },
+      });
+      applySecurityHeaders(response.headers);
+      if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
+      return response;
+    }
+  }
 
   // The tenant as it renders in THIS environment: its record with the declared
   // `.tot/config.json` fields applied (compliance, siteType, capabilities,
@@ -613,6 +630,8 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   locals.content = bindPublicationSpaceContentProviderV1(
     sharedRootContent,
     publicationSource.status === "selected" ? publicationSource.artifact : undefined,
+    // A discovery document lists the whole space it is bound to, not one selected page.
+    { wholeSpace: isPlatformPublicDiscoveryPath(renderPath) },
   );
   // Developer-draft content overlay — serves the AI-edited artifacts to the draft
   // owner only; every other viewer keeps the published/base chain above.

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

@@ -17,6 +17,10 @@
  * Preview sessions also consult the image-capture rewrite overlay so rewritten
  * `public/*.css` (and similar text assets) serve `/_a/<sha>` references.
  *
+ * A tenant whose ROOT is a publication space serves these paths from that space's selected version
+ * (its public asset lane, `<namespace>/<path>`), the same URL a whole-site tenant serves them at;
+ * otherwise the legacy asset pointer below answers.
+ *
  * Version selection, in order: a candidate/revision pin (`tot_preview_version` +
  * token cookie); else, for a shared-preview viewer (preview host, or a valid token
  * for this tenant), the version the content `preview` channel serves — what the
@@ -24,12 +28,20 @@
  */
 import type { APIContext } from "astro";
 import {
+  ASSET_CACHE_CONTROL,
   assetContentType,
+  compileRouteTierIndexV1,
+  parsePublicationVersionStateV1Json,
   parseTenantAssetPath,
+  publicationVersionStateKey,
+  readPublicationRootAssetV1,
   resolveChannelVersion,
   serveTenantAsset,
+  type PublicationArtifactReadBucketV1,
   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 {
@@ -68,6 +80,46 @@ async function tryServePreviewRewriteOverlay(input: {
   });
 }
 
+/** The root publication space's asset, or null when the tenant's root is not a selected space. */
+async function tryServePublicationRootAsset(input: {
+  /** The tenant the request resolved to (`Astro.locals.tenant`). */
+  tenant: TenantConfig | undefined;
+  bucket: PublicationArtifactReadBucketV1;
+  kvGet: (key: string) => Promise<string | null>;
+  tenantId: string;
+  pathname: string;
+  channel: "live" | "preview";
+  ifNoneMatch: string | null;
+}): Promise<Response | null> {
+  const parsed = parseTenantAssetPath(input.pathname);
+  if (!parsed || parsed.tenantId !== input.tenantId) return null;
+  const tenant = input.tenant;
+  if (!tenant || tenant.tenant_id !== input.tenantId ||
+    !tenant.publicationSpaces?.some((space) => space.routes.canonicalMount === "/")) 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({
+    index: compileRouteTierIndexV1(tenant), state: state.value, channel: input.channel,
+    bucket: input.bucket, relativePath: parsed.rel,
+  });
+  if (read.status === "legacy-root") return null;
+  if (read.status === "absent") {
+    return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  }
+  const etag = `"${read.sha256}"`;
+  const headers = { "content-type": assetContentType(parsed.rel), "cache-control": ASSET_CACHE_CONTROL, etag };
+  if (input.ifNoneMatch && input.ifNoneMatch.split(",").some((value) => value.trim().replace(/^W\//, "") === etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(read.bytes as Uint8Array<ArrayBuffer>, { status: 200, headers });
+}
+
 export async function GET(context: APIContext): Promise<Response> {
   const [bucket, kv] = await Promise.all([
     readR2("TENANT_ASSETS"),
@@ -106,6 +158,17 @@ export async function GET(context: APIContext): Promise<Response> {
   const previewVersionId = pinnedVersionId ?? sharedPreview.versionId;
 
   const pathname = url.pathname;
+  const fromPublication = await tryServePublicationRootAsset({
+    tenant: context.locals.tenant,
+    bucket: bucket as unknown as PublicationArtifactReadBucketV1,
+    kvGet: (key) => kv.get(key),
+    tenantId: urlTenant,
+    pathname,
+    channel: sharedPreview.preview || context.locals.customizationEnv === "test" ? "preview" : "live",
+    ifNoneMatch: context.request.headers.get("if-none-match"),
+  });
+  if (fromPublication) return fromPublication;
+
   if (previewVersionId) {
     const overlay = await tryServePreviewRewriteOverlay({
       kvGet: (key) => kv.get(key),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.24",
+  "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

@@ -20,6 +20,8 @@
     "./catalog-files": "./src/catalog-files.ts",
     "./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/schemas/publication-space/v1/manifest.schema.json

@@ -85,6 +85,19 @@
             "blog": { "$ref": "#/$defs/collectionBase" },
             "the-build": { "$ref": "#/$defs/collectionBase" }
           }
+        },
+        "externalRedirects": {
+          "description": "Exact paths the ROOT space sends to another origin; a mounted space declares none.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to"],
+            "properties": {
+              "from": { "$ref": "#/$defs/path" },
+              "to": { "type": "string", "pattern": "^https://[^/?#@\\s]+(?:/[^?#\\s]*)?$" }
+            }
+          }
         }
       }
     },