@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

package/apps/storefront/src/lib/catalog/shared/catalogIndex.ts

@@ -0,0 +1,109 @@
+/**
+ * The static catalog index (`/catalog-index.json`): every public product in the
+ * fields listing, faceting, search and a compact card read, plus each public
+ * collection's declared membership. It is emitted once per publish, so a static
+ * host answers sort, facet and search queries in the browser with the same
+ * engine the server uses (lib/catalog/tot/query.ts, lib/catalog/search/index.ts)
+ * — no origin compute on the public path (ADR 0013).
+ */
+import type { CatalogCollection, CatalogProduct } from "@tot/public-runtime";
+
+export const CATALOG_INDEX_PATH = "/catalog-index.json";
+export const CATALOG_INDEX_VERSION = 1;
+
+/** Description characters kept for search: enough to rank on, small enough to ship. */
+const DESCRIPTION_CHARS = 280;
+
+export interface CatalogIndexVariant {
+  price: number;
+  compare_at_price?: number;
+  option_values: Record<string, string>;
+  inventory: { available: boolean };
+}
+
+export interface CatalogIndexProduct {
+  id: string;
+  handle: string;
+  title: string;
+  vendor?: string;
+  product_type?: string;
+  description_text: string;
+  tags: string[];
+  status: CatalogProduct["status"];
+  options: { name: string }[];
+  variants: CatalogIndexVariant[];
+  price_range: CatalogProduct["price_range"];
+  collections: string[];
+  created_at: string;
+  image?: { url: string; alt?: string; rehosted?: boolean; id?: string };
+}
+
+export interface CatalogIndexCollection {
+  handle: string;
+  product_handles: string[];
+}
+
+export interface CatalogIndex {
+  version: number;
+  products: CatalogIndexProduct[];
+  collections: CatalogIndexCollection[];
+}
+
+export function toCatalogIndexProduct(p: CatalogProduct): CatalogIndexProduct {
+  const doc: CatalogIndexProduct = {
+    id: p.id,
+    handle: p.handle,
+    title: p.title,
+    description_text: (p.description_text ?? "").slice(0, DESCRIPTION_CHARS),
+    tags: p.tags,
+    status: p.status,
+    options: p.options.map((o) => ({ name: o.name })),
+    variants: p.variants.map((v) => ({
+      price: v.price,
+      ...(v.compare_at_price != null ? { compare_at_price: v.compare_at_price } : {}),
+      option_values: v.option_values,
+      inventory: { available: v.inventory.available },
+    })),
+    price_range: p.price_range,
+    collections: p.collections,
+    created_at: p.created_at,
+  };
+  if (p.vendor) doc.vendor = p.vendor;
+  if (p.product_type) doc.product_type = p.product_type;
+  const img = p.images[0];
+  if (img?.url) {
+    doc.image = { url: img.url };
+    if (img.alt) doc.image.alt = img.alt;
+    if (img.rehosted) doc.image.rehosted = img.rehosted;
+    if (img.id) doc.image.id = img.id;
+  }
+  return doc;
+}
+
+/** The index for a catalog's active products (in catalog order) and its public collections. */
+export function buildCatalogIndex(
+  activeProducts: CatalogProduct[],
+  collections: CatalogCollection[],
+): CatalogIndex {
+  return {
+    version: CATALOG_INDEX_VERSION,
+    products: activeProducts.map(toCatalogIndexProduct),
+    collections: collections.map((c) => ({ handle: c.handle, product_handles: c.product_handles })),
+  };
+}
+
+/**
+ * An index product in the shape the shared query/search engines read. They touch
+ * only the fields the index carries; everything else is absent by construction.
+ */
+export function asCatalogProduct(doc: CatalogIndexProduct): CatalogProduct {
+  return {
+    ...doc,
+    images: doc.image ? [doc.image] : [],
+  } as unknown as CatalogProduct;
+}
+
+/** An index collection in the shape `collectionProducts` reads. */
+export function asCatalogCollection(doc: CatalogIndexCollection): CatalogCollection {
+  return doc as unknown as CatalogCollection;
+}

package/apps/storefront/src/lib/catalog/shared/catalogQueryView.ts

@@ -0,0 +1,60 @@
+/**
+ * Listing and search over the static catalog index (`/catalog-index.json`), with
+ * the same engines the server uses, for a page whose query no renderer saw (a
+ * static host serves one document per path). Pure apart from the one fetch —
+ * the island owns the DOM, lib/publication/shared/staticQuery.ts owns the URL.
+ */
+import type { ListProductsQuery, ListProductsResponse } from "@tot/public-runtime";
+import { applyQuery, buildFacets, collectionProducts, paginate } from "../tot/query.js";
+import { buildSearchIndex } from "../search/index.js";
+import {
+  asCatalogCollection,
+  asCatalogProduct,
+  CATALOG_INDEX_PATH,
+  type CatalogIndex,
+  type CatalogIndexProduct,
+} from "./catalogIndex.js";
+
+export { bucketByKey } from "./priceBuckets.js";
+
+/** Results per search page — matches the server render of /search. */
+export const SEARCH_RESULT_LIMIT = 24;
+
+/** A collection's listing over the index — the FixtureToTClient.listProducts semantics. */
+export function collectionViewFromIndex(
+  index: CatalogIndex,
+  handle: string,
+  query: ListProductsQuery,
+): ListProductsResponse {
+  const active = index.products.map(asCatalogProduct);
+  const collection = index.collections.find((c) => c.handle === handle);
+  const pool = collection ? collectionProducts(active, asCatalogCollection(collection)) : [];
+  const facets = buildFacets(pool, query);
+  const { items, page, pageSize, total } = paginate(applyQuery(pool, query, true), query);
+  return { products: items, page, pageSize, total, facets };
+}
+
+/** Search results over the index — the FixtureToTClient.search semantics. */
+export function searchFromIndex(index: CatalogIndex, q: string, limit = SEARCH_RESULT_LIMIT): CatalogIndexProduct[] {
+  const byHandle = new Map(index.products.map((p) => [p.handle, p]));
+  return buildSearchIndex(index.products.map(asCatalogProduct))
+    .search(q, limit)
+    .map((hit) => byHandle.get(hit.product.handle)!)
+    .filter(Boolean);
+}
+
+let indexRequest: Promise<CatalogIndex> | null = null;
+
+/** Fetch the tenant's catalog index once per page (`base` is the tenant's client base path). */
+export function loadCatalogIndex(base: string): Promise<CatalogIndex> {
+  indexRequest ??= fetch(`${base.replace(/\/+$/, "")}${CATALOG_INDEX_PATH}`, {
+    headers: { Accept: "application/json" },
+  }).then((res) => {
+    if (!res.ok) throw new Error(`catalog index: HTTP ${res.status}`);
+    return res.json() as Promise<CatalogIndex>;
+  });
+  indexRequest.catch(() => {
+    indexRequest = null;
+  });
+  return indexRequest;
+}

package/apps/storefront/src/lib/catalog/shared/collectionPaging.ts

@@ -0,0 +1,78 @@
+/**
+ * Collection (PLP) paging — shared by the server render, the client query view,
+ * and the sitemap so the three can't drift.
+ *
+ * A public page is served as one prerendered document per PATH on both CDNs
+ * (ADR 0013), so the query string never reaches a renderer there. Two strategies
+ * follow from "what is N?":
+ *   - paging is N-bounded and indexable → a path variant per page,
+ *     `/collections/<h>/page/<n>/` (page 1 lives at the bare collection path);
+ *   - sort / facets / price / availability / inline search are unbounded and
+ *     noindex → the URL keeps its query and the client applies it over the static
+ *     catalog index (`/catalog-index.json`) whenever the render did not
+ *     (lib/publication/shared/staticQuery.ts).
+ */
+import type { CatalogCollection, ListProductsQuery, ListProductsResponse } from "@tot/public-runtime";
+import type { ToTClient } from "../tot/totClientInterface.js";
+
+/** Products per collection page. */
+export const COLLECTION_PAGE_SIZE = 9;
+
+/** Path of collection page `n` (unformed: the caller applies the tenant's URL form). */
+export function collectionPagePath(handle: string, n: number): string {
+  return n > 1 ? `/collections/${handle}/page/${n}` : `/collections/${handle}`;
+}
+
+/** Number of pages a collection of `total` products spans (at least 1). */
+export function collectionPageCount(total: number, pageSize = COLLECTION_PAGE_SIZE): number {
+  return Math.max(1, Math.ceil(total / pageSize));
+}
+
+/**
+ * The listing query a collection view applies: the URL's own (parsed) params,
+ * the path page when the query names none, and the default page size.
+ */
+export function withPathPage(query: ListProductsQuery, pathPage?: number): ListProductsQuery {
+  const out = { ...query };
+  if (out.page == null && pathPage != null && pathPage > 1) out.page = pathPage;
+  if (!out.pageSize) out.pageSize = COLLECTION_PAGE_SIZE;
+  return out;
+}
+
+/**
+ * Is this view expressible as a path variant — nothing but a page number at the
+ * default page size? Only those views get path pager links; any other view keeps
+ * its query and is applied client-side on a static host.
+ */
+export function isPathPageable(query: ListProductsQuery): boolean {
+  return (
+    (!query.sort || query.sort === "featured") &&
+    !query.q &&
+    !query.filters &&
+    !query.tags?.length &&
+    query.priceMin == null &&
+    query.priceMax == null &&
+    (!query.availability || query.availability === "all") &&
+    (!query.pageSize || query.pageSize === COLLECTION_PAGE_SIZE)
+  );
+}
+
+export interface CollectionListing {
+  collection: CatalogCollection;
+  result: ListProductsResponse;
+  /** Active members with no filters applied: 0 marks a synthesized-empty collection. */
+  memberTotal: number;
+}
+
+/** A public collection's listing for `query`, or null when the collection is absent or hidden. */
+export async function loadCollectionListing(
+  tot: ToTClient,
+  handle: string,
+  query: ListProductsQuery,
+): Promise<CollectionListing | null> {
+  const collection = await tot.getCollectionByHandle(handle);
+  if (!collection || collection.visibility === "hidden") return null;
+  const result = await tot.listProducts({ ...query, collection: handle });
+  const { total: memberTotal } = await tot.listProducts({ collection: handle, pageSize: 1 });
+  return { collection, result, memberTotal };
+}

package/apps/storefront/src/lib/catalog/shared/stockStatus.ts

@@ -0,0 +1,23 @@
+/**
+ * The availability line a variant earns on the PDP. Only what the catalog actually knows is
+ * claimed: "In stock" and "Only N left" need a tracked quantity behind them, so a variant with no
+ * inventory tracking says nothing (like a source that shows no stock text). "Sold out" needs
+ * only `available: false`.
+ */
+export const LOW_STOCK_THRESHOLD = 5;
+
+export interface StockStatus {
+  state: "sold-out" | "low-stock" | "in-stock";
+  label: string;
+}
+
+export function stockStatus(inventory: {
+  available: boolean;
+  quantity?: number | null;
+}): StockStatus | undefined {
+  if (!inventory.available) return { state: "sold-out", label: "Sold out" };
+  const qty = inventory.quantity;
+  if (qty === undefined || qty === null) return undefined;
+  if (qty <= LOW_STOCK_THRESHOLD) return { state: "low-stock", label: `Only ${qty} left` };
+  return { state: "in-stock", label: "In stock" };
+}

package/apps/storefront/src/lib/catalog/tot/query.ts

@@ -27,10 +27,18 @@ export function isAvailable(p: CatalogProduct): boolean {
   return p.variants.some((v) => v.inventory.available);
 }
 
+/**
+ * "New" is the product's real age. The `new` tag is the merchant's explicit call. Otherwise a
+ * product is new only when it has a known creation date inside the window: a record with no
+ * creation date, or whose `created_at` is no earlier than its `migrated_at` (the import stamped
+ * it, so it says when the record arrived, not when the product was created), is not new.
+ */
 export function isNew(p: CatalogProduct, days = 60): boolean {
   if (p.tags.includes("new")) return true;
   const created = Date.parse(p.created_at);
   if (Number.isNaN(created)) return false;
+  const migrated = Date.parse(p.migrated_at);
+  if (!Number.isNaN(migrated) && created >= migrated) return false;
   return Date.now() - created < days * 24 * 60 * 60 * 1000;
 }
 

package/apps/storefront/src/lib/checkout/browser/checkoutRequirementsForm.ts

@@ -0,0 +1,54 @@
+/** Browser wiring for the /admin "Checkout requirements" form: collect the switches, POST, report. */
+
+type StatusState = "ok" | "err";
+
+interface SaveResponse {
+  notice?: string;
+  error?: string;
+  errors?: unknown;
+}
+
+export function saveFailureMessage(status: number, data: SaveResponse): string {
+  if (Array.isArray(data.errors) && data.errors.length) return data.errors.join(" ");
+  return data.error || `Save failed (${status})`;
+}
+
+export function mountCheckoutRequirementsForm(form: HTMLElement): void {
+  const endpoint = form.dataset.endpoint || "/api/preview/checkout-requirements";
+  const targetTenant = form.dataset.targetTenant || "";
+  const status = form.querySelector<HTMLElement>("[data-checkout-requirements-status]");
+  const saveBtn = form.querySelector<HTMLButtonElement>("[data-checkout-requirements-save]");
+  const setStatus = (message: string, state?: StatusState) => {
+    if (!status) return;
+    status.textContent = message;
+    if (state) status.dataset.state = state;
+    else delete status.dataset.state;
+  };
+  saveBtn?.addEventListener("click", async () => {
+    const body: Record<string, unknown> = targetTenant ? { targetTenant } : {};
+    for (const input of form.querySelectorAll<HTMLInputElement>("[data-cr-field]")) {
+      body[input.dataset.crField ?? ""] = input.checked;
+    }
+    setStatus("Saving…");
+    saveBtn.disabled = true;
+    try {
+      const res = await fetch(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      let data: SaveResponse = {};
+      try {
+        data = (await res.json()) as SaveResponse;
+      } catch {
+        // non-JSON error body
+      }
+      if (res.ok) setStatus(data.notice || "Saved to test", "ok");
+      else setStatus(saveFailureMessage(res.status, data), "err");
+    } catch {
+      setStatus("Save failed — network error", "err");
+    } finally {
+      saveBtn.disabled = false;
+    }
+  });
+}

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

@@ -26,14 +26,20 @@ import {
   buildVariantCartPayload,
   commerceTenantId,
   MAX_CART_QUANTITY,
+  SAMPLE_CART_HANDOFF_URL,
+  takeVerificationRef,
+  withVerificationRef,
+  withShippingPolicy,
+  SHIPPING_UNAVAILABLE_CART_MESSAGE,
+  ShippingPolicyUnavailableError,
   type CartDenialCode,
+  type CartSubmissionField,
   type CatalogProduct,
   type TenantConfig,
   type ResolvedManagedCheckout,
 } from "@tot/public-runtime";
 import { resolveCheckoutHandoffCorrelation } from "@/lib/checkout/commerce/checkoutHandoffCorrelation";
 import { resolveCartSigning, shopperCartDenialMessage } from "@/lib/checkout/shared/checkoutCommerce";
-import { readEnv } from "@/lib/publication/shared/runtimeEnv";
 
 export type SampleProductReader = (tenant: TenantConfig, handle: string, commerce: ResolvedManagedCheckout) => Promise<CatalogProduct | null>;
 
@@ -83,8 +89,27 @@ function isCartForm(request: Request): boolean {
   );
 }
 
+/**
+ * The cart with the trusted tenant's declared shipping policy bound in, or `null` when that
+ * policy cannot be charged in the cart's currency: the cart is refused rather than sent on
+ * without the charge the store declared.
+ */
+async function boundShippingPolicy(
+  fields: readonly CartSubmissionField[],
+  tenant: TenantConfig,
+  mode: ResolvedManagedCheckout["mode"],
+  secret: string | undefined,
+): Promise<CartSubmissionField[] | null> {
+  try {
+    return await withShippingPolicy(fields, { mode, secret, policy: tenant.shipping });
+  } catch (err) {
+    if (err instanceof ShippingPolicyUnavailableError) return null;
+    throw err;
+  }
+}
+
 /** Native cart POST. Browser preflight is not consulted. Payment is never authorized. */
-async function cartFormPost(context: APIContext, readSampleProduct?: SampleProductReader): Promise<Response> {
+async function cartFormPost(context: APIContext): Promise<Response> {
   const { tenant, commerce } = context.locals;
   if (!commerce) {
     return cartDenial(
@@ -102,38 +127,13 @@ async function cartFormPost(context: APIContext, readSampleProduct?: SampleProdu
     );
   }
   const form = await context.request.formData();
-  const entries: Array<[string, string]> = [];
+  const submitted: Array<[string, string]> = [];
   for (const [name, value] of form.entries()) {
     if (typeof value !== "string") return cartDenial("signature", "Invalid cart.", 422);
-    entries.push([name, value]);
-  }
-  if (form.has("sample_product") || form.has("sample_variant")) {
-    const sampleTenant = await readEnv("COMMERCE_SAMPLE_TENANT_ID");
-    if (
-      !sampleTenant || sampleTenant !== commerceTenantId(tenant) ||
-      await readEnv("COMMERCE_DEMO_CHECKOUT_TIER") !== "test" || commerce.mode !== "signed"
-    ) return cartDenial("tenant", "Invalid cart.", 422);
-    const allowed = new Set(["sample_product", "sample_variant", "quantity"]);
-    if (entries.length !== 3 || entries.some(([name]) => !allowed.has(name)) ||
-      new Set(entries.map(([name]) => name)).size !== 3) {
-      return cartDenial("signature", "Invalid cart.", 422);
-    }
-    const quantity = form.get("quantity") as string;
-    if (!/^[1-9][0-9]*$/.test(quantity) || !Number.isSafeInteger(Number(quantity)) || Number(quantity) > MAX_CART_QUANTITY) {
-      return cartDenial("quantity", "Invalid quantity.", 422);
-    }
-    const product = await readSampleProduct?.(tenant, form.get("sample_product") as string, commerce) ?? null;
-    const variant = product?.variants.find((v) => v.id === form.get("sample_variant"));
-    if (!product || product.status !== "active" || product.visibility === "hidden" || product.visibility === "unlisted" ||
-      !variant || !variant.inventory.available || product.tenant_id !== tenant.tot_data_scope ||
-      variant.tenant_id !== tenant.tot_data_scope) {
-      return cartDenial("signature", "Product is unavailable.", 422);
-    }
-    const payload = await buildVariantCartPayload(product, variant, {
-      mode: "signed", secret: signing.secret, tenantId: commerceTenantId(tenant),
-    });
-    entries.splice(0, entries.length, ...payload.hidden.map((f): [string, string] => [f.name, f.value]), [payload.quantityName, quantity]);
+    submitted.push([name, value]);
   }
+  // The compliance gate adds the shopper's verification ref; it rides to the cart signed.
+  const { entries, ref } = takeVerificationRef(submitted);
   const result = await enforceCartSubmission({
     entries,
     mode: commerce.mode,
@@ -144,18 +144,21 @@ async function cartFormPost(context: APIContext, readSampleProduct?: SampleProdu
     const status = result.code === "signing-unavailable" ? 503 : 422;
     return cartDenial(result.code, shopperCartDenialMessage(result.code, result.message), status);
   }
+  const verified = await withVerificationRef(result.fields, { mode: commerce.mode, secret: signing.secret, ref });
+  const shipped = await boundShippingPolicy(verified, tenant, commerce.mode, signing.secret);
+  if (!shipped) return cartDenial("shipping", SHIPPING_UNAVAILABLE_CART_MESSAGE, 409);
   return new Response(null, {
     status: 303,
     headers: {
-      location: foxyCartRedirectUrl(commerce.cartUrl, result.fields),
+      location: foxyCartRedirectUrl(commerce.cartUrl, shipped),
       "cache-control": "no-store",
       "x-tot-payment-authorized": "false",
     },
   });
 }
 
-export async function checkoutHandoffPost(context: APIContext, readSampleProduct?: SampleProductReader): Promise<Response> {
-  if (isCartForm(context.request)) return cartFormPost(context, readSampleProduct);
+export async function checkoutHandoffPost(context: APIContext): Promise<Response> {
+  if (isCartForm(context.request)) return cartFormPost(context);
   const { tenant, browserEnvironment, commerce } = context.locals;
 
   // No managed checkout on this tenant → nothing to attribute.
@@ -189,7 +192,72 @@ export async function checkoutHandoffPost(context: APIContext, readSampleProduct
   return json({ attributed: false, reason: result.reason });
 }
 
-export async function GET(): Promise<Response> {
+/** Hosted-only dependencies; the renderer GET below never receives these. */
+export interface SampleCartContext {
+  tenant: TenantConfig;
+  commerce: ResolvedManagedCheckout;
+}
+
+function sampleResponse(body: string | null, status: number, location?: string): Response {
+  return new Response(body, { status, headers: {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "private, no-store",
+    "referrer-policy": "no-referrer",
+    "x-robots-tag": "noindex, nofollow",
+    "x-tot-payment-authorized": "false",
+    ...(location ? { location } : {}),
+  } });
+}
+
+/** Identifier-only GET: caller state never supplies tenant, catalog or checkout authority. */
+export async function sampleCartGet(
+  context: APIContext,
+  resolveContext: () => Promise<SampleCartContext | null>,
+  readProduct: SampleProductReader,
+): Promise<Response> {
+  const url = new URL(context.request.url);
+  const canonical = new URL(SAMPLE_CART_HANDOFF_URL);
+  const invalid = () => sampleResponse('{"error":"invalid_sample_cart"}', 422);
+  if (context.request.method !== "GET" || url.origin !== canonical.origin || url.pathname !== canonical.pathname ||
+      (context.request.headers.get("host") ?? url.host) !== canonical.host || url.search.length > 4096) return invalid();
+  const entries = [...url.searchParams];
+  const allowed = new Set(["sample_product", "sample_variant", "quantity"]);
+  if (entries.length !== 3 ||
+      entries.some(([key]) => !allowed.has(key)) || new Set(entries.map(([key]) => key)).size !== 3) return invalid();
+  const productId = url.searchParams.get("sample_product")!;
+  const variantId = url.searchParams.get("sample_variant")!;
+  const quantity = url.searchParams.get("quantity")!;
+  const safeId = (value: string) => value.length > 0 && value.length <= 256 &&
+    !/[\p{Cc}\s/\\%]/u.test(value) && value !== "." && !value.includes("..");
+  if (!safeId(productId) || !safeId(variantId) || !/^[1-9][0-9]*$/.test(quantity) ||
+      !Number.isSafeInteger(Number(quantity)) || Number(quantity) > MAX_CART_QUANTITY) return invalid();
+  try {
+    const trusted = await resolveContext();
+    if (!trusted) return sampleResponse('{"error":"sample_unavailable"}', 503);
+    const { tenant, commerce } = trusted;
+    const product = await readProduct(tenant, productId, commerce);
+    const variant = product?.variants.find(v => v.id === variantId);
+    if (!product || product.status !== "active" || product.visibility === "hidden" || product.visibility === "unlisted" ||
+        !variant || !variant.inventory.available || product.tenant_id !== tenant.tot_data_scope ||
+        variant.tenant_id !== tenant.tot_data_scope) return invalid();
+    const signing = await resolveCartSigning(commerce);
+    if (!signing.enabled) return sampleResponse('{"error":"sample_unavailable"}', 503);
+    const payload = await buildVariantCartPayload(product, variant, {
+      mode: "signed", secret: signing.secret, tenantId: commerceTenantId(tenant), currency: tenant.currency,
+    });
+    const result = await enforceCartSubmission({
+      entries: [...payload.hidden.map((f): [string, string] => [f.name, f.value]), [payload.quantityName, quantity]],
+      mode: "signed", secret: signing.secret, trustedTenantId: commerceTenantId(tenant),
+    });
+    if (!result.ok) return invalid();
+    const shipped = await boundShippingPolicy(result.fields, tenant, "signed", signing.secret);
+    if (!shipped) return sampleResponse('{"error":"shipping_unavailable"}', 409);
+    return sampleResponse(null, 303, foxyCartRedirectUrl(commerce.cartUrl, shipped));
+  } catch { return sampleResponse('{"error":"sample_unavailable"}', 503); }
+}
+
+/** Same `(context)` signature as the hosted page's GET, so the runner's projection typechecks against the middleware call. */
+export async function GET(_context: APIContext): Promise<Response> {
   return json({ error: "method_not_allowed" }, 405);
 }
 

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

@@ -0,0 +1,88 @@
+/**
+ * A store's checkout requirements on the shared ToT test store: the three switches in
+ * /admin → Settings → Checkout requirements.
+ *
+ * They are merchant-operated commerce settings (ADR 0035 "operational"), saved as the
+ * tenant-owned artifact `tenants/<id>/checkout-requirements.json` on the publish spine — saved
+ * to `test`, promoted to `live` with the rest of the store. Every switch defaults off and can
+ * only make checkout stricter, so no write can weaken what the platform enforces. They apply
+ * only while the store checks out on the shared test store; a store with its own checkout store,
+ * and production, keep the full fail-closed contract regardless of what is saved here.
+ */
+import { readPublishedArtifact, type CustomizationEnv } from "@tot/public-runtime";
+import { readKv } from "@/lib/publication/shared/runtimeEnv";
+
+export interface CheckoutRequirements {
+  /** Require a real ID verification the final-cart authority re-reads server-side. */
+  verification: boolean;
+  /** Require tax evidence. No producer exists yet, so the save refuses `true`. */
+  tax: boolean;
+  /** Enforce compliance rules (destination, flavor, purchase limits). */
+  rules: boolean;
+}
+
+export const CHECKOUT_REQUIREMENT_KEYS = ["verification", "tax", "rules"] as const;
+
+export const DEFAULT_CHECKOUT_REQUIREMENTS: Readonly<CheckoutRequirements> = Object.freeze({
+  verification: false,
+  tax: false,
+  rules: false,
+});
+
+export function checkoutRequirementsArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/checkout-requirements.json`;
+}
+
+/**
+ * Parse a published artifact. Absent → the defaults. Anything other than an object of the
+ * known boolean keys is `null` (unreadable): a reader must then fail closed, never treat a
+ * corrupt switch as off.
+ */
+export function parseCheckoutRequirements(raw: string | null): CheckoutRequirements | null {
+  if (raw === null) return { ...DEFAULT_CHECKOUT_REQUIREMENTS };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const value = parsed as Record<string, unknown>;
+  if (Object.keys(value).some(key => !(CHECKOUT_REQUIREMENT_KEYS as readonly string[]).includes(key))) return null;
+  const out = { ...DEFAULT_CHECKOUT_REQUIREMENTS };
+  for (const key of CHECKOUT_REQUIREMENT_KEYS) {
+    if (value[key] === undefined) continue;
+    if (typeof value[key] !== "boolean") return null;
+    out[key] = value[key] as boolean;
+  }
+  return out;
+}
+
+export type CheckoutRequirementsInput =
+  | { ok: true; requirements: CheckoutRequirements }
+  | { ok: false; errors: string[] };
+
+/** Validate a save from /admin. Tax evidence cannot be required until it has a producer. */
+export function validateCheckoutRequirementsInput(raw: unknown): CheckoutRequirementsInput {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, errors: ["body must be a JSON object"] };
+  const body = raw as Record<string, unknown>;
+  const errors: string[] = [];
+  const requirements = { ...DEFAULT_CHECKOUT_REQUIREMENTS };
+  for (const key of CHECKOUT_REQUIREMENT_KEYS) {
+    if (typeof body[key] !== "boolean") errors.push(`${key} must be true or false`);
+    else requirements[key] = body[key] as boolean;
+  }
+  if (requirements.tax) errors.push("Tax evidence can't be required yet: it needs excise setup first.");
+  return errors.length ? { ok: false, errors } : { ok: true, requirements };
+}
+
+/** The store's saved requirements for `env`, or `null` when they cannot be read. */
+export async function readCheckoutRequirements(tenantId: string, env: CustomizationEnv): Promise<CheckoutRequirements | null> {
+  const kv = await readKv("TENANT_CACHE");
+  if (!kv) return null;
+  try {
+    return parseCheckoutRequirements(await readPublishedArtifact(key => kv.get(key), tenantId, env, checkoutRequirementsArtifactPath(tenantId)));
+  } catch {
+    return null;
+  }
+}

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

@@ -26,6 +26,8 @@ export interface SeamView {
   status: "clear" | "absent" | "blocked";
   failedClosed?: boolean;
   codes?: readonly string[];
+  /** Flavor labels that triggered a `flavored_prohibited` block, for the refusal. */
+  flavors?: readonly string[];
 }
 
 export interface FinalCartRequest {