@tokenoftrust/storefront-runner 2.4.48 → 2.4.50

package/apps/storefront/migrations-apps/0016_scrappy_commerce_contract.sql

@@ -0,0 +1,166 @@
+-- Commerce orders, inbox/outbox, allocations, label purchases, and shipment audit.
+-- Tenant and stage are on every row. Money is integer minor units.
+-- The SQL directory is the apply set. One transaction per file.
+CREATE TABLE `scrappy_commerce_orders` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `source` text NOT NULL,
+  `source_order_id` text NOT NULL,
+  `currency` text NOT NULL,
+  `placed_at` text NOT NULL,
+  `payment_state` text NOT NULL CHECK (payment_state IN ('UNKNOWN', 'pending', 'authorized', 'captured', 'capture_unknown', 'voided', 'refund_requested', 'refunded', 'refund_unknown')),
+  `compliance_state` text NOT NULL CHECK (compliance_state IN ('UNKNOWN', 'pending', 'fresh', 'stale', 'unreadable', 'refused')),
+  `stock_state` text NOT NULL CHECK (stock_state IN ('UNKNOWN', 'unallocated', 'reserved', 'confirmed', 'released', 'expired')),
+  `fulfillment_state` text NOT NULL CHECK (fulfillment_state IN ('UNKNOWN', 'held', 'ready', 'handed_off', 'cancelled')),
+  `label_state` text NOT NULL CHECK (label_state IN ('UNKNOWN', 'none', 'intent', 'purchased', 'printed', 'void_requested', 'voided')),
+  `amount_minor` integer NOT NULL CHECK (amount_minor >= 0),
+  `event_version` integer NOT NULL CHECK (event_version >= 1),
+  PRIMARY KEY (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_scrappy_commerce_source_order`
+  ON `scrappy_commerce_orders` (`tenant_id`, `stage`, `source`, `source_order_id`);
+--> statement-breakpoint
+CREATE TABLE `scrappy_order_addresses` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `address_json` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`, `order_id`),
+  FOREIGN KEY (`tenant_id`, `stage`, `order_id`) REFERENCES `scrappy_commerce_orders` (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE TABLE `scrappy_commerce_inbox` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `source` text NOT NULL,
+  `source_event_id` text NOT NULL,
+  `event_version` integer NOT NULL CHECK (event_version >= 1),
+  `idempotency_key` text NOT NULL,
+  `payload_digest` text NOT NULL,
+  `received_at` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`, `source`, `source_event_id`)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_scrappy_inbox_idempotency`
+  ON `scrappy_commerce_inbox` (`tenant_id`, `stage`, `idempotency_key`);
+--> statement-breakpoint
+CREATE TABLE `scrappy_commerce_outbox` (
+  `outbox_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `source` text NOT NULL,
+  `source_event_id` text NOT NULL,
+  `event_version` integer NOT NULL CHECK (event_version >= 1),
+  `event_type` text NOT NULL,
+  `payload` text NOT NULL,
+  `available_at` text NOT NULL,
+  `attempt_count` integer NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  `state` text NOT NULL CHECK (state IN ('pending', 'delivered', 'dead')),
+  PRIMARY KEY (`outbox_id`),
+  UNIQUE (`tenant_id`, `stage`, `source`, `source_event_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_scrappy_outbox_due`
+  ON `scrappy_commerce_outbox` (`state`, `available_at`);
+--> statement-breakpoint
+CREATE TABLE `scrappy_allocations` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `sku` text NOT NULL,
+  `location_id` text NOT NULL,
+  `quantity` integer NOT NULL CHECK (quantity > 0),
+  `state` text NOT NULL CHECK (state IN ('reserved', 'confirmed', 'released', 'expired')),
+  PRIMARY KEY (`tenant_id`, `stage`, `order_id`, `sku`, `location_id`),
+  FOREIGN KEY (`tenant_id`, `stage`, `order_id`) REFERENCES `scrappy_commerce_orders` (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE TABLE `scrappy_final_cart_authorizations` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `authorization_id` text NOT NULL,
+  `cart_digest` text NOT NULL,
+  `expires_at` text NOT NULL,
+  `state` text NOT NULL CHECK (state IN ('active', 'consumed', 'expired', 'denied')),
+  PRIMARY KEY (`tenant_id`, `stage`, `authorization_id`)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_scrappy_active_final_cart`
+  ON `scrappy_final_cart_authorizations` (`tenant_id`, `stage`, `cart_digest`)
+  WHERE `state` = 'active';
+--> statement-breakpoint
+CREATE TABLE `scrappy_provider_operations` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `provider` text NOT NULL,
+  `purchase_id` text NOT NULL,
+  `order_id` text NOT NULL,
+  `kind` text NOT NULL CHECK (kind IN ('label_purchase', 'payment_capture', 'refund')),
+  `outcome` text NOT NULL CHECK (outcome IN ('intent', 'accepted', 'unknown', 'voided', 'refunded')),
+  `amount_minor` integer NOT NULL CHECK (amount_minor >= 0),
+  PRIMARY KEY (`tenant_id`, `stage`, `provider`, `purchase_id`),
+  FOREIGN KEY (`tenant_id`, `stage`, `order_id`) REFERENCES `scrappy_commerce_orders` (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_scrappy_open_label_purchase`
+  ON `scrappy_provider_operations` (`tenant_id`, `stage`, `order_id`)
+  WHERE `kind` = 'label_purchase' AND `outcome` IN ('intent', 'accepted', 'unknown');
+--> statement-breakpoint
+CREATE TABLE `scrappy_shipments` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `scope` text NOT NULL CHECK (scope = 'whole-order'),
+  `label_purchase_state` text NOT NULL CHECK (label_purchase_state IN ('none', 'intent', 'purchased', 'void_requested', 'voided', 'unknown')),
+  `label_print_state` text NOT NULL CHECK (label_print_state IN ('none', 'printed')),
+  `handoff_state` text NOT NULL CHECK (handoff_state IN ('none', 'handed_off', 'unknown')),
+  CHECK (handoff_state = 'none' OR label_purchase_state = 'purchased'),
+  CHECK (label_print_state = 'none' OR label_purchase_state = 'purchased'),
+  PRIMARY KEY (`tenant_id`, `stage`, `order_id`),
+  FOREIGN KEY (`tenant_id`, `stage`, `order_id`) REFERENCES `scrappy_commerce_orders` (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE TABLE `scrappy_shipment_audit` (
+  `audit_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `at` text NOT NULL,
+  `actor_id` text NOT NULL,
+  `kind` text NOT NULL,
+  `from_state` text NOT NULL,
+  `to_state` text NOT NULL,
+  PRIMARY KEY (`audit_id`),
+  FOREIGN KEY (`tenant_id`, `stage`, `order_id`) REFERENCES `scrappy_commerce_orders` (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE TRIGGER `scrappy_shipment_audit_no_update`
+BEFORE UPDATE ON `scrappy_shipment_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `scrappy_shipment_audit_no_delete`
+BEFORE DELETE ON `scrappy_shipment_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TABLE `scrappy_caller_replay` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `issuer` text NOT NULL,
+  `jti` text NOT NULL,
+  `seen_at` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`, `issuer`, `jti`)
+);
+--> statement-breakpoint
+CREATE TABLE `scrappy_sweep_cursor` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `cursor` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`)
+);

package/apps/storefront/src/components/islands/CheckoutComplianceGate.tsx

@@ -1,15 +1,11 @@
 /**
- * <CheckoutComplianceGate> — the storefront's pre-handoff compliance ENFORCEMENT
- * seam for regulated (age/nicotine) tenants.
+ * <CheckoutComplianceGate> — browser preflight for a regulated add-to-cart submit.
  *
- * Checkout completion happens in the EXTERNAL managed cart, so the last moment the
- * storefront controls is the add-to-cart submit. This island intercepts that
- * submit for any `form[data-managed-cart]`, collects the ship-to state + 21+
- * affirmation, and asks the server-authoritative gate (`/api/compliance/preflight`,
- * F12) whether the cart may proceed. Only a `clear` decision releases the handoff;
- * a hard block (restricted destination, flavored ban, per-order limit, failed /
- * unconfigured verification) STOPS it and shows why. Fail-closed by construction:
- * if the preflight itself errors on a regulated tenant, we do NOT hand off.
+ * The dialog collects the ship-to state and the age affirmation, then asks
+ * `/api/compliance/preflight` whether this browser may submit the form. Only a
+ * server `clear` releases that submit. A hard block (restricted destination,
+ * flavored ban, per-order limit, failed or unconfigured verification) stops it.
+ * If the preflight cannot be read, the dialog does not submit.
  *
  * On a tenant wired to the LIVE Token of Trust verification provider, preflight
  * additionally echoes a `verification` block (ref / provider status / continuation
@@ -18,15 +14,13 @@
  * continuation URL in a new tab, then re-read the SERVER's decision on an interval
  * until it clears or denies. Sandbox / no-provider tenants never receive the block
  * and see exactly the flow they always did. The client never decides a pass:
- * `decision.status === "clear"` from the server is the only thing that releases the
- * handoff, here as everywhere else. See `checkoutVerificationFlow.ts`.
+ * `decision.status === "clear"` from the server is the only thing that releases
+ * the submit. See `checkoutVerificationFlow.ts`.
  *
- * This is progressive enhancement: the underlying form still posts the real
- * (server-pre-signed) cart fields. If this island never hydrates, the form submits
- * as before — so the gate hardens the flow without being a single point of failure
- * for rendering the buy button. The REAL production enforcement is defense-in-depth
- * in the managed-cart pre-cart webhook (Track B); this is the storefront-side check
- * and the demo/preview's visible compliance checkpoint.
+ * This preflight is browser UX. It is not payment authorization. A `clear`
+ * decision only lets the native form submit; the server checks the cart again
+ * and never treats this dialog as authority to take payment. If the island
+ * never hydrates, or scripts are disabled, the form posts on its own.
  */
 import { useCallback, useEffect, useRef, useState } from "preact/hooks";
 import type { CartComplianceDecision } from "@tot/public-runtime";
@@ -177,11 +171,12 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
   const proceed = useCallback((line: PendingLine) => {
     stopPolling();
     clearStoredRef(verificationRefKey(preflightUrl, line));
+    // UX latch so this dialog does not intercept the resubmit. Not payment
+    // authority — the form's server action checks the cart.
     line.form.dataset.complianceCleared = "1";
+    line.form.dataset.paymentAuthority = "none";
     document.documentElement.style.overflow = "";
     setPending(null);
-    // requestSubmit re-runs submit; our listener now passes it through, and the
-    // managed-cart loader takes over the (still server-pre-signed) POST.
     if (typeof line.form.requestSubmit === "function") line.form.requestSubmit();
     else line.form.submit();
   }, [preflightUrl, stopPolling]);
@@ -377,6 +372,7 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
     <div
       class="fixed inset-0 z-[110] bg-[color-mix(in_srgb,var(--color-text)_75%,transparent)] backdrop-blur-sm"
       role="dialog"
+      data-payment-authority="none"
       aria-modal="true"
       aria-labelledby="cgate-title"
       onClick={(e) => {

package/apps/storefront/src/lib/checkoutCommerce.ts

@@ -24,7 +24,11 @@
  * wins; this only fills in when `commerce.checkout` is absent.
  */
 import type { TenantConfig, ResolvedManagedCheckout } from "@tot/public-runtime";
-import { resolveManagedCheckout, SHARED_DEMO_CHECKOUT } from "@tot/public-runtime";
+import {
+  CART_SIGNING_OPERATOR_ERROR,
+  resolveManagedCheckout,
+  SHARED_DEMO_CHECKOUT,
+} from "@tot/public-runtime";
 import { readEnv } from "@/lib/runtimeEnv";
 
 /**
@@ -86,6 +90,8 @@ export async function readCartSecret(
 export interface CartSigningResolution {
   enabled: boolean;
   secret?: string;
+  /** Set when signed mode has no secret. Actionable for the operator. No secret value. */
+  operatorError?: string;
 }
 
 /**
@@ -108,5 +114,5 @@ export async function resolveCartSigning(
     "[storefront] signed checkout is configured but FOXY_CART_SECRET is missing — " +
       "buy forms disabled (fail-closed). Set the cart-validation secret for this environment.",
   );
-  return { enabled: false };
+  return { enabled: false, operatorError: CART_SIGNING_OPERATOR_ERROR };
 }

package/apps/storefront/src/pages/api/commerce/checkout-handoff.ts

@@ -18,8 +18,15 @@
  *     unattributed response; the handoff proceeds, checkout is never blocked.
  */
 import type { APIContext } from "astro";
-import { parseConsentSnapshot, defaultConsentSnapshot } from "@tot/public-runtime";
+import {
+  enforceCartSubmission,
+  foxyCartRedirectUrl,
+  parseConsentSnapshot,
+  defaultConsentSnapshot,
+  type CartDenialCode,
+} from "@tot/public-runtime";
 import { resolveCheckoutHandoffCorrelation } from "@/lib/commerce/checkoutHandoffCorrelation";
+import { resolveCartSigning } from "@/lib/checkoutCommerce";
 
 export const prerender = false;
 
@@ -38,7 +45,78 @@ interface HandoffBody {
   consent?: unknown;
 }
 
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (ch) => {
+    if (ch === "&") return "&amp;";
+    if (ch === "<") return "&lt;";
+    if (ch === ">") return "&gt;";
+    if (ch === '"') return "&quot;";
+    return "&#39;";
+  });
+}
+
+function cartDenial(code: CartDenialCode, message: string, status: number): Response {
+  const body =
+    `<!doctype html><html><body><p data-cart-denial="${code}" data-payment-authorized="false">${escapeHtml(message)}</p></body></html>`;
+  return new Response(body, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "x-tot-payment-authorized": "false",
+    },
+  });
+}
+
+function isCartForm(request: Request): boolean {
+  const type = request.headers.get("content-type") ?? "";
+  return (
+    type.includes("application/x-www-form-urlencoded") ||
+    type.includes("multipart/form-data")
+  );
+}
+
+/** Native cart POST. Browser preflight is not consulted. Payment is never authorized. */
+async function cartFormPost(context: APIContext): Promise<Response> {
+  const { tenant, commerce } = context.locals;
+  if (!commerce) {
+    return cartDenial(
+      "signing-unavailable",
+      "Checkout is unavailable because this store has no cart configured.",
+      409,
+    );
+  }
+  const signing = await resolveCartSigning(commerce);
+  if (!signing.enabled) {
+    return cartDenial("signing-unavailable", signing.operatorError ?? "Signed checkout is unavailable.", 503);
+  }
+  const form = await context.request.formData();
+  const entries: Array<[string, string]> = [];
+  for (const [name, value] of form.entries()) {
+    if (typeof value === "string") entries.push([name, value]);
+  }
+  const result = await enforceCartSubmission({
+    entries,
+    mode: commerce.mode,
+    secret: signing.secret,
+    trustedTenantId: tenant.tenant_id,
+  });
+  if (!result.ok) {
+    const status = result.code === "signing-unavailable" ? 503 : 422;
+    return cartDenial(result.code, result.message, status);
+  }
+  return new Response(null, {
+    status: 303,
+    headers: {
+      location: foxyCartRedirectUrl(commerce.cartUrl, result.fields),
+      "cache-control": "no-store",
+      "x-tot-payment-authorized": "false",
+    },
+  });
+}
+
 export async function POST(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.

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

@@ -21,7 +21,9 @@ import ReviewSummary from "@/components/commerce/ReviewSummary.astro";
 import ReviewList from "@/components/commerce/ReviewList.astro";
 import { isOnSale, isNew, isAvailable, fromPrice } from "@/lib/tot/query";
 import {
-  buildMemberSignedCartPayload,
+  buildVariantCartPayload,
+  priceForPurchaseOption,
+  workerCartApiPath,
   normalizePurchaseOptions,
   visiblePurchaseOptions,
   isAutopilotEnabled,
@@ -208,6 +210,13 @@ const autopilotEnabled = isAutopilotEnabled(tenant.commerce?.autopilot);
 // list/subscription price; a Phase-2 member request signs their member price.
 const pricingCtx: PurchaseOptionPricingContext = { member, program: membershipProgram };
 
+const cartApiPath = workerCartApiPath({
+  provider: tenant.serving?.provider ?? "worker-r2-pointer",
+  phase: Astro.locals.browserEnvironment.environment === "live" ? "publication" : "preview",
+  apiBasePath,
+  endpoint: "/api/commerce/checkout-handoff",
+});
+
 let checkoutCart:
   | {
       action: string;
@@ -215,12 +224,15 @@ let checkoutCart:
       byVariantId: Record<string, Record<string, VariantCartPayload>>;
     }
   | undefined;
+let cartOperatorError: string | undefined;
 if (commerce) {
   // 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 { enabled, secret } = await resolveCartSigning(commerce);
-  if (enabled) {
+  const signing = await resolveCartSigning(commerce);
+  if (!signing.enabled) {
+    cartOperatorError = signing.operatorError;
+  } else {
     try {
       const purchaseOptions = visiblePurchaseOptions(
         normalizePurchaseOptions(product),
@@ -230,33 +242,41 @@ if (commerce) {
         product.variants.map(
           async (v) => {
             const payloads = await Promise.all(
-              purchaseOptions.map(
-                async (purchaseOption) =>
-                  [
-                    purchaseOption.id,
-                    await buildMemberSignedCartPayload(product, v, {
-                      mode: commerce.mode,
-                      secret,
-                      purchaseOption,
-                      pricing: pricingCtx,
-                      autopilotEnabled,
-                    }),
-                  ] as const,
-              ),
+              purchaseOptions.map(async (purchaseOption) => {
+                const effective = priceForPurchaseOption(
+                  v.price,
+                  purchaseOption,
+                  pricingCtx,
+                );
+                return [
+                  purchaseOption.id,
+                  await buildVariantCartPayload(product, v, {
+                    mode: commerce.mode,
+                    secret: signing.secret,
+                    purchaseOption,
+                    signedPrice: effective.price,
+                    autopilotEnabled,
+                    tenantId: tenant.tenant_id,
+                  }),
+                ] as const;
+              }),
             );
             return [v.id, Object.fromEntries(payloads)] as const;
           },
         ),
       );
       checkoutCart = {
-        action: commerce.cartUrl,
+        action: cartApiPath,
         purchaseOptions,
         byVariantId: Object.fromEntries(entries),
       };
     } catch (err) {
+      cartOperatorError =
+        err instanceof Error && err.name === "CartSigningUnavailableError"
+          ? err.message
+          : undefined;
       console.warn(
         `[storefront] Invalid checkout purchase options for ${product.handle}; cart disabled for this product.`,
-        err,
       );
     }
   }
@@ -368,8 +388,15 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
         </div>
       )}
 
-      {/* Variant selector island owns live price/SKU/availability + buy CTA. */}
-      <div class="mt-7">
+      {/* Variant selector island owns live price/SKU/availability + buy CTA.
+          The form action is the worker cart route, so a native submit reaches
+          the server check. A clear browser preflight is not payment authority. */}
+      <div class="mt-7" data-payment-authority="none">
+        {cartOperatorError && (
+          <p class="mb-3 text-sm text-[var(--color-text)]" role="alert" data-cart-operator-error>
+            {cartOperatorError}
+          </p>
+        )}
         <VariantSelector
           client:load
           variants={publicSelectorVariants(product.variants)}
@@ -380,7 +407,7 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
           productTitle={product.title}
           checkoutCart={checkoutCart}
           pricing={pricing}
-          handoffUrl={withBase(apiBasePath, "/api/commerce/checkout-handoff")}
+          handoffUrl={cartApiPath}
         />
         {/* Regulated-tenant checkout ENFORCEMENT gate. Intercepts the
             managed-cart handoff to clear age + ship-to compliance server-side

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.48",
+  "version": "2.4.50",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",