@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

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, deriveProductProfile,
+  commerceTenantId, totalsMatch, canonicalJson, shippingMinorFor,
   type CallerToken, type CatalogProduct, type CommerceEvidence, type CommerceEvidenceProvenance,
   type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
@@ -12,14 +12,20 @@ import { evaluateFinalCart, type SeamView } from "@/lib/checkout/commerce/finalC
 import { d1CommerceRunner, reserveAllocation } from "@/lib/inventory/allocations.js";
 import { readMirrorStock } from "@/lib/inventory/mirrorStock.js";
 import { admissionMatches, readCommerceAdmission, admissionSnapshotStatement } from "@/lib/checkout/commerce/commerceAdmission.js";
-import { isRegulatedTenant } from "@/lib/compliance/enforcement.js";
-import { POST as compliancePreflight } from "../compliance/preflight.js";
-import { resolveAdminTargetTenant } from "@/config/adminTargetTenant";
-import { withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
+import { evaluatePreflight } from "../compliance/preflight.js";
+import {
+  admitSharedStoreTenant, testStoreEvidencePolicy, SHARED_STORE_POLICY_REVISION, SHARED_STORE_POLICY_SOURCE,
+  SHARED_STORE_VERIFICATION_SOURCE, type SharedStoreEvidencePolicy,
+} from "@/lib/checkout/commerce/sharedStoreAdmission.js";
+import { readCheckoutRequirements } from "@/lib/checkout/commerce/checkoutRequirements.js";
+import { DeclaredTenantConfigUnreadError, withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
+import { resolveStoreCurrency } from "@tot/public-runtime/declared-tenant-config";
 import { createContentProvider } from "@/lib/content/storyblok/provider";
 import { createToTClient } from "@/lib/catalog/tot/ToTClient";
 export const prerender = false;
 const HEX = /^[a-f0-9]{64}$/;
+/** The shopper's verification correlation handle, as the signed `verification` cart option carries it. */
+const VERIFICATION_REF = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,199}$/;
 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" } });
 }
@@ -46,8 +52,10 @@ 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"];
-  if (Object.keys(v).some(k => !allowed.includes(k) && k !== "expectedAuthorizationId") || allowed.some(k => !(k in v))) return null;
+  const optional = ["expectedAuthorizationId", "verificationRef"];
+  if (Object.keys(v).some(k => !allowed.includes(k) && !optional.includes(k)) || allowed.some(k => !(k in v))) 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) ||
       typeof v.providerCartDigest !== "string" || !HEX.test(v.providerCartDigest) || typeof v.destinationDigest !== "string" || !HEX.test(v.destinationDigest) ||
       typeof v.tenantId !== "string" || !["preview", "publication"].includes(String(v.stage)) || typeof v.currency !== "string" || !/^[A-Z]{3}$/.test(v.currency) ||
@@ -64,19 +72,46 @@ function readSnapshot(value: unknown): CommerceProviderCartSnapshot | null {
   if (!totalsMatch(snapshot.totals) || snapshot.lines.reduce((sum, line) => sum + line.quantity * line.unitMinor, 0) !== snapshot.totals.subtotalMinor) return null;
   return snapshot;
 }
-async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot, products: readonly CatalogProduct[]): Promise<SeamView> {
-  const response = await compliancePreflight({
-    request: new Request("https://checkout.invalid/api/compliance/preflight", {
-      method: "POST", headers: { "content-type": "application/json" },
-      body: JSON.stringify({ lines: snapshot.lines.map(line => ({ handle: products.find(p => p.variants.some(v => v.sku === line.sku))!.handle, sku: line.sku, quantity: line.quantity })), destination: snapshot.destination }),
-    }), locals: { tenant: context.locals.tenant, tot: context.locals.tot },
-  } as APIContext);
+/**
+ * The compliance seam under the shared test store's policy. When verification is required the
+ * cart's verification ref goes to preflight, whose live provider re-reads its real status
+ * server-side; `verified` is true only when that read satisfied the requirement.
+ */
+async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot, selected: ReadonlyMap<string, CatalogProduct>, policy: SharedStoreEvidencePolicy): Promise<SeamView & { verified: boolean }> {
+  if (policy.rules === "off" && policy.verification === "not-required") return { status: "clear", verified: false };
+  const products = [...selected.values()];
   try {
-    const body = await response.json() as { decision?: { status?: string; failedClosed?: boolean; blocks?: { code?: string }[] } };
-    if (!body.decision) return { status: "absent" };
-    if (body.decision.status === "clear") return { status: "clear" };
-    return { status: "blocked", failedClosed: body.decision.failedClosed === true, codes: body.decision.blocks?.map(b => b.code ?? "") };
-  } catch { return { status: "absent" }; }
+    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 })),
+      destination: snapshot.destination,
+      ...(policy.verification === "required" && snapshot.verificationRef ? { verificationRef: snapshot.verificationRef } : {}),
+    }, { verification: policy.verification, rules: policy.rules });
+    const verified = policy.verification === "required" && decision.requirements.ageVerification === "satisfied";
+    const blocks = decision.blocks;
+    if (blocks.length === 0) return { status: "clear", verified };
+    const flavors = [...new Set(blocks.flatMap(block => block.code === "flavored_prohibited" ? block.flavors ?? [] : []))];
+    return { status: "blocked", verified, failedClosed: blocks.some(block => block.failedClosed === true), codes: blocks.map(block => block.code),
+      ...(flavors.length ? { flavors } : {}) };
+  } catch { return { status: "absent", verified: false }; }
+}
+function fullCartProduct(value: unknown, handle: string, scope: string): value is CatalogProduct {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const product = value as CatalogProduct;
+  return product.handle === handle && product.tenant_id === scope && typeof product.id === "string" && !!product.id &&
+    product.status === "active" && (product.visibility === undefined || product.visibility === "public") &&
+    typeof product.title === "string" && (product.product_type === undefined || typeof product.product_type === "string") &&
+    Array.isArray(product.tags) && product.tags.every(tag => typeof tag === "string") &&
+    Array.isArray(product.metafields) && product.metafields.every(field => field && typeof field === "object" && !Array.isArray(field) &&
+      typeof field.namespace === "string" && typeof field.key === "string" && typeof field.value === "string") &&
+    Array.isArray(product.variants) && product.variants.length > 0 && product.variants.every(variant => variant && typeof variant === "object" && !Array.isArray(variant) &&
+      variant.tenant_id === scope && variant.product_id === product.id && typeof variant.id === "string" && !!variant.id &&
+      (variant.sku === undefined || typeof variant.sku === "string") && Number.isFinite(variant.price) && variant.price >= 0 &&
+      typeof variant.currency === "string" && /^[A-Z]{3}$/.test(variant.currency) &&
+      variant.option_values && typeof variant.option_values === "object" && !Array.isArray(variant.option_values) &&
+      Object.values(variant.option_values).every(option => typeof option === "string") &&
+      variant.inventory && typeof variant.inventory === "object" && !Array.isArray(variant.inventory) && typeof variant.inventory.available === "boolean");
 }
 export async function POST(context: APIContext): Promise<Response> {
   if (Number(context.request.headers.get("content-length") ?? 0) > 65536) return deny("malformed-request");
@@ -102,28 +137,58 @@ export async function POST(context: APIContext): Promise<Response> {
     token = { scheme: "asymmetric-jwks", signatureValid: true, kid: header.kid, issuer: payload.iss ?? "", audience,
       expiresAt: new Date(payload.exp * 1000).toISOString(), jti: payload.jti ?? "", tenantId: snapshot.tenantId, stage: snapshot.stage };
   } catch { return deny("signature", 401); }
-  const allowedTenants = list(await readEnv("COMMERCE_TENANT_ALLOWLIST"));
-  if (!allowedTenants || !allowedTenants.includes(snapshot.tenantId)) return deny("tenant", 401);
-  const registered = await resolveAdminTargetTenant(snapshot.tenantId);
-  if (!registered || commerceTenantId(registered) !== snapshot.tenantId) return deny("tenant-unregistered", 401);
+  const admission = await admitSharedStoreTenant(snapshot.tenantId);
+  if (!admission.ok) return deny(admission.finding, 401);
+  const registered = admission.tenant;
   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 tenant = await withDeclaredTenantConfig(registered, kvGet, { env: contentEnv });
+  let tenant: TenantConfig;
+  try { tenant = await withDeclaredTenantConfig(registered, kvGet, { env: contentEnv }); } catch (err) {
+    if (err instanceof DeclaredTenantConfigUnreadError) return deny("config-unreadable", 503);
+    throw err;
+  }
   const content = 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");
-  let products: CatalogProduct[];
-  try { products = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
+  let listing: CatalogProduct[];
+  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 matches = products.flatMap(product => product.status === "active" && (!product.visibility || product.visibility === "public") && product.tenant_id === tenant.tot_data_scope
-      ? product.variants.filter(v => v.sku === line.sku).map(variant => ({ product, variant })) : []);
+    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");
+    const match = matches[0]!;
+    const handle = match.product.handle;
+    if (typeof handle !== "string" || !handle) return deny("catalog-cart-mismatch");
+    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");
+      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");
+    const variant = variants[0]!;
     const digits = new Intl.NumberFormat("en", { style: "currency", currency: snapshot.currency }).resolvedOptions().maximumFractionDigits ?? 2;
-    const scaled = (matches[0]?.variant.price ?? -1) * 10 ** digits;
-    if (matches.length !== 1 || !matches[0]!.variant.inventory.available || matches[0]!.variant.currency !== snapshot.currency || Math.abs(scaled - Math.round(scaled)) > 0.000001 || Math.round(scaled) !== line.unitMinor) return deny("catalog-cart-mismatch");
+    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");
+  }
+  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");
+  // 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) {
+    let owed: number;
+    try { owed = shippingMinorFor(tenant.shipping, snapshot.currency, snapshot.totals.subtotalMinor); } catch { return deny("shipping-unavailable"); }
+    if (snapshot.totals.shippingMinor !== owed) return deny("shipping-changed");
   }
   const database = await readD1("STOREFRONT_APPS_DB");
   if (!database) return deny("store-unconfigured", 503);
@@ -142,35 +207,40 @@ export async function POST(context: APIContext): Promise<Response> {
   const existing = prior ? await readCommerceAdmission(queryable, snapshot.tenantId, snapshot.stage, prior.authorization_id) : null;
   if (prior && (!existing || existing.expiresAt <= now)) return deny("admission-expired");
   if (existing && !admissionMatches(existing, snapshot)) return deny("provider-cart-changed");
-  const policy = tenant.commerce?.authorityPolicy;
-  const testPolicy = policy?.purpose === "synthetic-nonbillable" && typeof policy.revision === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(policy.revision) &&
-    Number.isFinite(Date.parse(policy.expiresAt)) && policy.expiresAt > now && await readEnv("COMMERCE_DEMO_CHECKOUT_TIER") === "test" &&
-    tenant.commerce?.checkout?.storeSubDomain === "tot-preview" && tenant.commerce.checkout.mode === "signed" &&
-    ["verification", "tax", "risk"].every(field => ["required", "not-required"].includes(policy.requirements?.[field as "verification" | "tax" | "risk"]));
-  const regulated = isRegulatedTenant(tenant) || !!tenant.compliance?.pactAct || !!tenant.compliance?.exciseTax ||
-    snapshot.lines.some(line => products.some(p => p.variants.some(v => v.sku === line.sku && ["ends", "e-liquid", "other-nicotine"].includes(deriveProductProfile(p, v).category))));
-  if (testPolicy && regulated && (policy.requirements.verification === "not-required" || policy.requirements.tax === "not-required")) return deny("authority-policy-regulated");
+  const requirements = await readCheckoutRequirements(tenant.tenant_id, contentEnv);
+  if (!requirements) return deny("checkout-requirements-unreadable", 503);
+  const policy = testStoreEvidencePolicy(requirements);
   const authorities = [];
   for (const sku of new Set(snapshot.lines.map(line => line.sku))) {
     authorities.push(await readMirrorStock(queryable, { tenantId: snapshot.tenantId, stage: snapshot.stage, sku, locationId: "unspecified", now, maxAgeMs: 15 * 60_000 }));
   }
   const stockExpiry = Math.min(...authorities.flatMap(authority => authority ? [Date.parse(authority.asOf) + 15 * 60_000] : []));
   const evidence: CommerceEvidence = { verification: "absent", tax: "absent", risk: "absent", stock: "fresh" };
-  const expiresAt = existing?.expiresAt ?? new Date(Math.min(Date.now() + 5 * 60_000, stockExpiry, testPolicy ? Date.parse(policy.expiresAt) : Infinity)).toISOString();
+  const expiresAt = existing?.expiresAt ?? new Date(Math.min(Date.now() + 5 * 60_000, stockExpiry)).toISOString();
   const provenance = {} as CommerceEvidenceProvenance;
   for (const field of ["verification", "tax", "risk"] as const) {
-    if (testPolicy && policy.requirements?.[field] === "not-required") {
+    if (policy[field] === "not-required") {
       evidence[field] = "not-required";
-      provenance[field] = { requirement: "not-required", state: "not-required", source: "declared-synthetic-policy", policyRevision: policy.revision, expiresAt };
+      provenance[field] = { requirement: "not-required", state: "not-required", source: SHARED_STORE_POLICY_SOURCE, policyRevision: SHARED_STORE_POLICY_REVISION, expiresAt };
     }
   }
   provenance.stock = { requirement: "required", state: "satisfied", source: "tenant-inventory-movements", policyRevision: "mirror-v1", expiresAt };
   const presented: FinalCartBinding = { tenantId: snapshot.tenantId, stage: snapshot.stage, currency: snapshot.currency, lines: snapshot.lines,
     destinationDigest: snapshot.destinationDigest, verificationExpiresAt: expiresAt, taxExpiresAt: expiresAt };
+  const seamView = await seam(authorityContext, snapshot, selected, policy);
+  if (policy.verification === "required" && seamView.verified) {
+    evidence.verification = "fresh";
+    provenance.verification = { requirement: "required", state: "satisfied", source: SHARED_STORE_VERIFICATION_SOURCE, policyRevision: SHARED_STORE_POLICY_REVISION, expiresAt };
+  }
   const decision = await evaluateFinalCart({ now, routedTenantId: commerceTenantId(tenant), quoted: presented, presented, evidence,
-    seam: await seam(authorityContext, snapshot, products), catalogAvailable: true, browserConfirmed: false, token,
+    seam: seamView, catalogAvailable: true, browserConfirmed: false, token,
     trustedIssuers: issuers, expectedAudience: audience, activeKids, authorities });
-  if (!decision.ok) return deny(decision.finding, 409, decision.owner);
+  if (!decision.ok) {
+    if (decision.finding === "verification-refused:flavored_prohibited" && seamView.flavors) {
+      return json({ ok: false, finding: decision.finding, flavors: seamView.flavors }, 409);
+    }
+    return deny(decision.finding, 409, decision.owner);
+  }
   const authorizationId = existing?.authorizationId ?? `a${crypto.randomUUID()}`;
   // Retries of the same verified provider cart share one reservation, including concurrent callbacks.
   const cartDigest = existing?.cartDigest ?? await digest(`commerce-provider-cart-v1\n${snapshot.providerCartId}\n${snapshot.providerCartDigest}`);

package/apps/storefront/src/pages/api/compliance/preflight.ts

@@ -34,6 +34,7 @@ import {
   type TotVerificationClient,
   type TotVerificationStatus,
 } from "@/lib/compliance/verification/totVerificationClient";
+import { sharedStorePolicy } from "@/lib/checkout/commerce/sharedStoreAdmission";
 
 export const prerender = false;
 
@@ -268,8 +269,7 @@ function withProviderCleared(ruleset: ComplianceRuleset): ComplianceRuleset {
 }
 
 export async function POST(context: APIContext): Promise<Response> {
-  const { tenant, tot } = context.locals;
-  const regulated = isRegulatedTenant(tenant);
+  const regulated = isRegulatedTenant(context.locals.tenant);
 
   let body: PreflightBody;
   try {
@@ -281,7 +281,45 @@ export async function POST(context: APIContext): Promise<Response> {
       : json({ decision: evaluateEmpty() });
   }
 
+  // The shared test store applies the store's own saved requirements, computed here from the
+  // tenant's config — never from the request, so a shopper cannot waive one.
+  const policy = await sharedStorePolicy(context.locals.tenant, context.locals.commerce, context.locals.customizationEnv);
+  return json(await evaluatePreflight(context, body, policy ? { verification: policy.verification, rules: policy.rules } : {}));
+}
+
+export interface PreflightOptions {
+  /**
+   * Server-owned verification requirement, from the shared test store's policy for this
+   * tenant. "required" requires verification even where the ruleset would not; absent keeps
+   * the ruleset's own. Never read from the request body.
+   */
+  verification?: "required" | "not-required";
+  /**
+   * Server-owned rule enforcement, from the same policy. "off" keeps only the verification
+   * outcome: destination, flavor, purchase-limit and excise blocks do not apply.
+   */
+  rules?: "enforce" | "off";
+}
+
+export interface PreflightResult {
+  decision: CartComplianceDecision;
+  verification?: LiveVerificationMeta;
+}
+
+/** The preflight decision for `body`, evaluated server-side against the tenant's ruleset. */
+export async function evaluatePreflight(
+  context: APIContext,
+  body: PreflightBody,
+  options: PreflightOptions = {},
+): Promise<PreflightResult> {
+  const { tenant, tot } = context.locals;
+  const regulated = isRegulatedTenant(tenant);
+
   let ruleset = await resolveTenantRuleset(tenant);
+  if (ruleset && options.verification) {
+    ruleset = { ...ruleset, verification: { ...ruleset.verification, required: options.verification === "required" } };
+  }
+  const rulesOff = options.rules === "off";
   let verification = normalizeVerification(body.verification);
   const destination = normalizeDestination(body.destination);
   let liveVerification: LiveVerificationMeta | undefined;
@@ -291,7 +329,7 @@ export async function POST(context: APIContext): Promise<Response> {
   // not evidence) and the affirmation shortcut below is unreachable — "tot" is
   // never in SANDBOX_VERIFICATION_PROVIDERS. Any adapter failure clears the
   // provider so the engine blocks fail-closed, exactly as when none is wired.
-  if (ruleset && isLiveTotVerificationProvider(ruleset.verification.provider)) {
+  if (ruleset && ruleset.verification.required && isLiveTotVerificationProvider(ruleset.verification.provider)) {
     const resolved = await resolveLiveVerification(body);
     if (!resolved) {
       ruleset = withProviderCleared(ruleset);
@@ -330,15 +368,12 @@ export async function POST(context: APIContext): Promise<Response> {
     if (!product) {
       // A line we can't resolve on a regulated tenant is a fail-closed block:
       // we can't prove it's shippable, so we don't let it through.
-      if (regulated) {
-        return json(
-          {
-            decision: blockedDecision(
-              `Product "${raw.handle}" could not be resolved for compliance evaluation.`,
-            ),
-          },
-          200,
-        );
+      if (regulated && !rulesOff) {
+        return {
+          decision: blockedDecision(
+            `Product "${raw.handle}" could not be resolved for compliance evaluation.`,
+          ),
+        };
       }
       continue;
     }
@@ -364,7 +399,20 @@ export async function POST(context: APIContext): Promise<Response> {
     ageAffirmed: body.ageAffirmed === true,
   });
 
-  return json(liveVerification ? { decision, verification: liveVerification } : { decision });
+  const applied = rulesOff ? verificationOnly(decision) : decision;
+  return liveVerification ? { decision: applied, verification: liveVerification } : { decision: applied };
+}
+
+/** The decision with only its verification outcome: every rule block removed, status recomputed. */
+function verificationOnly(decision: CartComplianceDecision): CartComplianceDecision {
+  const blocks = decision.blocks.filter((block) => block.code.startsWith("verification_"));
+  return {
+    ...decision,
+    blocks,
+    purchaseLimit: null,
+    failedClosed: blocks.some((block) => block.failedClosed === true),
+    status: blocks.some((block) => block.code !== "verification_required") ? "blocked" : blocks.length ? "action_required" : "clear",
+  };
 }
 
 /** The trivial "nothing to enforce" decision for an unregulated empty request. */

package/apps/storefront/src/pages/blog/author/[author].astro

@@ -70,7 +70,7 @@ const crumbs = breadcrumbLd(trail, canonicalBase);
   path={blogPaths.author(slug)}
   fullBleed
   jsonLd={[crumbs, profileLd, itemListLd]}
-  structuredData={{ pageType: "collection" }}
+  structuredData={{ pageType: "collection", crumbs: trail, items: posts.map((post) => ({ title: post.title, url: new URL(blogPaths.post(post.slug), canonicalBase + "/").toString() })) }}
 >
   <header class:list={["author-hero", { "author-hero--plain": !presentation.hero }]}>
     <div class="blog-shell">

package/apps/storefront/src/pages/blog/category/[category].astro

@@ -48,7 +48,7 @@ const crumbs = breadcrumbLd(trail, canonicalBase);
   path={path}
   fullBleed
   jsonLd={[crumbs, itemList]}
-  structuredData={{ pageType: "collection" }}
+  structuredData={{ pageType: "collection", crumbs: trail, items: posts.map((post) => ({ title: post.title, url: new URL(blogPaths.post(post.slug), canonicalBase + "/").toString() })) }}
 >
   <header class:list={["blog-hero", { "blog-hero--plain": !presentation.hero }]}>
     <div class="blog-shell">

package/apps/storefront/src/pages/blog/tag/[tag].astro

@@ -46,7 +46,7 @@ const crumbs = breadcrumbLd(trail, canonicalBase);
   path={path}
   fullBleed
   jsonLd={[crumbs, itemList]}
-  structuredData={{ pageType: "collection" }}
+  structuredData={{ pageType: "collection", crumbs: trail, items: posts.map((post) => ({ title: post.title, url: new URL(blogPaths.post(post.slug), canonicalBase + "/").toString() })) }}
 >
   <header class:list={["blog-hero", { "blog-hero--plain": !presentation.hero }]}>
     <div class="blog-shell">

package/apps/storefront/src/pages/catalog-index.json.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-tenant static catalog index (lib/catalog/shared/catalogIndex.ts): what the
+ * browser filters, sorts and searches when a static host serves a listing or
+ * search page whose query no renderer saw. Published alongside the pages it
+ * serves; commerce-only.
+ */
+import type { APIContext } from "astro";
+import { buildCatalogIndex } from "@/lib/catalog/shared/catalogIndex.js";
+
+export async function GET(context: APIContext): Promise<Response> {
+  const { tot, features } = context.locals;
+  if (!features.catalog && !features.productSearch) return new Response(null, { status: 404 });
+  const [products, collections] = await Promise.all([tot.getAllActiveProducts(), tot.listCollections()]);
+  return new Response(JSON.stringify(buildCatalogIndex(products, collections)), {
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "public, max-age=300, s-maxage=3600",
+    },
+  });
+}

package/apps/storefront/src/pages/collections/[handle]/page/[n].astro

@@ -0,0 +1,28 @@
+---
+/**
+ * `/collections/<h>/page/<n>/` — page N≥2 of a collection, the indexable path
+ * variant every static host can serve (ADR 0013: paging is N-bounded). Page 1
+ * lives at the bare collection path; both render through _CollectionView.
+ */
+import CollectionView from "../../_CollectionView.astro";
+import { collectionPageCount, loadCollectionListing } from "@/lib/catalog/shared/collectionPaging";
+import { effectiveCollectionQuery } from "@/lib/publication/shared/staticQuery";
+import { parsePagedRouteParam } from "@/lib/content/blog/pagination";
+
+// Same query contract as page 1: sort/facets/price/search are applied client-side
+// on a static host, the page number comes from the path.
+export const STATIC_QUERY = "client-applied";
+
+const { handle } = Astro.params;
+if (!Astro.locals.features.catalog) return new Response(null, { status: 404 });
+const pathPage = parsePagedRouteParam(Astro.params.n);
+if (!handle || pathPage === null) return new Response(null, { status: 404 });
+
+const query = effectiveCollectionQuery(Astro.url, pathPage);
+const listing = await loadCollectionListing(Astro.locals.tot, handle, query);
+if (!listing) return new Response(null, { status: 404 });
+// A page past the collection's end is a real 404, never a clamped copy of the last page.
+if (pathPage > collectionPageCount(listing.memberTotal)) return new Response(null, { status: 404 });
+---
+
+<CollectionView {...listing} query={query} pathPage={pathPage} />