@tokenoftrust/storefront-runner 2.4.49 → 2.4.51

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/lib/commerce/finalCartAuthorization.ts

@@ -0,0 +1,234 @@
+/**
+ * Final-cart authorization decision. Payment is admitted only when the caller
+ * token, the bound cart, fresh evidence, the verification seam, and mirror stock
+ * all agree. Catalog availability and a browser confirmation are not authority.
+ */
+import {
+  admitCallerToken,
+  assertMinor,
+  decideCommerceCommand,
+  finalCartDigest,
+  finalCartStillBound,
+  sumMinor,
+  type CallerToken,
+  type CommerceEvidence,
+  type CommerceStage,
+  type EvidenceState,
+  type FinalCartBinding,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type StockState,
+} from "@tot/public-runtime";
+import { readMirrorAuthority, VERIFICATION_PROVIDER_OWNER, type ReserveHold } from "@/lib/inventory/allocations.js";
+
+export interface SeamView {
+  status: "clear" | "absent" | "blocked";
+  failedClosed?: boolean;
+  codes?: readonly string[];
+}
+
+export interface FinalCartRequest {
+  now: string;
+  routedTenantId: string;
+  quoted: FinalCartBinding;
+  presented: FinalCartBinding;
+  evidence: CommerceEvidence | null;
+  seam: SeamView | null;
+  catalogAvailable: boolean;
+  browserConfirmed: boolean;
+  token: CallerToken | null;
+  trustedIssuers: readonly string[];
+  expectedAudience: string;
+  activeKids: readonly string[];
+  authorities: readonly unknown[];
+  payment?: PaymentState;
+  stock?: StockState;
+  fulfillment?: FulfillmentState;
+  label?: LabelState;
+}
+
+export type FinalCartDecision =
+  | {
+      ok: true;
+      digest: string;
+      expiresAt: string;
+      amountMinor: number;
+      holds: ReserveHold[];
+      issuer: string;
+      jti: string;
+      tenantId: string;
+      stage: CommerceStage;
+    }
+  | { ok: false; finding: string; owner?: string };
+
+const EVIDENCE_FIELDS = ["verification", "tax", "risk", "stock"] as const;
+
+function sortedLines(cart: FinalCartBinding) {
+  return [...cart.lines].sort(
+    (left, right) => left.sku.localeCompare(right.sku) || left.unitMinor - right.unitMinor || left.quantity - right.quantity,
+  );
+}
+
+function cartFinding(quoted: FinalCartBinding, presented: FinalCartBinding, routedTenantId: string): string | null {
+  if (quoted.tenantId !== routedTenantId || presented.tenantId !== routedTenantId || quoted.tenantId !== presented.tenantId) {
+    return "tenant-changed";
+  }
+  if (quoted.stage !== presented.stage) return "stage-changed";
+  if (quoted.currency !== presented.currency) return "currency-changed";
+  if (quoted.destinationDigest !== presented.destinationDigest) return "destination-changed";
+  const left = sortedLines(quoted);
+  const right = sortedLines(presented);
+  if (left.length !== right.length || left.some((line, index) => line.sku !== right[index]?.sku)) return "product-changed";
+  if (left.some((line, index) => line.unitMinor !== right[index]?.unitMinor)) return "price-changed";
+  if (left.some((line, index) => line.quantity !== right[index]?.quantity)) return "quantity-changed";
+  if (quoted.verificationExpiresAt !== presented.verificationExpiresAt || quoted.taxExpiresAt !== presented.taxExpiresAt) {
+    return "evidence-window-changed";
+  }
+  return null;
+}
+
+function evidenceFinding(evidence: CommerceEvidence | null): string | null {
+  if (!evidence) return "missing-evidence";
+  for (const field of EVIDENCE_FIELDS) {
+    const state: EvidenceState | string = evidence[field];
+    if (state === "fresh") continue;
+    if (state === "UNKNOWN") return `evidence-${field}-unknown`;
+    if (state === "stale" || state === "unreadable" || state === "absent") return `evidence-${field}-${state}`;
+    return `evidence-${field}-unreadable`;
+  }
+  return null;
+}
+
+function seamFinding(seam: SeamView | null): { finding: string; owner?: string } | null {
+  if (!seam || seam.status === "absent") return { finding: "verification-seam-absent" };
+  if (seam.status === "clear") return null;
+  const codes = (seam.codes ?? []).filter((code) => /^[a-z0-9_-]+$/.test(code));
+  if (seam.failedClosed && codes.some((code) => code === "verification_unconfigured" || code === "ruleset_unavailable")) {
+    return { finding: "verification-provider-unconfigured", owner: VERIFICATION_PROVIDER_OWNER };
+  }
+  return { finding: codes[0] ? `verification-refused:${codes[0]}` : "verification-refused" };
+}
+
+function isCatalogShape(value: unknown): boolean {
+  return value == null || (typeof value === "object" && value !== null && "available" in value && !("provider" in value));
+}
+
+function commandFinding(reason: string): string {
+  switch (reason) {
+    case "stock":
+      return "stock-unknown";
+    case "fulfillment":
+      return "fulfillment-refused";
+    case "reconcile":
+      return "payment-reconcile";
+    case "payment":
+      return "payment-refused";
+    default:
+      return "evidence-refused";
+  }
+}
+
+function earlierExpiry(left: string, right: string): string {
+  return left <= right ? left : right;
+}
+
+/** Deny with one specific finding, or clear a mirror hold for each sku. */
+export async function evaluateFinalCart(input: FinalCartRequest): Promise<FinalCartDecision> {
+  if (input.browserConfirmed && (!input.token || input.token.scheme !== "asymmetric-jwks" || !input.token.signatureValid)) {
+    return { ok: false, finding: "browser-not-authority" };
+  }
+  if (!input.token) return { ok: false, finding: "signature" };
+  const admitted = admitCallerToken({
+    token: input.token,
+    trustedIssuers: input.trustedIssuers,
+    expectedAudience: input.expectedAudience,
+    activeKids: input.activeKids,
+    now: input.now,
+    tenantId: input.routedTenantId,
+    stage: input.presented.stage,
+  });
+  if (!admitted.ok) return { ok: false, finding: admitted.reason };
+
+  const changed = cartFinding(input.quoted, input.presented, input.routedTenantId);
+  if (changed) return { ok: false, finding: changed };
+
+  if (input.presented.lines.length < 1) return { ok: false, finding: "malformed-request" };
+
+  const evidence = evidenceFinding(input.evidence);
+  if (evidence) return { ok: false, finding: evidence };
+
+  const expiresAt = earlierExpiry(input.presented.verificationExpiresAt, input.presented.taxExpiresAt);
+  if (
+    input.presented.verificationExpiresAt <= input.now ||
+    input.presented.taxExpiresAt <= input.now ||
+    expiresAt <= input.now
+  ) {
+    return { ok: false, finding: "evidence-expired" };
+  }
+
+  let digest: string;
+  let amountMinor: number;
+  try {
+    for (const line of input.presented.lines) {
+      assertMinor(line.quantity, "quantity");
+      assertMinor(line.unitMinor, "unitMinor");
+    }
+    amountMinor = sumMinor(input.presented.lines.map((line) => line.unitMinor * line.quantity));
+    digest = await finalCartDigest(input.presented);
+    const quotedDigest = await finalCartDigest(input.quoted);
+    if (!finalCartStillBound(quotedDigest, digest, input.now, expiresAt)) return { ok: false, finding: "cart-unbound" };
+  } catch {
+    return { ok: false, finding: "malformed-request" };
+  }
+
+  const seam = seamFinding(input.seam);
+  if (seam) return { ok: false, finding: seam.finding, ...(seam.owner ? { owner: seam.owner } : {}) };
+
+  const command = decideCommerceCommand({
+    command: "authorize-final-cart",
+    payment: input.payment ?? "pending",
+    stock: input.stock ?? "unallocated",
+    fulfillment: input.fulfillment ?? "held",
+    label: input.label ?? "none",
+    evidence: input.evidence!,
+    providerOutcome: null,
+  });
+  if (!command.admit) return { ok: false, finding: commandFinding(command.reason) };
+
+  const quantities = new Map<string, number>();
+  for (const line of input.presented.lines) {
+    quantities.set(line.sku, (quantities.get(line.sku) ?? 0) + line.quantity);
+  }
+  const holds: ReserveHold[] = [];
+  for (const sku of [...quantities.keys()].sort()) {
+    const quantity = quantities.get(sku)!;
+    const named =
+      input.authorities.find((value) => {
+        if (!value || typeof value !== "object") return false;
+        return (value as { sku?: unknown }).sku === sku;
+      }) ?? (quantities.size === 1 ? (input.authorities[0] ?? null) : null);
+    if (named && typeof named === "object" && "provider" in named && (named as { provider: unknown }).provider !== "mirror") {
+      return { ok: false, finding: "authority-unavailable" };
+    }
+    const mirror = readMirrorAuthority(named);
+    if (!mirror || mirror.sku !== sku) {
+      return { ok: false, finding: input.catalogAvailable && isCatalogShape(named) ? "catalog-not-authority" : "authority-unavailable" };
+    }
+    if (mirror.onHand < quantity) return { ok: false, finding: "stock-unavailable" };
+    holds.push({ sku, locationId: mirror.locationId, quantity, onHand: mirror.onHand });
+  }
+
+  if (input.token.scheme !== "asymmetric-jwks") return { ok: false, finding: "shared-secret" };
+  return {
+    ok: true,
+    digest,
+    expiresAt,
+    amountMinor,
+    holds,
+    issuer: input.token.issuer,
+    jti: input.token.jti,
+    tenantId: input.routedTenantId,
+    stage: input.presented.stage,
+  };
+}