@tokenoftrust/storefront-runner 2.0.13 → 2.0.15

package/apps/storefront/public/shared/commerce-chrome.css

@@ -339,6 +339,11 @@ a.article-card__tag:hover { text-decoration: underline; }
 .footer-warning p { color: color-mix(in srgb, var(--color-primary-contrast) 78%, transparent); font-size: .82rem; }
 .footer-bottom { margin-top: 28px; padding-top: 18px; border-top: 1px solid color-mix(in srgb, var(--color-primary-contrast) 16%, transparent); display: flex; flex-wrap: wrap; gap: 10px 24px; justify-content: space-between; align-items: center; }
 .footer-bottom p, .footer-bottom a { color: color-mix(in srgb, var(--color-primary-contrast) 60%, transparent); font-size: .82rem; }
+/* The Legal link row (a "Legal"-titled footer column, moved here — see
+   lib/chrome/footerLegal.ts). Wraps under the copyright at narrow widths
+   rather than overflowing the bar. */
+.footer-bottom nav ul { display: flex; flex-wrap: wrap; gap: 6px 20px; list-style: none; margin: 0; padding: 0; }
+.footer-bottom nav a:hover { color: var(--color-primary-contrast); text-decoration: underline; }
 
 /* --- Reveal-on-scroll (raw-chrome markup uses .reveal/.in) ---------------- */
 .reveal { opacity: 0; transform: translateY(18px); transition: opacity .5s ease, transform .5s ease; }

package/apps/storefront/src/components/chrome/SiteFooter.astro

@@ -27,7 +27,10 @@ interface Props {
   compliance?: string;
   /** Legal bottom-bar line (e.g. a composed "© 2026 Acme · some legal note" string). */
   legal?: string;
-  /** Bottom-bar policy links (e.g. Privacy Policy, Terms), shown alongside `legal`. */
+  /** Bottom-bar policy links (e.g. Privacy Policy, Terms), shown alongside `legal`.
+   * The links of a `Legal`-titled footer column, which the caller MOVES out of
+   * `columns` (lib/chrome/footerLegal.ts) — passing them in both places would
+   * render each one twice. */
   bottomLinks?: ChromeLink[];
   class?: string;
 }

package/apps/storefront/src/layouts/Layout.astro

@@ -25,6 +25,7 @@ import { organizationLd, websiteLd } from "@/lib/jsonld";
 import { nonceInlineTags, CHROME_BODY_MARKER } from "@/lib/rawMarketingHtml";
 import { reportTrackingChainHealth } from "@/lib/tracking/interactionHealth";
 import { resolveHeaderVariant, resolveFooterVariant } from "@/lib/chrome/variant";
+import { splitFooterLegal } from "@/lib/chrome/footerLegal";
 import type { HeaderVariant, FooterVariant } from "@/lib/chrome/model";
 import { renderIntegrationPhases, INTERACTION_TRACKING_BOOT_JS } from "@tot/public-runtime";
 import { readViewerSession } from "@/lib/auth/route";
@@ -208,11 +209,12 @@ const headerLogo = brandLogoValid ?? themeHeaderLogo;
 const headerWordmark = brand?.label ?? tenant.displayName;
 const headerBrandHref = brand?.href;
 
-// Footer bottom bar: a "Legal"-titled column's links win; otherwise every
-// column's links flatten into the policy-link row (mirrors the retired
-// nav/Footer.astro exactly).
-const legalCol = chrome.footer.columns.find((c) => /legal/i.test(c.title));
-const bottomLinks = legalCol ? legalCol.links : chrome.footer.columns.flatMap((c) => c.links);
+// Footer bottom bar: a "Legal"-titled column MOVES out of the grid and its
+// links render beside the copyright — one shared split with the raw renderer
+// (lib/chrome/footerLegal.ts), so neither surface can duplicate them.
+const { gridColumns: footerColumns, legalLinks: bottomLinks } = splitFooterLegal(
+  chrome.footer.columns,
+);
 const legalBase = chrome.footer.bottom?.copyright ?? `© ${new Date().getFullYear()} ${tenant.displayName}`;
 const legalLine = `${legalBase}${chrome.footer.bottom?.note ? ` · ${chrome.footer.bottom.note}` : ""}`;
 
@@ -386,7 +388,7 @@ const footerWidgets = await renderWidgetSlot(
             contact: chrome.footer.brand?.text ? [chrome.footer.brand.text] : undefined,
           }}
           variant={resolvedFooterVariant}
-          columns={chrome.footer.columns}
+          columns={footerColumns}
           newsletter={features.newsletter ? { title: "Newsletter", placeholder: "you@example.com" } : undefined}
           social={chrome.footer.social}
           legal={legalLine}

package/apps/storefront/src/lib/chrome/footerLegal.ts

@@ -0,0 +1,52 @@
+/**
+ * The footer's Legal split — ONE source of truth for both renderers (the
+ * raw-string footer in lib/rawChrome.ts and the component footer in
+ * components/chrome/SiteFooter.astro), so a tenant's `Legal` column can never
+ * land in the grid on one surface and in the bottom bar on the other.
+ *
+ * Contract, title-based (no extra schema field): a footer column titled
+ * `Legal` — case-insensitive, surrounding whitespace ignored — is not a grid
+ * column. Its links render in the bottom bar beside the copyright, inside a
+ * single `<nav aria-label="Legal">`.
+ *
+ * The column is MOVED, never copied: it leaves `.footer-grid` entirely, so
+ * each legal link appears exactly once in the DOM. Each link keeps its own
+ * governed identity (`data-tot-el`) and action (`data-tot-action`); only the
+ * placement changes, to `footer-bottom`, which is what that placement means.
+ *
+ * A tenant with no `Legal` column gets a text-only bottom bar — the other
+ * columns stay in the grid rather than being flattened into a second copy of
+ * themselves under the copyright.
+ */
+import type { ChromeLink, FooterColumn } from "./model.js";
+
+/** The bottom-bar nav's accessible name. Exactly one is emitted per footer. */
+export const LEGAL_NAV_LABEL = "Legal";
+
+/** The title-based contract: `Legal`, case- and surrounding-whitespace-insensitive. */
+export function isLegalColumnTitle(title: string): boolean {
+  return title.trim().toLowerCase() === LEGAL_NAV_LABEL.toLowerCase();
+}
+
+export interface FooterLegalSplit {
+  /** The columns that stay in `.footer-grid`, in authored order. */
+  gridColumns: FooterColumn[];
+  /** The extracted bottom-bar links, in authored order. Empty when no Legal column. */
+  legalLinks: ChromeLink[];
+}
+
+/**
+ * Partition footer columns into what the grid renders and what the bottom bar
+ * renders. Every `Legal`-titled column is extracted (a config with two is a
+ * tenant mistake, not a reason to emit a second nav) and its links concatenated
+ * in authored order.
+ */
+export function splitFooterLegal(columns: readonly FooterColumn[]): FooterLegalSplit {
+  const gridColumns: FooterColumn[] = [];
+  const legalLinks: ChromeLink[] = [];
+  for (const column of columns) {
+    if (isLegalColumnTitle(column.title)) legalLinks.push(...column.links);
+    else gridColumns.push(column);
+  }
+  return { gridColumns, legalLinks };
+}

package/apps/storefront/src/lib/chrome/trackingPlacements.ts

@@ -24,9 +24,10 @@ export const CHROME_PLACEMENT = {
   /** Footer link columns. */
   footer: "footer",
   /**
-   * Footer bottom legal/policy link row — component surface only. The raw
-   * renderer's `ChromeFooter.bottom` carries text only (no links); its footer
-   * columns cover the same links under `footer` above.
+   * Footer bottom legal/policy link row, on either surface — the links of a
+   * `Legal`-titled footer column, which both renderers move out of the grid and
+   * into the bottom bar (lib/chrome/footerLegal.ts). `ChromeFooter.bottom`
+   * itself carries text only.
    */
   footerBottom: "footer-bottom",
   /** The mobile nav drawer (MobileNav island) and its no-JS accordion fallback. */

package/apps/storefront/src/lib/rawChrome.ts

@@ -28,6 +28,7 @@ import { CHROME_BODY_MARKER, CHROME_HEAD_MARKER } from "./rawMarketingHtml.js";
 import { isCurrentNavHref } from "./chrome/navCurrent.js";
 import { ctaIdentityAttr } from "./chrome/ctaIdentity.js";
 import { CHROME_PLACEMENT } from "./chrome/trackingPlacements.js";
+import { LEGAL_NAV_LABEL, splitFooterLegal } from "./chrome/footerLegal.js";
 import { trackingAttributesHtml } from "@tot/public-runtime";
 import type {
   ChromeAgeGate,
@@ -391,7 +392,11 @@ function renderFooter(footer: ChromeFooter): string {
           return `      <div class="footer-brand">${logo}${text}${news}</div>\n`;
         })()
       : "";
-  const columns = footer.columns
+  // A `Legal`-titled column moves to the bottom bar (lib/chrome/footerLegal.ts)
+  // — scope indices count RENDERED grid columns, so they describe where a link
+  // actually is rather than where it sat in the authored array.
+  const { gridColumns, legalLinks } = splitFooterLegal(footer.columns);
+  const columns = gridColumns
     .map((c, colIndex) => {
       const links = c.links
         .map((l, i) => {
@@ -425,11 +430,28 @@ function renderFooter(footer: ChromeFooter): string {
   const warning = footer.warning
     ? `\n    <div class="footer-warning"><p><strong>WARNING:</strong> ${esc(footer.warning)}</p></div>`
     : "";
-  const bottom = footer.bottom
-    ? `\n    <div class="footer-bottom">${footer.bottom.copyright ? `<p>${esc(footer.bottom.copyright)}</p>` : ""}${
+  const legalNav = legalLinks.length
+    ? `<nav aria-label="${LEGAL_NAV_LABEL}"><ul>${legalLinks
+        .map((l, i) => {
+          const stamp = trackingAttributesHtml({
+            el: l.id,
+            action: l.action,
+            tracking: l.tracking,
+            placement: CHROME_PLACEMENT.footerBottom,
+            scope: "footer-bottom",
+            index: i,
+          });
+          return `<li><a href="${esc(l.href)}"${relFor(l)}${stamp}>${esc(l.label)}</a></li>`;
+        })
+        .join("")}</ul></nav>`
+    : "";
+  const bottomText = footer.bottom
+    ? `${footer.bottom.copyright ? `<p>${esc(footer.bottom.copyright)}</p>` : ""}${
         footer.bottom.note ? `<p>${esc(footer.bottom.note)}</p>` : ""
-      }</div>`
+      }`
     : "";
+  const bottom =
+    bottomText || legalNav ? `\n    <div class="footer-bottom">${bottomText}${legalNav}</div>` : "";
   return (
     `<footer class="site-footer">\n` +
     `  <div class="container">\n` +

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.15",
   "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)`.
  *