@tokenoftrust/storefront-runner 4.1.2 → 4.2.1

package/apps/storefront/env.d.ts

@@ -131,6 +131,12 @@ declare global {
        * Look" content for the resolved customizationEnv over Storyblok/local.
        */
       content: ContentProvider;
+      /**
+       * Immutable content version this response rendered, set only for a candidate
+       * pin. Absent on the shared preview channel and on publication. Preview cart
+       * signing copies it; it is not the asset cookie revision.
+       */
+      contentVersionId?: string;
       /** Inline CSS-variable theme block already serialized for <head>. */
       themeStyle: string;
       /** Absolute canonical base for this request. */

package/apps/storefront/src/components/catalog/storefront/ProductCard.astro

@@ -30,7 +30,7 @@ interface Props {
 }
 
 const { product, priority = false, rating, reviewCount } = Astro.props;
-const { tenant, basePath, features, commerce, apiBasePath, browserEnvironment } = Astro.locals;
+const { tenant, basePath, features, commerce, apiBasePath, browserEnvironment, contentVersionId } = Astro.locals;
 const showBadges = features.productBadges;
 
 // A compliance-verified item (age/lab/regulatory) earns a "Compliant" badge —
@@ -93,6 +93,7 @@ const cardCart = await buildCardCartForm({
   commerce,
   apiBasePath,
   environment: browserEnvironment.environment,
+  contentVersionId,
 });
 
 const quickview = {

package/apps/storefront/src/lib/checkout/commerce/cardCartForm.ts

@@ -37,6 +37,8 @@ export async function buildCardCartForm(input: {
   commerce: ResolvedManagedCheckout | null | undefined;
   apiBasePath: string;
   environment: string;
+  /** Candidate content pin this card rendered. Ignored on a live page. */
+  contentVersionId?: string;
 }): Promise<CardCartForm | null> {
   const variant = defaultCardVariant(input.product);
   if (!variant) return null;
@@ -58,6 +60,7 @@ export async function buildCardCartForm(input: {
           autopilotEnabled,
           tenantId: commerceTenantId(input.tenant),
           currency: input.tenant.currency,
+          contentVersionId: input.environment === "live" ? undefined : input.contentVersionId,
         });
     const provider = input.tenant.serving?.provider === "s3-overwrite" ? "s3-overwrite" : "worker-r2-pointer";
     return {

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

@@ -733,6 +733,10 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // (checkout handoff, compliance preflight, newsletter) must stay off `basePath`
   // once it's pin-overridden, or they 404 under preview.
   locals.apiBasePath = basePath;
+  // The catalog pin the page rendered. Absent on the shared preview channel and on
+  // publication. Cart signing copies this onto a preview cart; the asset cookie
+  // revision is a different value and is not a catalog pin.
+  if (candidatePin) locals.contentVersionId = candidatePin.versionId;
   // 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/apps/storefront/src/pages/api/commerce/final-cart-authorization.ts

@@ -2,7 +2,7 @@
 import type { APIContext } from "astro";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify, type JSONWebKeySet } from "jose";
 import {
-  commerceTenantId, totalsMatch, canonicalJson, shippingMinorFor,
+  commerceTenantId, totalsMatch, canonicalJson, shippingMinorFor, isContentVersionId, providerCartDigestMaterial,
   type CallerToken, type CatalogProduct, type CommerceEvidence, type CommerceEvidenceProvenance,
   type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
@@ -52,8 +52,9 @@ function readSnapshot(value: unknown): CommerceProviderCartSnapshot | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const v = value as Record<string, unknown>;
   const allowed = ["provider", "providerCartId", "providerCartDigest", "tenantId", "stage", "currency", "lines", "totals", "destinationDigest", "destination"];
-  const optional = ["expectedAuthorizationId", "verificationRef"];
+  const optional = ["expectedAuthorizationId", "verificationRef", "contentVersionId"];
   if (Object.keys(v).some(k => !allowed.includes(k) && !optional.includes(k)) || allowed.some(k => !(k in v))) return null;
+  if ("contentVersionId" in v && (typeof v.contentVersionId !== "string" || !isContentVersionId(v.contentVersionId))) return null;
   if ("expectedAuthorizationId" in v && (typeof v.expectedAuthorizationId !== "string" || !/^[a-z0-9][a-z0-9-]{0,80}$/.test(v.expectedAuthorizationId))) return null;
   if ("verificationRef" in v && (typeof v.verificationRef !== "string" || !VERIFICATION_REF.test(v.verificationRef))) return null;
   if (v.provider !== "foxycart" || typeof v.providerCartId !== "string" || !/^[a-zA-Z0-9._:-]{1,128}$/.test(v.providerCartId) ||
@@ -166,17 +167,23 @@ async function authorize(context: APIContext): Promise<Response> {
   const kv = await readKv("TENANT_CACHE");
   const kvGet = async (key: string): Promise<string | null> => kv ? kv.get(key) : null;
   const contentEnv = snapshot.stage === "publication" ? "live" : "test";
+  const contentVersionId = snapshot.stage === "preview" && snapshot.contentVersionId ? snapshot.contentVersionId : undefined;
   let tenant: TenantConfig;
-  try { tenant = await withDeclaredTenantConfig(registered, kvGet, { env: contentEnv }); } catch (err) {
+  try {
+    tenant = await withDeclaredTenantConfig(registered, kvGet, {
+      env: contentEnv,
+      ...(contentVersionId ? { pinnedVersionId: contentVersionId } : {}),
+    });
+  } catch (err) {
     if (err instanceof DeclaredTenantConfigUnreadError) return deny("config-unreadable", 503);
     throw err;
   }
-  const content = createContentProvider(tenant, { get: kvGet, env: contentEnv });
+  const content = contentVersionId
+    ? createContentProvider(tenant, undefined, { get: kvGet, versionId: contentVersionId })
+    : createContentProvider(tenant, { get: kvGet, env: contentEnv });
   const tot = await createToTClient(tenant, await readD1("CATALOG_DB"), content);
   const authorityContext = { ...context, locals: { ...context.locals, tenant, tot, content } } as APIContext;
-  const { tenantId, stage, currency, totals, destinationDigest } = snapshot;
-  const lines = [...snapshot.lines].sort((a, b) => a.sku.localeCompare(b.sku) || a.unitMinor - b.unitMinor || a.quantity - b.quantity);
-  if (snapshot.providerCartDigest !== await digest(canonicalJson({ tenantId, stage, currency, lines, totals, destinationDigest }))) return deny("provider-cart-digest");
+  if (snapshot.providerCartDigest !== await digest(canonicalJson(providerCartDigestMaterial(snapshot)))) return deny("provider-cart-digest");
   let listing: CatalogProduct[];
   try { listing = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
   if (!Array.isArray(listing)) return deny("catalog-unavailable", 503);

package/apps/storefront/src/pages/products/[handle].astro

@@ -267,6 +267,7 @@ if (commerce || sampleHandoff) {
                     autopilotEnabled,
                     tenantId: commerceTenantId(tenant),
                     currency: tenant.currency,
+                    contentVersionId: Astro.locals.browserEnvironment.environment === "live" ? undefined : Astro.locals.contentVersionId,
                   }),
                 ] as const;
               }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.1.2",
+  "version": "4.2.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/packages/public-runtime/src/checkout-orders.ts

@@ -347,6 +347,12 @@ export interface CommerceProviderCartSnapshot {
   totals: MinorTotals;
   destinationDigest: string;
   destination: { country: string; region: string };
+  /**
+   * Immutable content version the preview page rendered, from the signed `content_version`
+   * cart option. Present only for a candidate pin. Part of the provider-cart digest when
+   * present. A preview authority reads that pin's catalog; a publication cart still reads live.
+   */
+  contentVersionId?: string;
   /**
    * The shopper's verification correlation handle, from the signed `verification` cart option.
    * Present only when the cart carries one; outside the cart digest. A handle, not a claim: the
@@ -355,6 +361,46 @@ export interface CommerceProviderCartSnapshot {
   verificationRef?: string;
 }
 
+const CONTENT_VERSION_ID = /^[A-Za-z0-9._-]{1,128}$/;
+
+/** A rendered content pin. The same shape as a preview version id, and never a path. */
+export function isContentVersionId(value: string): boolean {
+  return CONTENT_VERSION_ID.test(value) && !value.includes("..");
+}
+
+/**
+ * The provider-cart digest body. `contentVersionId` is included only when the snapshot
+ * names one, so a cart that carries no pin keeps the digest it already had.
+ */
+export function providerCartDigestMaterial(snapshot: {
+  tenantId: string;
+  stage: string;
+  currency: string;
+  lines: readonly FinalCartLine[];
+  totals: MinorTotals;
+  destinationDigest: string;
+  contentVersionId?: string;
+}): {
+  tenantId: string;
+  stage: string;
+  currency: string;
+  lines: FinalCartLine[];
+  totals: MinorTotals;
+  destinationDigest: string;
+  contentVersionId?: string;
+} {
+  const lines = [...snapshot.lines].sort((a, b) => a.sku.localeCompare(b.sku) || a.unitMinor - b.unitMinor || a.quantity - b.quantity);
+  const material = {
+    tenantId: snapshot.tenantId,
+    stage: snapshot.stage,
+    currency: snapshot.currency,
+    lines,
+    totals: snapshot.totals,
+    destinationDigest: snapshot.destinationDigest,
+  };
+  return snapshot.contentVersionId === undefined ? material : { ...material, contentVersionId: snapshot.contentVersionId };
+}
+
 /** Safe source references explaining each server-owned authority decision. */
 export interface CommerceAuthoritySource {
   requirement: "required" | "not-required";

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

@@ -27,6 +27,7 @@ import type {
 import { resolveStoreCurrency } from "./declared-tenant-config.mjs";
 import { DEFAULT_ONE_TIME_PURCHASE_OPTION } from "./product.js";
 import type { ShippingPolicy, TenantConfig } from "./tenant.js";
+import { isContentVersionId } from "./checkout-orders.js";
 
 /** Stable commerce scope shared by signed carts, provider callers and operator authorization. */
 export function commerceTenantId(tenant: Pick<TenantConfig, "appDomain">): string {
@@ -165,6 +166,11 @@ export interface BuildVariantCartPayloadOptions {
    * `resolveStoreCurrency`, so absent or invalid is USD. Never taken from the submitted form.
    */
   currency?: string;
+  /**
+   * Content version the preview page rendered. Signed as `content_version` when present.
+   * A publication page and a shared-channel preview omit it. Never taken from the form.
+   */
+  contentVersionId?: string;
 }
 
 /** Declared public serving substrate (ADR 0013 `serving.provider`). */
@@ -205,9 +211,13 @@ export class CartSigningUnavailableError extends Error {
  * both bind the cart to it. `verification` carries the shopper's verification
  * ref when the gate produced one (`withVerificationRef`). `shipping_policy` carries the
  * store's declared shipping charge (`withShippingPolicy`). `return_url` carries the page the
- * shopper submitted from (`withReturnUrl`).
+ * shopper submitted from (`withReturnUrl`). `content_version` carries the candidate
+ * content pin the page rendered, and only then.
  */
-export const INTERNAL_CART_FIELDS = ["currency", "tenant", "verification", "shipping_policy", "return_url"] as const;
+export const INTERNAL_CART_FIELDS = ["currency", "tenant", "verification", "shipping_policy", "return_url", "content_version"] as const;
+
+/** Signed cart option naming the content version the preview page rendered. */
+export const CONTENT_VERSION_CART_FIELD = "content_version";
 
 /** The signed cart option the checkout store's Continue Shopping link reads (`withReturnUrl`). */
 export const RETURN_URL_CART_FIELD = "return_url";
@@ -499,7 +509,7 @@ export function cartFieldsForVariant(
   product: CatalogProduct,
   variant: CatalogVariant,
   purchaseOption?: ProductPurchaseOption,
-  opts?: { signedPrice?: number; tenantId?: string; currency?: string },
+  opts?: { signedPrice?: number; tenantId?: string; currency?: string; contentVersionId?: string },
 ): { code: string; fields: CartField[] } {
   const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
@@ -527,6 +537,12 @@ export function cartFieldsForVariant(
   if (opts?.tenantId) {
     fields.push({ name: "tenant", value: opts.tenantId });
   }
+  if (opts?.contentVersionId) {
+    if (!isContentVersionId(opts.contentVersionId)) {
+      throw new Error("cartFieldsForVariant: content version id is not a rendered pin");
+    }
+    fields.push({ name: CONTENT_VERSION_CART_FIELD, value: opts.contentVersionId });
+  }
   if (image) fields.push({ name: "image", value: image });
   // Variant options (Flavor, Nicotine strength, …) travel as product options so
   // the cart line reflects the exact variant the shopper picked.
@@ -728,7 +744,7 @@ export async function buildVariantCartPayload(
     product,
     variant,
     opts.purchaseOption,
-    { signedPrice: opts.signedPrice, tenantId: opts.tenantId, currency: opts.currency },
+    { signedPrice: opts.signedPrice, tenantId: opts.tenantId, currency: opts.currency, contentVersionId: opts.contentVersionId },
   );
   const signed = opts.mode === "signed";
   if (signed && !opts.secret) {

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

@@ -280,6 +280,8 @@ export interface MemberSignedCartPayloadOptions {
   tenantId?: string;
   /** The store's currency, signed into the cart (see {@link BuildVariantCartPayloadOptions.currency}). */
   currency?: string;
+  /** Candidate content pin the preview page rendered. Omitted for publication and the shared channel. */
+  contentVersionId?: string;
 }
 
 /**
@@ -315,6 +317,7 @@ export async function buildMemberSignedCartPayload(
     autopilotEnabled: opts.autopilotEnabled,
     tenantId: opts.tenantId,
     currency: opts.currency,
+    contentVersionId: opts.contentVersionId,
   });
 }