@tokenoftrust/storefront-runner 2.0.13 → 2.0.14

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

@@ -23,7 +23,9 @@ import type { CustomizationEnv, KvGet, TenantConfig } from "@tot/public-runtime"
 import {
   contentArtifactPath,
   listPublishedArtifactPaths,
+  listVersionArtifactPaths,
   readPublishedArtifact,
+  readVersionArtifact,
   tenantDirRelative,
   tenantDirSegment,
 } from "@tot/public-runtime";
@@ -681,6 +683,99 @@ export class PublishedContentProvider implements ContentProvider {
   }
 }
 
+// ---------------------------------------------------------------------------
+// VersionPinnedContentProvider — pins content to ONE exact immutable
+// `versionId`, bypassing channel/pointer resolution entirely (the candidate/
+// revision preview's read path). Structurally the version-pinned twin of
+// PublishedContentProvider (channel -> versionId vs. versionId direct); every
+// method mirrors it 1:1 so a candidate's OWN pages/blog/products/etc. render
+// through the exact same generic-content plumbing as a live/preview page,
+// pinned to the exact commit under review instead of the shared channel.
+// ---------------------------------------------------------------------------
+
+export class VersionPinnedContentProvider implements ContentProvider {
+  constructor(
+    private readonly base: ContentProvider,
+    private readonly tenantId: string,
+    private readonly get: KvGet,
+    private readonly versionId: string,
+  ) {}
+
+  private pinnedRaw(relative: string): Promise<string | null> {
+    return readVersionArtifact(
+      this.get,
+      this.tenantId,
+      this.versionId,
+      contentArtifactPath(this.tenantId, relative),
+    );
+  }
+
+  private async pinned<T>(relative: string): Promise<T | null> {
+    const raw = await this.pinnedRaw(relative);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async getHome(): Promise<HomeContent> {
+    return (await this.pinned<HomeContent>("home.json")) ?? this.base.getHome();
+  }
+  async getHomeHtml(): Promise<string | null> {
+    const raw = await this.pinnedRaw("home.html");
+    return raw !== null ? stampTrackingIdsAtPublish(raw) : this.base.getHomeHtml();
+  }
+  async getPageHtml(slug: string): Promise<string | null> {
+    const rel = `pages-html/${normalizeRawPageSlug(slug)}.html`;
+    const raw = await this.pinnedRaw(rel);
+    return raw !== null ? stampTrackingIdsAtPublish(raw) : this.base.getPageHtml(slug);
+  }
+  listPageHtmlSlugs(): Promise<string[]> {
+    return this.listArtifactPaths("pages-html/").then((paths) =>
+      paths === null
+        ? this.base.listPageHtmlSlugs()
+        : paths
+            .filter((path) => path.endsWith(".html"))
+            .map((path) => path.slice("pages-html/".length, -".html".length)),
+    );
+  }
+  async getChromeHtml(currentPath?: string): Promise<string | null> {
+    const publishedHtml = await this.pinnedRaw("chrome.html");
+    if (publishedHtml) return stampTrackingIdsAtPublish(publishedHtml);
+    const config = parseChromeConfig(await this.pinned<unknown>("chrome.json"));
+    if (config) {
+      const assignments = parseChromeAssignments(await this.pinned<unknown>("chrome-assignments.json"));
+      return renderRawChrome(config, currentPath, assignments);
+    }
+    return this.base.getChromeHtml(currentPath);
+  }
+  async getChrome(): Promise<ChromeConfig> {
+    const config = parseChromeConfig(await this.pinned<unknown>("chrome.json"));
+    return config ?? this.base.getChrome();
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    return (await this.pinned<EditorialPage>(`pages/${slug}.json`)) ?? this.base.getPage(slug);
+  }
+  async listPages(): Promise<EditorialPage[]> {
+    const paths = await this.listArtifactPaths("pages/");
+    if (paths === null) return this.base.listPages();
+    const pages = await Promise.all(
+      paths.filter((path) => path.endsWith(".json")).map(async (path) => this.pinned<EditorialPage>(path)),
+    );
+    return pages.filter((page): page is EditorialPage => page !== null);
+  }
+
+  readArtifact(relative: string): Promise<string | null> {
+    return this.pinnedRaw(relative);
+  }
+
+  async listArtifactPaths(prefix = ""): Promise<string[] | null> {
+    return listVersionArtifactPaths(this.get, this.tenantId, this.versionId, prefix);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // DevDraftContentProvider — the per-developer DRAFT overlay. Wraps the
 // resolved provider chain and serves a
@@ -747,9 +842,22 @@ export class DevDraftContentProvider implements ContentProvider {
 
 const PLACEHOLDER_TOKEN_RE = /PLACEHOLDER|^$/i;
 
+/**
+ * Pin content resolution to ONE exact immutable `versionId` instead of a
+ * `{live,test}` channel — the candidate/revision preview's read path (see
+ * `VersionPinnedContentProvider`). Takes priority over `customization` when
+ * both are given: a pinned candidate render must never fall through to the
+ * shared channel.
+ */
+export interface ContentVersionPin {
+  get: KvGet;
+  versionId: string;
+}
+
 export function createContentProvider(
   tenant: TenantConfig,
   customization?: ContentCustomization,
+  pin?: ContentVersionPin,
 ): ContentProvider {
   // Content dirs are keyed by tenant_id (the adopter writes content/<tenant>/).
   const local = new LocalContentProvider(tenant.tenant_id);
@@ -758,6 +866,9 @@ export function createContentProvider(
   const base: ContentProvider = usable
     ? new StoryblokContentProvider(token, local)
     : local;
+  if (pin) {
+    return new VersionPinnedContentProvider(base, tenant.tenant_id, pin.get, pin.versionId);
+  }
   return customization
     ? new PublishedContentProvider(base, tenant.tenant_id, customization)
     : base;

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

@@ -27,6 +27,8 @@ import { STATIC_SCRIPT_HASHES, STATIC_STYLE_HASHES } from "@/lib/cspStaticHashes
 import { applySecurityHeaders } from "@/lib/securityHeaders";
 import { maybeInjectPreviewReload } from "@/lib/previewReload";
 import {
+  CANDIDATE_CONTENT_PIN_PARAM,
+  verifyContentPinToken,
   resolveCustomizationEnv,
   buildCsp,
   STOREFRONT_CSP_ALLOWLIST,
@@ -288,6 +290,34 @@ export const onRequest = defineMiddleware(async (context, next) => {
   const isPreviewHost = host.toLowerCase().startsWith("preview.");
   const queryToken = url.searchParams.get("__preview");
   const cookieToken = context.cookies.get("tot_preview")?.value ?? null;
+
+  // Candidate-render CONTENT PIN (`__tot_candidate_pin`): a signed, tenant- and
+  // expiry-bound token minted ONLY by the control-plane candidate/revision
+  // renderers (`src/lib/preview/pinnedRouteRender.ts`, never client-forgeable)
+  // that pins THIS one render's content resolution to an exact immutable
+  // `versionId`, bypassing the shared `{live,test}` channel entirely. It rides
+  // an in-process `context.rewrite()` from those renderers so a real Astro
+  // route (blog, editorial pages, …) — not just the raw `home.html`/
+  // `pages-html/*` documents they serve directly — renders pinned to the
+  // candidate under review (fb-1788536381607). Verified here so it can only
+  // ever name the resolved tenant's own version; a mismatched/expired/absent
+  // token falls through to the normal channel-resolved read below, same
+  // fail-closed posture as the `__preview` token.
+  const candidatePinParam = url.searchParams.get(CANDIDATE_CONTENT_PIN_PARAM);
+  let candidatePin: { versionId: string; basePath: string } | null = null;
+  if (candidatePinParam) {
+    const pinSecret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+    if (pinSecret) {
+      const verified = await verifyContentPinToken(
+        pinSecret,
+        candidatePinParam,
+        Math.floor(Date.now() / 1000),
+      );
+      if (verified.ok && verified.claims.tenantId === tenant.tenant_id) {
+        candidatePin = { versionId: verified.claims.versionId, basePath: verified.claims.basePath };
+      }
+    }
+  }
   // Per-developer AI-edit draft: the signed
   // tot_dev_draft cookie's mere PRESENCE opts the request out of the shared page
   // cache below (a draft view must never be cached publicly); it's verified —
@@ -329,6 +359,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
     !isPreviewHost &&
     !queryToken &&
     !cookieToken &&
+    !candidatePin &&
     !draftCookie &&
     managedIntegrationDeclarations.length === 0 &&
     !url.pathname.startsWith("/api/");
@@ -451,6 +482,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
     !isPreviewHost &&
     !queryToken &&
     !cookieToken &&
+    !candidatePin &&
     !draftCookie &&
     isCacheablePath(url.pathname, url.searchParams);
   let pageKey: Request | null = null;
@@ -662,10 +694,15 @@ export const onRequest = defineMiddleware(async (context, next) => {
       : null;
   locals.commerce = commerce ?? undefined;
   locals.tot = tot;
-  locals.content = createContentProvider(tenant, {
-    get: kvGet,
-    env: customization.env,
-  });
+  // A verified candidate content pin takes priority over the channel-resolved
+  // read — a pinned candidate/revision render must never fall through to the
+  // shared `{live,test}` content (see `pinnedRouteRender.ts`).
+  locals.content = candidatePin
+    ? createContentProvider(tenant, undefined, { get: kvGet, versionId: candidatePin.versionId })
+    : createContentProvider(tenant, {
+        get: kvGet,
+        env: customization.env,
+      });
   // Developer-draft content overlay — serves the AI-edited artifacts to the draft
   // owner only; every other viewer keeps the published/base chain above.
   if (draft) {
@@ -686,8 +723,11 @@ export const onRequest = defineMiddleware(async (context, next) => {
   locals.activeWidgetPlacements = [];
   // Prefix that path-routed pages live under ("" for host-routed). Pages stay
   // tenant-agnostic; the Layout uses this to keep root-absolute links inside
-  // the tenant prefix on the client.
-  locals.basePath = basePath;
+  // the tenant prefix on the client. A candidate content pin overrides this to
+  // the PINNING render's own prefix (`/preview/rev/<sha>` or
+  // `/preview/render/<tenant>/<changeId>`) so a pinned page's OWN generated
+  // links stay inside that candidate instead of escaping to the live host.
+  locals.basePath = candidatePin ? candidatePin.basePath : basePath;
   // Renderer-owned four-stage browser environment (ADR 0014 E1 / 0017), computed
   // ONCE here from authoritative request state and serialized before app code by
   // both document mounts (Layout.astro + rawHtmlResponse). The candidate render

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "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/src/customization-preview.ts

@@ -130,6 +130,106 @@ export async function verifyPreviewToken(
   return { ok: true, claims };
 }
 
+/**
+ * Query-string param a candidate/revision renderer's `context.rewrite()` uses to
+ * carry a signed content-pin token into the re-dispatched request — read by
+ * `src/middleware/index.ts` to bind that ONE request's content resolution to an
+ * exact `versionId` instead of the shared `{live,test}` channel. See
+ * {@link ContentPinClaims}.
+ */
+export const CANDIDATE_CONTENT_PIN_PARAM = "__tot_candidate_pin";
+
+/**
+ * Claims carried by a CONTENT-PIN token — distinct from {@link PreviewClaims}
+ * (which grants "test" channel access). A content pin grants read access to ONE
+ * exact immutable site version, bypassing channel resolution entirely. It backs
+ * the candidate/revision renderer's generic-route fallback: rendering any real
+ * Astro page (not just the raw `home.html`/`pages-html/*` documents) pinned to a
+ * candidate's `versionId` rather than the shared `live`/`test` channel.
+ */
+export interface ContentPinClaims {
+  tenantId: string;
+  versionId: string;
+  /** basePath the pinned render's own generated links must stay under. */
+  basePath: string;
+  /** Expiry, epoch seconds. */
+  exp: number;
+}
+
+/**
+ * Mint a content-pin token: `<payloadB64Url>.<sigB64Url>`. `ttlSeconds` is added
+ * to `nowSeconds` (caller supplies the clock so this stays pure/testable).
+ */
+export async function signContentPinToken(
+  secret: string,
+  claims: Omit<ContentPinClaims, "exp">,
+  ttlSeconds: number,
+  nowSeconds: number,
+): Promise<string> {
+  const full: ContentPinClaims = { ...claims, exp: nowSeconds + ttlSeconds };
+  const payload = bytesToB64Url(textEncoder.encode(JSON.stringify(full)));
+  const key = await hmacKey(secret);
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    textEncoder.encode(payload) as unknown as BufferSource,
+  );
+  return `${payload}.${bytesToB64Url(new Uint8Array(sig))}`;
+}
+
+export type VerifyContentPinResult =
+  | { ok: true; claims: ContentPinClaims }
+  | { ok: false; reason: "malformed" | "bad-signature" | "expired" };
+
+/**
+ * Verify a content-pin token against `secret` and the caller's clock. Signature
+ * is checked with `crypto.subtle.verify` (constant-time) before expiry.
+ */
+export async function verifyContentPinToken(
+  secret: string,
+  token: string,
+  nowSeconds: number,
+): Promise<VerifyContentPinResult> {
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: "malformed" };
+  const payload = token.slice(0, dot);
+  const sigPart = token.slice(dot + 1);
+
+  let sig: Uint8Array;
+  try {
+    sig = b64UrlToBytes(sigPart);
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const key = await hmacKey(secret);
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig as unknown as BufferSource,
+    textEncoder.encode(payload) as unknown as BufferSource,
+  );
+  if (!valid) return { ok: false, reason: "bad-signature" };
+
+  let claims: ContentPinClaims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(b64UrlToBytes(payload)));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (
+    !claims ||
+    typeof claims.tenantId !== "string" ||
+    typeof claims.versionId !== "string" ||
+    typeof claims.basePath !== "string" ||
+    typeof claims.exp !== "number"
+  ) {
+    return { ok: false, reason: "malformed" };
+  }
+  if (claims.exp <= nowSeconds) return { ok: false, reason: "expired" };
+  return { ok: true, claims };
+}
+
 export type CustomizationEnv = "live" | "test";
 
 export interface EnvResolutionInput {

package/packages/public-runtime/src/customization-runtime.ts

@@ -286,6 +286,46 @@ export async function readPublishedArtifact(
   return get(customizationArtifactKey(tenantId, versionId));
 }
 
+/**
+ * Read one artifact's text from a resolved immutable `versionId`, or null when
+ * that specific artifact is absent from the version. Pinned to the versionId,
+ * never a channel pointer — a candidate/revision preview must never resolve
+ * live/test content. `path` is the FULL artifact path (e.g. from
+ * `contentArtifactPath`), not tenant-content-relative.
+ */
+export async function readVersionArtifact(
+  get: KvGet,
+  tenantId: string,
+  versionId: string,
+  path: string,
+): Promise<string | null> {
+  const manifest = await readSiteVersion(get, tenantId, versionId);
+  const contentHash = manifest?.artifacts?.[path];
+  if (!contentHash) return null;
+  return get(customizationArtifactKey(tenantId, contentHash));
+}
+
+/**
+ * List artifact paths in an immutable site version, pinned directly to
+ * `versionId` (never a channel pointer) — the enumeration companion to
+ * {@link readVersionArtifact}, used by a pinned `ContentProvider` to answer
+ * `listArtifactPaths` the same way {@link listPublishedArtifactPaths} does for
+ * the channel-resolved read. `prefix` is content-relative (e.g. `"blog/"`).
+ */
+export async function listVersionArtifactPaths(
+  get: KvGet,
+  tenantId: string,
+  versionId: string,
+  prefix = "",
+): Promise<string[]> {
+  const manifest = await readSiteVersion(get, tenantId, versionId);
+  const root = contentArtifactPath(tenantId, "");
+  return Object.keys(manifest?.artifacts ?? {})
+    .flatMap((path) => (path.startsWith(root) ? [path.slice(root.length)] : []))
+    .filter((path) => path.startsWith(prefix))
+    .sort((a, b) => a.localeCompare(b));
+}
+
 /**
  * List artifact paths in the immutable site version selected for `(tenant, env)`.
  *