@tokenoftrust/storefront-runner 4.3.4 → 4.4.0

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

@@ -16,7 +16,8 @@ import PriceDisplay from "@/components/catalog/storefront/commerce/PriceDisplay.
 import RatingStars from "@/components/catalog/storefront/commerce/RatingStars.astro";
 import { withBase } from "@/lib/publication/shared/basePath";
 import { pageUrlForm } from "@/lib/content/seo/urlForm";
-import { buildCardCartForm } from "@/lib/checkout/commerce/cardCartForm";
+import { buildCardCartForm, cardNeedsOptionChoice } from "@/lib/checkout/commerce/cardCartForm";
+import { isLocalSampleCheckout } from "@/config/declaredTenantConfig";
 
 interface Props {
   product: CatalogProduct;
@@ -95,6 +96,10 @@ const cardCart = await buildCardCartForm({
   environment: browserEnvironment.environment,
   contentVersionId,
 });
+// A product with options is chosen on its product page, never from the card.
+const productHref = withBase(basePath, pageUrlForm(`/products/${product.handle}`, tenant.seo));
+const selectOptions = available && cardNeedsOptionChoice(product) &&
+  (!!commerce || isLocalSampleCheckout(tenant.tenant_id));
 
 const quickview = {
   ...snapshot,
@@ -201,7 +206,7 @@ const quickview = {
       {/* `py-3` on an inline box raises the tap target to the 44px minimum
           without changing the line box, so the card layout is untouched. */}
       <a
-        href={withBase(basePath, pageUrlForm(`/products/${product.handle}`, tenant.seo))}
+        href={productHref}
         data-astro-prefetch
         class="py-3 after:absolute after:inset-0 after:z-0 transition-colors motion-safe:group-hover:text-primary"
       >
@@ -234,6 +239,18 @@ const quickview = {
         </form>
       )
     }
+    {
+      selectOptions && (
+        <a
+          href={productHref}
+          data-select-options
+          data-product-handle={product.handle}
+          class="relative z-10 mt-3 block w-full rounded-full bg-[var(--color-primary)] px-4 py-3 text-center font-display text-sm font-medium text-[var(--color-primary-contrast)]"
+        >
+          Select options
+        </a>
+      )
+    }
 
     {rating != null && <RatingStars rating={rating} count={reviewCount} class="mt-1.5" />}
 

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

@@ -1,7 +1,9 @@
 /**
- * Add-to-cart form for a catalog card. One default variant — the first
- * available one — signed the same way the product page signs its handoff.
- * No form when the product cannot be bought or the cart cannot be signed.
+ * Add-to-cart form for a catalog card. Only a product with a single variant
+ * buys from its card, signed the same way the product page signs its handoff;
+ * a product with options links to its product page ("Select options") so the
+ * card never adds a variant the shopper did not choose. No form when the
+ * product cannot be bought or the cart cannot be signed.
  */
 import type { CatalogProduct, CatalogVariant, ResolvedManagedCheckout, TenantConfig } from "@tot/public-runtime";
 import {
@@ -31,6 +33,11 @@ export function defaultCardVariant(product: CatalogProduct): CatalogVariant | nu
   return product.variants.find((variant) => variant.inventory.available) ?? null;
 }
 
+/** A product with more than one variant needs the shopper's choice on its product page. */
+export function cardNeedsOptionChoice(product: CatalogProduct): boolean {
+  return product.variants.length > 1;
+}
+
 export async function buildCardCartForm(input: {
   product: CatalogProduct;
   tenant: TenantConfig;
@@ -40,6 +47,7 @@ export async function buildCardCartForm(input: {
   /** Candidate content pin this card rendered. Ignored on a live page. */
   contentVersionId?: string;
 }): Promise<CardCartForm | null> {
+  if (cardNeedsOptionChoice(input.product)) return null;
   const variant = defaultCardVariant(input.product);
   if (!variant) return null;
   const sampleHandoff = isLocalSampleCheckout(input.tenant.tenant_id);

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

@@ -36,6 +36,16 @@ export function cartSessionCookiePath(basePath: string): string {
   return `${withLead.replace(/\/+$/, "")}/`;
 }
 
+/**
+ * True when a browser at `pathname` sends the cookie stored at `cookiePath`. A
+ * candidate preview page (`/preview/render/<tenant>/<change>/…`) is outside the
+ * tenant prefix, so the browser holds this store's session but does not send it there.
+ */
+export function cartSessionCookieVisible(pathname: string, cookiePath: string): boolean {
+  if (cookiePath === "/") return true;
+  return pathname.startsWith(cookiePath) || `${pathname}/` === cookiePath;
+}
+
 /** Cart URL that selects one Foxy session. Other params are kept. */
 export function withCartSession(cartUrl: string, id: string): string {
   const url = new URL(cartUrl);
@@ -47,12 +57,21 @@ function saneSessionId(value: unknown): value is string {
   return typeof value === "string" && CART_SESSION_ID.test(value);
 }
 
+/**
+ * An option name as one key. FC.json spells names for display (measured 2026-10-23:
+ * `return_url` reads "return url"), and a signed name carries `||<hash>`, so names
+ * compare trimmed, lowercased, and with spaces and underscores as one `_`.
+ */
+function optionKey(raw: string): string {
+  return (raw.split("||")[0] ?? "").trim().toLowerCase().replace(/[\s_]+/g, "_");
+}
+
 function optionBaseName(option: unknown): string | null {
   if (!option || typeof option !== "object") return null;
   const raw = (option as { name?: unknown; class?: unknown }).name
     ?? (option as { class?: unknown }).class;
   if (typeof raw !== "string" || raw.length === 0) return null;
-  return raw.split("||")[0] ?? "";
+  return optionKey(raw);
 }
 
 function optionValue(option: unknown): string | null {
@@ -72,7 +91,7 @@ function itemTenant(item: unknown): string | null {
   }
   if (options && typeof options === "object") {
     for (const [key, value] of Object.entries(options as Record<string, unknown>)) {
-      if (key.split("||")[0] === "tenant" && typeof value === "string") return value;
+      if (optionKey(key) === "tenant" && typeof value === "string") return value;
     }
   }
   return null;

package/apps/storefront/src/pages/api/commerce/final-cart-authorization.ts

@@ -2,8 +2,8 @@
 import type { APIContext } from "astro";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify, type JSONWebKeySet } from "jose";
 import {
-  commerceTenantId, totalsMatch, shippingMinorFor, isContentVersionId, catalogPinDigestFinding,
-  type CallerToken, type CatalogProduct, type CommerceEvidence, type CommerceEvidenceProvenance,
+  commerceTenantId, totalsMatch, shippingMinorFor, isContentVersionId, catalogPinDigestFinding, cartLineCode,
+  type CallerToken, type CatalogProduct, type CatalogVariant, type CommerceEvidence, type CommerceEvidenceProvenance,
   type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
 import { fromD1 } from "@/lib/catalog/d1/catalog.js";
@@ -30,6 +30,17 @@ function json(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" } });
 }
 function deny(finding: string, status = 409, owner?: string): Response { return json({ ok: false, finding, ...(owner ? { owner } : {}) }, status); }
+/**
+ * Which check refused, and on which cart line (its index in the presented snapshot). Logged on
+ * the decision line only: closed check names and an index, never a SKU, price or cart value.
+ */
+interface RefusalDetail { check: string; line?: number }
+const refusalDetails = new WeakMap<Response, RefusalDetail>();
+function refuse(finding: string, detail: RefusalDetail, status = 409): Response {
+  const response = deny(finding, status);
+  refusalDetails.set(response, detail);
+  return response;
+}
 function list(value: string | undefined): string[] | null {
   if (!value) return null;
   try {
@@ -85,7 +96,11 @@ async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot,
     const { decision } = await evaluatePreflight({ locals: { tenant: context.locals.tenant, tot: {
       getProductByHandle: async (handle: string) => selected.get(handle) ?? null,
     } } } as APIContext, {
-      lines: snapshot.lines.map(line => ({ handle: products.find(p => p.variants.some(v => v.sku === line.sku))!.handle, sku: line.sku, quantity: line.quantity })),
+      lines: snapshot.lines.map(line => {
+        const product = products.find(p => p.variants.some(v => cartLineCode(v) === line.sku))!;
+        const variant = product.variants.find(v => cartLineCode(v) === line.sku)!;
+        return { handle: product.handle, variantId: variant.id, sku: line.sku, quantity: line.quantity };
+      }),
       destination: snapshot.destination,
       ...(policy.verification === "required" && snapshot.verificationRef ? { verificationRef: snapshot.verificationRef } : {}),
     }, { verification: policy.verification, rules: policy.rules });
@@ -132,8 +147,11 @@ export async function POST(context: APIContext): Promise<Response> {
   if (response.status !== 200 || threw) {
     try { finding = String((await response.clone().json() as { finding?: unknown }).finding ?? "unreadable").slice(0, 80); } catch { finding = "unreadable"; }
   }
+  const detail = refusalDetails.get(response);
   try {
-    console.info("commerce-final-cart-decision", JSON.stringify({ correlationId, ok: response.status === 200, finding, status: response.status, threw, ms: Date.now() - started }));
+    console.info("commerce-final-cart-decision", JSON.stringify({ correlationId, ok: response.status === 200, finding,
+      ...(detail ? { check: detail.check, ...(detail.line === undefined ? {} : { line: detail.line }) } : {}),
+      status: response.status, threw, ms: Date.now() - started }));
   } catch { /* Diagnostic delivery cannot alter the decision. */ }
   return response;
 }
@@ -189,31 +207,39 @@ async function authorize(context: APIContext): Promise<Response> {
   try { listing = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
   if (!Array.isArray(listing)) return deny("catalog-unavailable", 503);
   const selected = new Map<string, CatalogProduct>();
-  if (snapshot.currency !== resolveStoreCurrency(tenant.currency)) return deny("catalog-cart-mismatch");
-  for (const line of snapshot.lines) {
+  const mismatch = (check: string, line?: number) => refuse("catalog-cart-mismatch", line === undefined ? { check } : { check, line });
+  if (snapshot.currency !== resolveStoreCurrency(tenant.currency)) return mismatch("store-currency");
+  // A line's `sku` is the product code the page signed (`cartLineCode`): the SKU, or the
+  // variant id for a variant with none.
+  const coded = (line: { sku: string }) => (variant: CatalogVariant | null | undefined) => !!variant && cartLineCode(variant) === line.sku;
+  for (const [index, line] of snapshot.lines.entries()) {
     const matches = listing.flatMap(product => product && product.status === "active" && (!product.visibility || product.visibility === "public") && product.tenant_id === tenant.tot_data_scope && Array.isArray(product.variants)
-      ? product.variants.filter(v => v && v.sku === line.sku).map(variant => ({ product, variant })) : []);
-    if (matches.length !== 1) return deny("catalog-cart-mismatch");
+      ? product.variants.filter(coded(line)).map(variant => ({ product, variant })) : []);
+    if (matches.length !== 1) return mismatch(matches.length === 0 ? "sku-not-in-catalog" : "sku-ambiguous", index);
     const match = matches[0]!;
     const handle = match.product.handle;
-    if (typeof handle !== "string" || !handle) return deny("catalog-cart-mismatch");
+    if (typeof handle !== "string" || !handle) return mismatch("product-handle", index);
     if (!selected.has(handle)) {
       let detail: CatalogProduct | null;
       try { detail = await tot.getProductByHandle(handle); } catch { return deny("catalog-unavailable", 503); }
-      if (!fullCartProduct(detail, handle, tenant.tot_data_scope)) return deny("catalog-cart-mismatch");
+      if (!fullCartProduct(detail, handle, tenant.tot_data_scope)) return mismatch("product-detail", index);
       selected.set(handle, detail);
     }
     const detail = selected.get(handle)!;
-    if (detail.id !== match.product.id) return deny("catalog-cart-mismatch");
-    const variants = detail.variants.filter(variant => variant.sku === line.sku);
-    if (variants.length !== 1 || variants[0]!.id !== match.variant.id) return deny("catalog-cart-mismatch");
+    if (detail.id !== match.product.id) return mismatch("product-id", index);
+    const variants = detail.variants.filter(coded(line));
+    if (variants.length !== 1 || variants[0]!.id !== match.variant.id) return mismatch("variant-detail", index);
     const variant = variants[0]!;
     const digits = new Intl.NumberFormat("en", { style: "currency", currency: snapshot.currency }).resolvedOptions().maximumFractionDigits ?? 2;
     const scaled = variant.price * 10 ** digits;
-    if (!variant.inventory.available || variant.currency !== snapshot.currency || Math.abs(scaled - Math.round(scaled)) > 0.000001 || Math.round(scaled) !== line.unitMinor) return deny("catalog-cart-mismatch");
+    if (!variant.inventory.available) return mismatch("unavailable", index);
+    if (variant.currency !== snapshot.currency) return mismatch("variant-currency", index);
+    if (Math.abs(scaled - Math.round(scaled)) > 0.000001) return mismatch("price-precision", index);
+    if (Math.round(scaled) !== line.unitMinor) return mismatch("price", index);
   }
   const products = [...selected.values()];
-  if (snapshot.lines.some(line => products.flatMap(product => product.variants.filter(variant => variant.sku === line.sku)).length !== 1)) return deny("catalog-cart-mismatch");
+  const ambiguous = snapshot.lines.findIndex(line => products.flatMap(product => product.variants.filter(coded(line))).length !== 1);
+  if (ambiguous !== -1) return mismatch("sku-ambiguous", ambiguous);
   // Shipping is re-derived from the store's own declaration, never from the cart: a cart that
   // dropped, replayed or altered its signed `shipping_policy` option was charged another amount.
   if (tenant.shipping) {

package/apps/storefront/src/pages/cart.ts

@@ -1,28 +1,50 @@
 import type { APIRoute } from "astro";
 import { commerceTenantId } from "@tot/public-runtime";
-import { bindCartSession, CART_UNAVAILABLE_MESSAGE, withCartSession } from "@/lib/checkout/commerce/cartSession.js";
+import {
+  bindCartSession,
+  CART_UNAVAILABLE_MESSAGE,
+  cartSessionCookiePath,
+  cartSessionCookieVisible,
+  withCartSession,
+} from "@/lib/checkout/commerce/cartSession.js";
 import { managedCartHref } from "@/lib/content/chrome/managedCart.js";
 
 export const prerender = false;
 
+const NO_STORE = "private, no-store";
+
 /**
- * Backward-compatible entry for bookmarked or tenant-authored `/cart` links.
- * Chrome now links straight to managed checkout, but this route prevents stale
- * links from falling through the content catch-all to a misleading storefront
- * 404. Tenant resolution and preview authorization have already run in
- * middleware before this redirect is selected. The redirect carries this
- * tenant's Foxy session and never the shared cart.
+ * Entry for bookmarked or tenant-authored `/cart` links. Chrome links straight to
+ * managed checkout, but this route keeps those links from falling through the
+ * content catch-all to a misleading storefront 404. Tenant resolution and preview
+ * authorization have already run in middleware before this redirect is selected.
+ * The redirect carries this tenant's Foxy session and never the shared cart.
+ *
+ * The session cookie lives on the tenant prefix. A link on a pinned preview page
+ * arrives from outside it, without the cookie, so it is sent to the tenant prefix
+ * first: binding there reads the shopper's own session instead of minting an empty
+ * one over it.
  */
 export const GET: APIRoute = async (context) => {
   const location = managedCartHref(context.locals.commerce);
   if (!location || !context.locals.commerce) return new Response(null, { status: 404 });
+  // `basePath` is the prefix the browser is on: a pinned render overrides it to the
+  // pin's own prefix, while `apiBasePath` stays the tenant prefix the cookie lives on.
+  const cookiePath = cartSessionCookiePath(context.locals.apiBasePath ?? context.locals.basePath ?? "");
+  const pagePrefix = cartSessionCookiePath(context.locals.basePath ?? context.locals.apiBasePath ?? "");
+  if (!cartSessionCookieVisible(pagePrefix, cookiePath)) {
+    return new Response(null, {
+      status: 302,
+      headers: { location: `${cookiePath}cart`, "cache-control": NO_STORE },
+    });
+  }
   const tenantId = context.locals.tenant ? commerceTenantId(context.locals.tenant) : "";
   const sessionId = tenantId ? await bindCartSession(context, context.locals.commerce, tenantId) : null;
   if (!sessionId) {
     return new Response(CART_UNAVAILABLE_MESSAGE, {
       status: 503,
       headers: {
-        "cache-control": "private, no-store",
+        "cache-control": NO_STORE,
         "content-type": "text/plain; charset=utf-8",
       },
     });
@@ -31,7 +53,7 @@ export const GET: APIRoute = async (context) => {
     status: 302,
     headers: {
       location: withCartSession(location, sessionId),
-      "cache-control": "private, no-store",
+      "cache-control": NO_STORE,
     },
   });
 };

package/package.json

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

@@ -500,6 +500,14 @@ export function resolveManagedCheckout(
   };
 }
 
+/**
+ * The checkout product code for a variant: its SKU, or its id when it has none. Every field
+ * is hashed against it, and the final-cart authority finds a cart line's variant by it.
+ */
+export function cartLineCode(variant: Pick<CatalogVariant, "id" | "sku">): string {
+  return variant.sku && variant.sku.length ? variant.sku : variant.id;
+}
+
 /**
  * The raw (unsigned) cart fields for a variant: name, price, code, image, the
  * variant's options, and an editable quantity. `code` is the checkout product code
@@ -511,7 +519,7 @@ export function cartFieldsForVariant(
   purchaseOption?: ProductPurchaseOption,
   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 code = cartLineCode(variant);
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
     product.images[0]?.url;
   // The signed price is either the caller's member-adjusted EFFECTIVE price