@tokenoftrust/storefront-runner 2.4.91 → 2.5.0

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

@@ -1,333 +1,185 @@
-/**
- * POST /api/commerce/final-cart-authorization — time-limited final-cart admission.
- * Caller-owned asymmetric tokens only. Catalog availability, a browser confirmation,
- * and missing verification evidence do not authorize payment.
- */
+/** Provider-authenticated final-cart admission. Evidence and applicability are server-owned. */
 import type { APIContext } from "astro";
-import { createLocalJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify, type JSONWebKeySet, type JWTPayload } from "jose";
-import type { TenantConfig } from "@tot/public-runtime";
+import { createLocalJWKSet, decodeProtectedHeader, jwtVerify, type JSONWebKeySet } from "jose";
 import {
-  type CallerToken,
-  type CommerceEvidence,
-  type CommerceStage,
-  type EvidenceState,
-  type FinalCartBinding,
-  type FulfillmentState,
-  type LabelState,
-  type PaymentState,
-  type StockState,
+  commerceTenantId, totalsMatch, canonicalJson, deriveProductProfile,
+  type CallerToken, type CatalogProduct, type CommerceEvidence, type CommerceEvidenceProvenance,
+  type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
-import { fromD1, listAllActiveProducts } from "@/lib/catalog/d1/catalog.js";
-import { readD1, readEnv } from "@/lib/publication/shared/env";
+import { fromD1 } from "@/lib/catalog/d1/catalog.js";
+import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
 import { evaluateFinalCart, type SeamView } from "@/lib/checkout/commerce/finalCartAuthorization.js";
-import { d1CommerceRunner, mirrorOnHand, reserveAllocation } from "@/lib/inventory/allocations.js";
+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 { createContentProvider } from "@/lib/content/storyblok/provider";
+import { createToTClient } from "@/lib/catalog/tot/ToTClient";
 export const prerender = false;
-
-const EVIDENCE_STATES = new Set(["fresh", "UNKNOWN", "stale", "unreadable", "absent"]);
-const STAGES = new Set(["preview", "publication"]);
-
+const HEX = /^[a-f0-9]{64}$/;
 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: number, owner?: string): Response {
-  return json(owner ? { ok: false, finding, owner } : { ok: false, finding }, status);
-}
-
-function statusFor(finding: string): number {
-  if (finding === "store-unconfigured" || finding === "caller-unconfigured") return 503;
-  if (
-    finding === "browser-not-authority" ||
-    finding === "tenant-unbound" ||
-    finding === "shared-secret" ||
-    finding === "signature" ||
-    finding === "kid" ||
-    finding === "issuer" ||
-    finding === "audience" ||
-    finding === "expired" ||
-    finding === "lifetime" ||
-    finding === "jti" ||
-    finding === "tenant" ||
-    finding === "stage"
-  ) {
-    return 401;
-  }
-  return 409;
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" } });
 }
-
-function claimString(payload: JWTPayload, key: string): string {
-  const value = payload[key];
-  return typeof value === "string" ? value : "";
-}
-
-function parseList(value: string | undefined): string[] | null {
-  if (!value || value.trim() === "") return null;
-  const trimmed = value.trim();
-  if (trimmed.startsWith("[")) {
-    try {
-      const parsed = JSON.parse(trimmed) as unknown;
-      if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string" || item.trim() === "")) return null;
-      return parsed as string[];
-    } catch {
-      return null;
-    }
-  }
-  const parts = trimmed.split(",").map((part) => part.trim()).filter(Boolean);
-  return parts.length > 0 ? parts : null;
+function deny(finding: string, status = 409, owner?: string): Response { return json({ ok: false, finding, ...(owner ? { owner } : {}) }, status); }
+function list(value: string | undefined): string[] | null {
+  if (!value) return null;
+  try {
+    const values: unknown = value.trim().startsWith("[") ? JSON.parse(value) : value.split(",").map(v => v.trim());
+    return Array.isArray(values) && values.length > 0 && values.every(v => typeof v === "string" && v.length > 0) ? values : null;
+  } catch { return null; }
 }
-
 function publicJwks(value: string | undefined): JSONWebKeySet | null {
-  if (!value) return null;
   try {
-    const parsed = JSON.parse(value) as unknown;
-    if (!parsed || typeof parsed !== "object" || !Array.isArray((parsed as { keys?: unknown }).keys)) return null;
-    const keys = (parsed as { keys: unknown[] }).keys;
-    if (keys.length < 1) return null;
-    for (const key of keys) {
-      if (!key || typeof key !== "object") return null;
-      const record = key as Record<string, unknown>;
-      if (typeof record.d === "string" || record.kty === "oct" || typeof record.k === "string") return null;
-    }
+    const parsed: unknown = JSON.parse(value ?? "");
+    if (!parsed || typeof parsed !== "object" || !("keys" in parsed) || !Array.isArray(parsed.keys) || parsed.keys.length < 1) return null;
+    if (parsed.keys.some(key => !key || typeof key !== "object" || "d" in key || "k" in key || key.kty !== "OKP" || key.crv !== "Ed25519")) return null;
     return parsed as JSONWebKeySet;
-  } catch {
-    return null;
-  }
+  } catch { return null; }
 }
-
-function readCart(value: unknown): FinalCartBinding | null {
-  if (!value || typeof value !== "object") return null;
-  const record = value as Record<string, unknown>;
-  if (typeof record.tenantId !== "string" || typeof record.currency !== "string" || typeof record.destinationDigest !== "string") {
-    return null;
-  }
-  if (typeof record.stage !== "string" || !STAGES.has(record.stage)) return null;
-  if (typeof record.verificationExpiresAt !== "string" || typeof record.taxExpiresAt !== "string") return null;
-  if (!Array.isArray(record.lines) || record.lines.length > 50) return null;
-  const lines = [];
-  for (const line of record.lines) {
-    if (!line || typeof line !== "object") return null;
-    const row = line as Record<string, unknown>;
-    if (typeof row.sku !== "string" || typeof row.quantity !== "number" || typeof row.unitMinor !== "number") return null;
-    lines.push({ sku: row.sku, quantity: row.quantity, unitMinor: row.unitMinor });
-  }
-  return {
-    tenantId: record.tenantId,
-    stage: record.stage as CommerceStage,
-    currency: record.currency,
-    lines,
-    destinationDigest: record.destinationDigest,
-    verificationExpiresAt: record.verificationExpiresAt,
-    taxExpiresAt: record.taxExpiresAt,
-  };
-}
-
-function readEvidence(value: unknown): CommerceEvidence | null {
-  if (!value || typeof value !== "object") return null;
-  const record = value as Record<string, unknown>;
-  const evidence = {} as CommerceEvidence;
-  for (const field of ["verification", "tax", "risk", "stock"] as const) {
-    const state = record[field];
-    if (typeof state !== "string" || !EVIDENCE_STATES.has(state)) return null;
-    evidence[field] = state as EvidenceState;
-  }
-  return evidence;
+async function digest(value: string): Promise<string> {
+  return [...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)))].map(b => b.toString(16).padStart(2, "0")).join("");
 }
-
-function readState<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
-  return typeof value === "string" && (allowed as readonly string[]).includes(value) ? (value as T) : undefined;
+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;
+  if ("expectedAuthorizationId" in v && (typeof v.expectedAuthorizationId !== "string" || !/^[a-z0-9][a-z0-9-]{0,80}$/.test(v.expectedAuthorizationId))) 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) ||
+      !Array.isArray(v.lines) || v.lines.length < 1 || v.lines.length > 50) return null;
+  if (v.lines.some(line => !line || typeof line !== "object" || typeof line.sku !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/.test(line.sku) ||
+      !Number.isSafeInteger(line.quantity) || line.quantity < 1 || line.quantity > 99 || !Number.isSafeInteger(line.unitMinor) || line.unitMinor < 0 ||
+      Object.keys(line).some(k => !["sku", "quantity", "unitMinor"].includes(k)))) return null;
+  if (!v.totals || typeof v.totals !== "object" || Object.keys(v.totals).length !== 4 ||
+      !["subtotalMinor", "shippingMinor", "taxMinor", "totalMinor"].every(k => Number.isSafeInteger((v.totals as Record<string, unknown>)[k]) && Number((v.totals as Record<string, unknown>)[k]) >= 0)) return null;
+  const d = v.destination as Record<string, unknown> | undefined;
+  if (!d || Object.keys(d).length !== 2 || typeof d.country !== "string" || !/^[A-Z]{2}$/.test(d.country) || typeof d.region !== "string" || !/^[A-Z0-9-]{1,8}$/.test(d.region)) return null;
+  const snapshot = v as unknown as CommerceProviderCartSnapshot;
+  if (new Set(snapshot.lines.map(line => line.sku)).size !== snapshot.lines.length) return null;
+  if (!totalsMatch(snapshot.totals) || snapshot.lines.reduce((sum, line) => sum + line.quantity * line.unitMinor, 0) !== snapshot.totals.subtotalMinor) return null;
+  return snapshot;
 }
-
-function destinationOf(value: unknown): { region: string; country: string } | null {
-  if (!value || typeof value !== "object") return null;
-  const record = value as Record<string, unknown>;
-  const region = typeof record.region === "string" ? record.region.trim() : "";
-  const country = typeof record.country === "string" ? record.country.trim() : "";
-  if (!/^[A-Za-z]{2}$/.test(region)) return null;
-  if (country !== "" && !/^[A-Za-z]{2}$/.test(country)) return null;
-  return { region: region.toUpperCase(), country: country === "" ? "US" : country.toUpperCase() };
-}
-
-async function catalogAvailableFor(skus: readonly string[]): Promise<boolean> {
-  if (skus.length === 0) return false;
-  const database = await readD1("CATALOG_DB");
-  if (!database) return false;
-  const wanted = new Set(skus);
-  try {
-    const products = await listAllActiveProducts(fromD1(database));
-    for (const product of products) {
-      for (const variant of product.variants) {
-        if (variant.sku === undefined) continue;
-        if (wanted.has(variant.sku) && variant.inventory.available === true) return true;
-      }
-    }
-  } catch {
-    return false;
-  }
-  return false;
-}
-
-async function verificationSeam(
-  context: APIContext,
-  cart: FinalCartBinding,
-  destination: { region: string; country: string } | null,
-): Promise<SeamView> {
-  const tot = (context.locals as { tot?: { getProductByHandle: (handle: string) => Promise<unknown> } }).tot ?? {
-    getProductByHandle: async () => null,
-  };
+async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot, products: readonly CatalogProduct[]): Promise<SeamView> {
   const response = await compliancePreflight({
-    request: new Request("https://synthetic-tenant.invalid/api/compliance/preflight", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        lines: cart.lines.map((line) => ({ handle: line.sku, sku: line.sku, quantity: line.quantity })),
-        ...(destination ? { destination: { region: destination.region, country: destination.country } } : {}),
-      }),
-    }),
-    locals: { tenant: context.locals.tenant, tot },
+    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);
-  let body: unknown;
   try {
-    body = await response.json();
-  } catch {
-    return { status: "absent" };
-  }
-  const decision = body && typeof body === "object" ? (body as { decision?: { status?: unknown; failedClosed?: unknown; blocks?: unknown } }).decision : undefined;
-  if (!decision || decision.status === "clear") return { status: decision ? "clear" : "absent" };
-  const blocks = Array.isArray(decision.blocks) ? decision.blocks : [];
-  const codes = blocks
-    .map((block) => (block && typeof block === "object" ? (block as { code?: unknown }).code : undefined))
-    .filter((code): code is string => typeof code === "string");
-  return { status: "blocked", failedClosed: decision.failedClosed === true, codes };
+    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" }; }
 }
-
 export async function POST(context: APIContext): Promise<Response> {
-  const tenant = context.locals.tenant as TenantConfig | undefined;
-  const appDomain = tenant?.appDomain ?? "";
-  if (!tenant || appDomain === "") return deny("tenant-unbound", 401);
-
-  let body: Record<string, unknown>;
-  try {
-    const parsed = await context.request.json();
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return deny("malformed-request", 409);
-    body = parsed as Record<string, unknown>;
-  } catch {
-    return deny("malformed-request", 409);
-  }
-
-  if (body.scheme === "shared-secret") return deny("shared-secret", statusFor("shared-secret"));
-
-  const quoted = readCart(body.quoted);
-  const presented = readCart(body.presented);
-  if (!quoted || !presented) return deny("malformed-request", 409);
-
-  const jwks = publicJwks(await readEnv("SCRAPPY_CALLER_JWKS"));
-  const issuers = parseList(await readEnv("SCRAPPY_CALLER_ISSUERS"));
-  const audience = await readEnv("SCRAPPY_CALLER_AUDIENCE");
-  const activeKids = parseList(await readEnv("SCRAPPY_CALLER_ACTIVE_KIDS"));
+  if (Number(context.request.headers.get("content-length") ?? 0) > 65536) return deny("malformed-request");
+  const raw = await context.request.text();
+  if (raw.length > 65536) return deny("malformed-request");
+  let snapshot: CommerceProviderCartSnapshot | null;
+  try { snapshot = readSnapshot(JSON.parse(raw)); } catch { snapshot = null; }
+  if (!snapshot) return deny("malformed-request");
+  const jwks = publicJwks(await readEnv("COMMERCE_CALLER_JWKS"));
+  const issuers = list(await readEnv("COMMERCE_CALLER_ISSUERS"));
+  const audience = await readEnv("COMMERCE_CALLER_AUDIENCE");
+  const activeKids = list(await readEnv("COMMERCE_CALLER_ACTIVE_KIDS"));
   if (!jwks || !issuers || !audience || !activeKids) return deny("caller-unconfigured", 503);
-
-  const header = context.request.headers.get("authorization") ?? "";
-  const bearer = header.startsWith("Bearer ") ? header.slice("Bearer ".length).trim() : "";
-  let token: CallerToken | null = null;
-  if (bearer !== "") {
-    try {
-      const decoded = decodeJwt(bearer);
-      const protectedHeader = decodeProtectedHeader(bearer);
-      let signatureValid = false;
-      try {
-        await jwtVerify(bearer, createLocalJWKSet(jwks), { algorithms: ["EdDSA"] });
-        signatureValid = true;
-      } catch (error) {
-        const code = error && typeof error === "object" && "code" in error ? String((error as { code: unknown }).code) : "";
-        signatureValid = code === "ERR_JWT_EXPIRED" || code === "ERR_JWT_CLAIM_VALIDATION_FAILED";
-      }
-      const exp = typeof decoded.exp === "number" ? new Date(decoded.exp * 1000).toISOString() : "";
-      const audienceClaim = typeof decoded.aud === "string" ? decoded.aud : Array.isArray(decoded.aud) ? decoded.aud[0] ?? "" : "";
-      const stageClaim = claimString(decoded, "stage");
-      if (stageClaim !== "preview" && stageClaim !== "publication") return deny("stage", statusFor("stage"));
-      token = {
-        scheme: "asymmetric-jwks",
-        signatureValid,
-        kid: typeof protectedHeader.kid === "string" ? protectedHeader.kid : "",
-        issuer: typeof decoded.iss === "string" ? decoded.iss : "",
-        audience: audienceClaim,
-        expiresAt: exp,
-        jti: claimString(decoded, "jti"),
-        tenantId: claimString(decoded, "tenantId"),
-        stage: stageClaim,
-      };
-    } catch {
-      token = null;
-    }
+  const bearer = context.request.headers.get("authorization")?.replace(/^Bearer /, "") ?? "";
+  let token: CallerToken;
+  try {
+    const header = decodeProtectedHeader(bearer);
+    if (!header.kid || !activeKids.includes(header.kid)) return deny("kid", 401);
+    const { payload } = await jwtVerify(bearer, createLocalJWKSet(jwks), { algorithms: ["EdDSA"], issuer: issuers, audience });
+    if (payload.requestDigest !== await digest(raw)) return deny("request-digest", 401);
+    if (payload.tenantId !== snapshot.tenantId || payload.stage !== snapshot.stage) return deny("tenant", 401);
+    if (typeof payload.exp !== "number") return deny("expired", 401);
+    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 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 });
+  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); }
+  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 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 provider = tenant.inventory?.provider ?? "mirror";
-  const authorities: unknown[] = [];
+  const database = await readD1("STOREFRONT_APPS_DB");
+  if (!database) return deny("store-unconfigured", 503);
+  if (tenant.inventory?.provider && tenant.inventory.provider !== "mirror") return deny("authority-unavailable");
   const now = new Date().toISOString();
-  if (provider !== "mirror") {
-    authorities.push({ provider, sku: presented.lines[0]?.sku });
-  } else {
-    const skus = [...new Set(presented.lines.map((line) => line.sku))];
-    for (const sku of skus) {
-      const onHand = mirrorOnHand(sku, "unspecified");
-      authorities.push(
-        onHand == null
-          ? null
-          : { provider: "mirror", readable: true, locationId: "unspecified", sku, onHand, asOf: now },
-      );
+  const queryable = fromD1(database);
+  const prior = await queryable.first<{ authorization_id: string; state: string }>(
+    `SELECT s.authorization_id,a.state FROM commerce_admission_snapshots s JOIN scrappy_final_cart_authorizations a
+     ON a.tenant_id=s.tenant_id AND a.stage=s.stage AND a.authorization_id=s.authorization_id
+     JOIN commerce_provider_carts p ON p.tenant_id=s.tenant_id AND p.stage=s.stage AND p.authorization_id=s.authorization_id
+     WHERE p.tenant_id=? AND p.stage=? AND p.provider='foxycart' AND p.provider_cart_id=?`,
+    snapshot.tenantId, snapshot.stage, snapshot.providerCartId,
+  );
+  if (snapshot.expectedAuthorizationId && snapshot.expectedAuthorizationId !== prior?.authorization_id) return deny("provider-cart-conflict");
+  if (prior && prior.state !== "active") return deny("admission-consumed");
+  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 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 provenance = {} as CommerceEvidenceProvenance;
+  for (const field of ["verification", "tax", "risk"] as const) {
+    if (testPolicy && policy.requirements?.[field] === "not-required") {
+      evidence[field] = "not-required";
+      provenance[field] = { requirement: "not-required", state: "not-required", source: "declared-synthetic-policy", policyRevision: policy.revision, expiresAt };
     }
   }
-  const catalogAvailable = await catalogAvailableFor(presented.lines.map((line) => line.sku));
-
-  const decision = await evaluateFinalCart({
-    now,
-    routedTenantId: appDomain,
-    quoted,
-    presented,
-    evidence: readEvidence(body.evidence),
-    seam: await verificationSeam(context, presented, destinationOf(body.destination)),
-    catalogAvailable,
-    browserConfirmed: body.browserConfirmed === true,
-    token,
-    trustedIssuers: issuers,
-    expectedAudience: audience,
-    activeKids,
-    authorities,
-    payment: readState<PaymentState>(body.payment, ["UNKNOWN", "pending", "authorized", "captured", "capture_unknown", "voided", "refund_requested", "refunded", "refund_unknown"]),
-    stock: readState<StockState>(body.stock, ["UNKNOWN", "unallocated", "reserved", "confirmed", "released", "expired"]),
-    fulfillment: readState<FulfillmentState>(body.fulfillment, ["UNKNOWN", "held", "ready", "handed_off", "cancelled"]),
-    label: readState<LabelState>(body.label, ["UNKNOWN", "none", "intent", "purchased", "printed", "void_requested", "voided"]),
-  });
-  if (!decision.ok) return deny(decision.finding, statusFor(decision.finding), decision.owner);
-
-  const database = await readD1("STOREFRONT_APPS_DB");
-  if (!database || typeof database.prepare !== "function") return deny("store-unconfigured", 503);
-  const reserved = await reserveAllocation(d1CommerceRunner(database), {
-    tenantId: decision.tenantId,
-    stage: decision.stage,
-    orderId: `a${crypto.randomUUID()}`,
-    cartDigest: decision.digest,
-    expiresAt: decision.expiresAt,
-    now,
-    currency: presented.currency,
-    amountMinor: decision.amountMinor,
-    issuer: decision.issuer,
-    jti: decision.jti,
-    holds: decision.holds,
-  });
-  if (!reserved.ok) return deny(reserved.finding, statusFor(reserved.finding));
-  return json({
-    ok: true,
-    authorizationId: reserved.authorizationId,
-    cartDigest: decision.digest,
-    expiresAt: reserved.expiresAt,
-    repeated: reserved.repeated,
-    stage: decision.stage,
+  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 decision = await evaluateFinalCart({ now, routedTenantId: commerceTenantId(tenant), quoted: presented, presented, evidence,
+    seam: await seam(authorityContext, snapshot, products), catalogAvailable: true, browserConfirmed: false, token,
+    trustedIssuers: issuers, expectedAudience: audience, activeKids, authorities });
+  if (!decision.ok) 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}`);
+  const reserved = await reserveAllocation(d1CommerceRunner(database), { tenantId: decision.tenantId, stage: decision.stage, orderId: authorizationId,
+    cartDigest, expiresAt: decision.expiresAt, now, currency: snapshot.currency, amountMinor: snapshot.totals.totalMinor,
+    issuer: decision.issuer, jti: decision.jti, holds: decision.holds,
+    providerCart: { provider: snapshot.provider, id: snapshot.providerCartId, digest: snapshot.providerCartDigest, expectedAuthorizationId: snapshot.expectedAuthorizationId },
+    admissionStatement: admissionSnapshotStatement({ ...snapshot, authorizationId, cartDigest, evidence, provenance, expiresAt: decision.expiresAt, now }),
   });
+  if (!reserved.ok) return deny(reserved.finding);
+  return json({ ok: true, authorizationId: reserved.authorizationId, cartDigest, expiresAt: reserved.expiresAt, repeated: reserved.repeated, stage: snapshot.stage });
 }
-

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

@@ -22,6 +22,9 @@ import ReviewList from "@/components/catalog/storefront/commerce/ReviewList.astr
 import { isOnSale, isNew, isAvailable, fromPrice } from "@/lib/catalog/tot/query";
 import {
   buildMemberSignedCartPayload,
+  commerceTenantId,
+  SAMPLE_CART_HANDOFF_URL,
+  sampleVariantCartPayload,
   workerCartApiPath,
   normalizePurchaseOptions,
   visiblePurchaseOptions,
@@ -39,6 +42,7 @@ import type {
   PurchaseOptionPricingContext,
 } from "@tot/public-runtime";
 import { resolveCartSigning, shopperCheckoutUnavailableHtml } from "@/lib/checkout/shared/checkoutCommerce";
+import { isLocalSampleCheckout } from "@/config/declaredTenantConfig";
 import { isRegulatedTenant } from "@/lib/compliance/enforcement";
 import { resolveMemberContext } from "@/lib/membership/eligibility";
 import { truncate } from "@/lib/content/shared/format";
@@ -233,11 +237,12 @@ let checkoutCart:
     }
   | undefined;
 let checkoutUnavailable = false;
-if (commerce) {
+const sampleHandoff = isLocalSampleCheckout(tenant.tenant_id);
+if (commerce || sampleHandoff) {
   // Fail closed for production signed checkout: a signed tenant with no
   // cart-validation secret builds NO cart (never a tamperable form). See
   // resolveCartSigning — it also logs the misconfiguration loudly.
-  const signing = await resolveCartSigning(commerce);
+  const signing = sampleHandoff ? { enabled: true, secret: undefined } : await resolveCartSigning(commerce!);
   if (!signing.enabled) {
     checkoutUnavailable = true;
   } else {
@@ -253,13 +258,13 @@ if (commerce) {
               purchaseOptions.map(async (purchaseOption) => {
                 return [
                   purchaseOption.id,
-                  await buildMemberSignedCartPayload(product, v, {
-                    mode: commerce.mode,
+                  sampleHandoff ? sampleVariantCartPayload(product.handle, v.id) : await buildMemberSignedCartPayload(product, v, {
+                    mode: commerce!.mode,
                     secret: signing.secret,
                     purchaseOption,
                     pricing: pricingCtx,
                     autopilotEnabled,
-                    tenantId: tenant.tenant_id,
+                    tenantId: commerceTenantId(tenant),
                   }),
                 ] as const;
               }),
@@ -269,7 +274,7 @@ if (commerce) {
         ),
       );
       checkoutCart = {
-        action: cartApiPath,
+        action: sampleHandoff ? SAMPLE_CART_HANDOFF_URL : cartApiPath,
         purchaseOptions,
         byVariantId: Object.fromEntries(entries),
       };
@@ -415,13 +420,13 @@ const structuredData = {
           productTitle={product.title}
           checkoutCart={checkoutCart}
           pricing={pricing}
-          handoffUrl={cartApiPath}
+          handoffUrl={sampleHandoff ? undefined : cartApiPath}
         />
         {/* Regulated-tenant checkout ENFORCEMENT gate. Intercepts the
             managed-cart handoff to clear age + ship-to compliance server-side
             before the external checkout. Only mounts when a store is wired AND
             the tenant is regulated. */}
-        {checkoutCart && isRegulatedTenant(tenant) && compliance?.minAge && (
+        {checkoutCart && !sampleHandoff && isRegulatedTenant(tenant) && compliance?.minAge && (
           <CheckoutComplianceGate
             client:load
             preflightUrl={withBase(apiBasePath, "/api/compliance/preflight")}

package/apps/storefront/test/pipeline/harness.ts

@@ -22,6 +22,12 @@ interface HarnessEnv {
 
 type TenantPipelineStub = {
   [K in
+    | "holdCommerce"
+    | "resumeCommerce"
+    | "commerceRaceReceive"
+    | "commerceRaceWakeups"
+    | "scheduleCommerce"
+    | "commerceRuns"
     | "submit"
     | "deliverExternal"
     | "job"

package/apps/storefront/test/pipeline/pipeline-host.ts

@@ -80,6 +80,35 @@ function harnessSeedServices(
 const matrices = new WeakMap<DurableObjectState, { faults: MatrixFaults; registry: JobKindRegistry }>();
 
 export class TenantPipeline extends DeployedTenantPipeline {
+  private commercePaused = false;
+  private commerceResume: (() => void) | null = null;
+  private commerceOutcome: string = "complete";
+  async holdCommerce(outcome = "complete"): Promise<void> { this.commercePaused = true; this.commerceOutcome = outcome; }
+  async resumeCommerce(): Promise<void> {
+    this.commercePaused = false; this.commerceOutcome = "complete";
+    this.commerceResume?.(); this.commerceResume = null;
+  }
+  async commerceRaceReceive(tenantId: string): Promise<void> {
+    return this.ctx.blockConcurrencyWhile(async () => { await this.scheduleCommerce(tenantId, Date.now() + 2000); });
+  }
+  async commerceRaceWakeups(): Promise<number> {
+    return [...this.ctx.storage.sql.exec<{count:number}>(`SELECT COUNT(*) count FROM commerce_wakeup`)][0]?.count ?? 0;
+  }
+
+  protected override async runCommerce(tenantId:string,_now:string):Promise<number|null> {
+    this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS commerce_probe(tenant_id TEXT PRIMARY KEY,runs INTEGER NOT NULL)`);
+    this.ctx.storage.sql.exec(`INSERT INTO commerce_probe VALUES(?,1) ON CONFLICT(tenant_id) DO UPDATE SET runs=runs+1`,tenantId);
+    const outcome = this.commerceOutcome;
+    if (this.commercePaused) await new Promise<void>(resolve => { this.commerceResume = resolve; });
+    if (outcome === "error") throw new Error("delivery-unavailable");
+    if (outcome === "retry") return Date.now() + 60_000;
+    return null;
+  }
+  async commerceRuns():Promise<number> {
+    this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS commerce_probe(tenant_id TEXT PRIMARY KEY,runs INTEGER NOT NULL)`);
+    return [...this.ctx.storage.sql.exec<{runs:number}>(`SELECT SUM(runs) runs FROM commerce_probe`)][0]?.runs ?? 0;
+  }
+
   protected override jobKinds(ctx: DurableObjectState): JobKindRegistry {
     const faults = new MatrixFaults(ctx, () => publishWorldOf(ctx).kv);
     const services = previewServicesWithEffects(fakePreviewServices(ctx, faults.landed), faults.landed);