@tokenoftrust/storefront-runner 4.7.0 → 4.7.1

package/agency-kit/tools/lib/page-slugs.mjs

@@ -0,0 +1,113 @@
+// @ts-check
+/**
+ * Which editorial page slugs the hosted storefront router can serve.
+ *
+ * A page under `content/pages/<file>.json` is served at `/<slug>/`, where `<slug>` is the page's
+ * own JSON `slug` (never the file name), and a raw page `content/pages-html/<path>.html` is served
+ * at `/<path>/`. Both reach the platform's catch-all route, which every first-class platform route
+ * outranks. So a slug is servable only when:
+ *
+ *   - it is a string of one or more `/`-separated segments, each starting with a letter or digit
+ *     and holding only letters, digits, `-` and `_` (no leading/trailing or doubled slash, no `.`:
+ *     both CDNs treat a dotted last segment as a file, never a page);
+ *   - its first segment is not a route root the platform owns (`products`, `collections`, `blog`,
+ *     `api`, …) — the platform route answers first and the page is never reached;
+ *   - no other page, JSON or raw, claims the same slug — the router serves one of them.
+ *
+ * Pure: callers pass what they read, so the kit validator and `tot validate` apply one rule.
+ * `packages/cli/src/page-slugs.mjs` is a byte-identical copy (a test pins it).
+ */
+
+/**
+ * First path segments the platform's own routes answer before the editorial catch-all.
+ * Pinned against the storefront's route tree by scripts/lib/page-slug-reserved.test.mjs.
+ */
+export const RESERVED_PAGE_ROOTS = Object.freeze([
+  "_sitemap",
+  "account",
+  "admin",
+  "api",
+  "auth",
+  "blog",
+  "capabilities",
+  "cart",
+  "cockpit",
+  "collections",
+  "dashboard",
+  "diag",
+  "preview",
+  "products",
+  "saved",
+  "search",
+  "shared",
+  "style-guide",
+  "tenants",
+  "the-build",
+]);
+
+const SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Why `slug` cannot be served by the hosted router, or null when it can.
+ * @param {unknown} slug
+ * @returns {string | null}
+ */
+export function unservableSlugReason(slug) {
+  if (typeof slug !== "string" || slug.length === 0) return "has no string `slug`";
+  const segments = slug.split("/");
+  if (segments.some((segment) => !SEGMENT_RE.test(segment))) {
+    return `slug "${slug}" is not a page path: each "/"-separated segment must start with a letter or digit and hold only letters, digits, "-" and "_" (no leading, trailing or doubled "/", no ".")`;
+  }
+  const root = /** @type {string} */ (segments[0]);
+  if (RESERVED_PAGE_ROOTS.includes(root)) {
+    return `slug "${slug}" starts with "${root}/", a route the platform serves itself — the page is never reached`;
+  }
+  return null;
+}
+
+/**
+ * @typedef {Object} PageSlugFinding
+ * @property {string} code     `page-slug-unservable` | `page-slug-duplicate`
+ * @property {string} path     the declaring file, store-relative
+ * @property {string} message
+ * @property {string} remedy
+ */
+
+/**
+ * Every slug the hosted router cannot serve, across a store's JSON and raw pages.
+ * @param {{ pages?: ReadonlyArray<{ path: string, slug: unknown }>, rawPages?: ReadonlyArray<{ path: string, slug: string }> }} input
+ *   `pages`: each `content/pages/*.json` with its parsed `slug`; `rawPages`: each
+ *   `content/pages-html/**.html` with the slug its path encodes.
+ * @returns {PageSlugFinding[]}
+ */
+export function pageSlugFindings({ pages = [], rawPages = [] }) {
+  /** @type {PageSlugFinding[]} */
+  const findings = [];
+  /** @type {Map<string, string>} */
+  const claimed = new Map();
+  for (const { path, slug } of [...pages, ...rawPages]) {
+    const reason = unservableSlugReason(slug);
+    if (reason) {
+      findings.push({
+        code: "page-slug-unservable",
+        path,
+        message: `${reason}, so the hosted store answers 404 for it`,
+        remedy: "give the page a slug of plain path segments outside the platform's routes, and add a content/redirects.json entry from any old URL",
+      });
+      continue;
+    }
+    const key = /** @type {string} */ (slug);
+    const first = claimed.get(key);
+    if (first !== undefined) {
+      findings.push({
+        code: "page-slug-duplicate",
+        path,
+        message: `slug "${slug}" is also claimed by ${first} — the hosted store serves only one of them`,
+        remedy: "give each page its own slug",
+      });
+      continue;
+    }
+    claimed.set(key, path);
+  }
+  return findings;
+}

package/apps/storefront/src/lib/content/storyblok/provider.ts

@@ -261,6 +261,23 @@ async function readRawDevFile(scope: string, relative: string): Promise<string |
   }
 }
 
+/**
+ * An editorial page is routed by its JSON `slug`, never by its file name (`pages/<name>.json`
+ * may hold `"slug": "policies/terms-of-service"`). The file named after the slug is read first
+ * because it is the common layout; any other match needs the enumeration.
+ */
+async function pageBySlug(
+  slug: string,
+  read: (relative: string) => Promise<EditorialPage | null>,
+  list: () => Promise<EditorialPage[]>,
+): Promise<EditorialPage | null> {
+  const wanted = slug.replace(/^\/+|\/+$/g, "");
+  if (!wanted) return null;
+  const named = await read(`pages/${wanted}.json`);
+  if (named?.slug === wanted) return named;
+  return (await list()).find((page) => page.slug === wanted) ?? null;
+}
+
 export class LocalContentProvider implements ContentProvider {
   constructor(private readonly scope: string = DEFAULT_SCOPE) {}
 
@@ -714,8 +731,11 @@ export class PublishedContentProvider implements ContentProvider {
     return config ?? ((await this.usesVersionedContent()) ? EMPTY_CHROME_CONFIG : this.base.getChrome());
   }
   async getPage(slug: string): Promise<EditorialPage | null> {
-    const page = await this.published<EditorialPage>(`pages/${slug}.json`);
-    return page ?? ((await this.usesVersionedContent()) ? null : this.base.getPage(slug));
+    if (!(await this.usesVersionedContent())) {
+      const legacy = await this.published<EditorialPage>(`pages/${slug}.json`);
+      return legacy?.slug === slug ? legacy : this.base.getPage(slug);
+    }
+    return pageBySlug(slug, (relative) => this.published<EditorialPage>(relative), () => this.listPages());
   }
   async listPages(): Promise<EditorialPage[]> {
     // Editorial enumeration follows its source, not the generic artifact fallback.
@@ -824,7 +844,7 @@ export class VersionPinnedContentProvider implements ContentProvider {
     return config ?? EMPTY_CHROME_CONFIG;
   }
   async getPage(slug: string): Promise<EditorialPage | null> {
-    return this.pinned<EditorialPage>(`pages/${slug}.json`);
+    return pageBySlug(slug, (relative) => this.pinned<EditorialPage>(relative), () => this.listPages());
   }
   async listPages(): Promise<EditorialPage[]> {
     const paths = await this.listArtifactPaths("pages/");

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

@@ -70,6 +70,7 @@ import {
   MATERIALIZE_MODE_BINDING,
   verifyConsentSnapshotSig,
   resolveNativeGa4SandboxUrl,
+  CANDIDATE_CONTENT_PIN_PARAM,
 } from "@tot/public-runtime";
 import { readBakedManagedInstalls } from "@/lib/integrations/integration/bakedManagedInstalls";
 import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
@@ -274,13 +275,22 @@ export async function runRenderChain(input: RenderChainInput): Promise<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.
+  // A pinned render (staged/candidate revision) redirects inside the revision it reviews, and its
+  // one-shot pin token never reaches the browser.
+  const declaredRedirectHeaders = (location: string): HeadersInit => {
+    if (!location.startsWith("/")) return { location };
+    let search = url.search;
+    if (url.searchParams.has(CANDIDATE_CONTENT_PIN_PARAM)) {
+      const query = new URLSearchParams(url.search);
+      query.delete(CANDIDATE_CONTENT_PIN_PARAM);
+      search = query.toString() ? `?${query.toString()}` : "";
+    }
+    return { location: `${url.origin}${candidatePin ? candidatePin.basePath : basePath}${location}${search}` };
+  };
   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 },
-      });
+      const response = new Response(null, { status: 308, headers: declaredRedirectHeaders(location) });
       applySecurityHeaders(response.headers);
       if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
       return response;
@@ -355,10 +365,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   if (publicationSource.status === "legacy-root") {
     const location = await contentRedirectLocation(locals.content, renderPath);
     if (location) {
-      const response = new Response(null, {
-        status: 308,
-        headers: { location: location.startsWith("/") ? `${url.origin}${basePath}${location}${url.search}` : location },
-      });
+      const response = new Response(null, { status: 308, headers: declaredRedirectHeaders(location) });
       applySecurityHeaders(response.headers);
       return response;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "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/scripts/tenant/validate.mjs

@@ -46,6 +46,7 @@ import {
   workspacePathForTenantRelative,
 } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 import { isForbiddenPublicPath, publicBinaryFindings } from "../../agency-kit/tools/lib/public-binaries.mjs";
+import { pageSlugFindings } from "../../agency-kit/tools/lib/page-slugs.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
 import { declaredObligations, isRegulatedCompliance, validateDeclaredConfig } from "../../packages/cli/src/declared-config.mjs";
 
@@ -1200,6 +1201,18 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // 3b. editorial page slugs — every page must be reachable at its slug on the hosted router
+  // (agency-kit/tools/lib/page-slugs.mjs, the rule `tot validate` applies).
+  {
+    const pages = walk(join(contentDir, "pages"), (x) => x.endsWith(".json")).sort().map((p) => {
+      const { value, error } = readJsonSafe(p);
+      return { path: rel(p), slug: error ? undefined : value?.slug };
+    });
+    const rawPages = walk(pagesDir, (x) => x.endsWith(".html")).sort()
+      .map((p) => ({ path: rel(p), slug: relative(pagesDir, p).split("\\").join("/").replace(/\.html$/, "") }));
+    for (const f of pageSlugFindings({ pages, rawPages })) findings.push(mk(ERROR, f.code, f.path, f.message, f.remedy));
+  }
+
   // 4. raw HTML documents — validate + portability + resolution
   const hasChrome = providesChrome(contentDir);
   const htmlFiles = walk(contentDir, (p) => p.endsWith(".html"));