@tokenoftrust/storefront-runner 2.0.17 → 2.0.18

package/apps/storefront/env.d.ts

@@ -10,6 +10,8 @@ import type {
   BrowserEnvironment,
   CompiledIntegrationCsp,
   EffectivePlan,
+  ConsentSnapshot,
+  ResolvedRouteTierV1,
 } from "@tot/public-runtime";
 import type { ToTClient } from "@/lib/tot/ToTClient";
 import type { ContentProvider } from "@/lib/storyblok/provider";
@@ -104,6 +106,12 @@ declare global {
     interface Locals {
       /** Tenant resolved from the request Host by src/middleware. */
       tenant: TenantConfig;
+      /**
+       * THE route-tier answer for this request (ADR 0013), resolved once by the
+       * middleware from the TENANT-RELATIVE path and used to pick which branch
+       * served it. Downstream code reads this rather than re-deriving a tier.
+       */
+      routeTier: ResolvedRouteTierV1;
       /**
        * Effective capability flags for the resolved tenant (commerce defaults
        * unless siteType:"marketing"/explicit features). Chrome, layout islands,
@@ -157,6 +165,16 @@ declare global {
        * wired; carries no secret and no nonce.
        */
       integrationPlan: EffectivePlan;
+      /**
+       * The tenant's actual initial consent snapshot — computed once by the
+       * middleware from its saved {@link TenantConsentConfig} (ext-admin-03) via
+       * the neutral consent broker (ext-policy-03), or the fail-closed
+       * essential-only default when the tenant has never configured one. BOTH
+       * document mounts (Layout.astro + rawHtmlResponse) inline THIS value as
+       * `consent.defaults`, so a shopper's pre-interaction eligibility matches
+       * what the tenant actually approved — never a hardcoded default.
+       */
+      consentSnapshot: ConsentSnapshot;
       /**
        * Resolved cart/checkout facts for this request (loader src, cart URL,
        * mode). Present only for commerce tenants with a checkout store;

package/apps/storefront/migrations-apps/0012_test_destinations.sql

@@ -0,0 +1,29 @@
+-- A tenant-owned, NON-LIVE-ONLY destination a developer registers to prove
+-- exactly-once delivery for a new marketing action before wiring a real vendor
+-- adapter. `environment` is never `live` — enforced by the managed-analytics
+-- service, not by this table.
+CREATE TABLE `test_destinations` (
+  `destination_id` text PRIMARY KEY NOT NULL,
+  `tenant_id` text NOT NULL,
+  `environment` text NOT NULL,
+  `created_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_test_destinations_tenant`
+  ON `test_destinations` (`tenant_id`);
+--> statement-breakpoint
+-- The delivered-event ledger a test destination reads back. Keyed by
+-- (destination_id, event_id): a retried/duplicate delivery of the same event id
+-- is `INSERT OR IGNORE`, so the row a caller reads back always reflects the
+-- FIRST delivery only — the proof that delivery landed exactly once.
+CREATE TABLE `test_destination_deliveries` (
+  `destination_id` text NOT NULL,
+  `event_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `action_name` text NOT NULL,
+  `delivered_at` text NOT NULL,
+  PRIMARY KEY(`destination_id`, `event_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_test_destination_deliveries_tenant`
+  ON `test_destination_deliveries` (`tenant_id`);

package/apps/storefront/src/components/blog/ReactionBar.astro

@@ -9,7 +9,7 @@
  * view counts). Tenant/collection-generic: mounts on any post route.
  */
 import { getReactionCounts, REACTIONS, type Reaction } from "@/lib/blog/reactions.js";
-import { readKv } from "@/lib/env";
+import { readKv } from "@/lib/runtimeEnv";
 import { withBase } from "@/lib/basePath";
 
 interface Props {

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

@@ -11,6 +11,16 @@
  * 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.
  *
+ * On a tenant wired to the LIVE Token of Trust verification provider, preflight
+ * additionally echoes a `verification` block (ref / provider status / continuation
+ * URL). That block's presence — and only that — branches this dialog into the live
+ * trip: collect the shopper's email, start the verification, open the provider's
+ * 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`.
+ *
  * 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
@@ -20,6 +30,17 @@
  */
 import { useCallback, useEffect, useRef, useState } from "preact/hooks";
 import type { CartComplianceDecision } from "@tot/public-runtime";
+import {
+  clearStoredRef,
+  parsePreflightResponse,
+  pollVerification,
+  readStoredRef,
+  verificationPhase,
+  verificationRefKey,
+  writeStoredRef,
+  type PreflightResponse,
+  type VerificationPhase,
+} from "./checkoutVerificationFlow.js";
 
 interface Props {
   /** Absolute (base-path-aware) URL of the preflight endpoint. */
@@ -70,6 +91,12 @@ interface PendingLine {
   title: string;
 }
 
+/** Shopper-facing phase, extended with the two paused states polling can end in. */
+type DialogPhase = VerificationPhase | "stalled";
+
+const FAIL_CLOSED_MESSAGE =
+  "We couldn't reach our compliance check. For your safety, checkout is paused — please try again.";
+
 export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props) {
   const [pending, setPending] = useState<PendingLine | null>(null);
   const [region, setRegion] = useState("");
@@ -79,6 +106,22 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
   const [error, setError] = useState<string | null>(null);
   const dialogRef = useRef<HTMLDivElement>(null);
 
+  // --- Live-provider verification trip (inert on sandbox / no-provider tenants).
+  const [phase, setPhase] = useState<DialogPhase>("none");
+  const [email, setEmail] = useState("");
+  const [givenName, setGivenName] = useState("");
+  const [familyName, setFamilyName] = useState("");
+  const [verificationRef, setVerificationRef] = useState<string | null>(null);
+  const [continuationUrl, setContinuationUrl] = useState<string | null>(null);
+  const [popupBlocked, setPopupBlocked] = useState(false);
+  /** Cancellation token for the in-flight poll loop (at most one at a time). */
+  const pollToken = useRef<{ cancelled: boolean } | null>(null);
+
+  const stopPolling = useCallback(() => {
+    if (pollToken.current) pollToken.current.cancelled = true;
+    pollToken.current = null;
+  }, []);
+
   // Intercept managed-cart form submits (capture phase, before the native POST).
   useEffect(() => {
     function onSubmit(e: Event) {
@@ -91,16 +134,23 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
       e.stopPropagation();
       const qtyInput = form.querySelector<HTMLInputElement>('input[name$="quantity" i], input[name="quantity"]');
       const quantity = Math.max(1, parseInt(qtyInput?.value ?? "1", 10) || 1);
-      setPending({
+      const line: PendingLine = {
         form,
         handle: form.dataset.productHandle ?? "",
         sku: form.dataset.variantSku || undefined,
         variantId: form.dataset.variantId || undefined,
         quantity,
         title: form.dataset.productTitle ?? "this item",
-      });
+      };
+      setPending(line);
       setDecision(null);
       setError(null);
+      setPhase("none");
+      setContinuationUrl(null);
+      setPopupBlocked(false);
+      // A reload mid-trip must not lose the correlation: replay the stored ref so
+      // the server re-reads THIS attempt's verification instead of starting over.
+      setVerificationRef(readStoredRef(verificationRefKey(preflightUrl, line)));
       let pre = false;
       try {
         pre = localStorage.getItem(AGE_KEY) === "yes";
@@ -112,17 +162,21 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
     }
     document.addEventListener("submit", onSubmit, true);
     return () => document.removeEventListener("submit", onSubmit, true);
-  }, []);
+  }, [preflightUrl]);
 
   const close = useCallback(() => {
+    stopPolling();
     setPending(null);
     setDecision(null);
     setError(null);
     setLoading(false);
+    setPhase("none");
     document.documentElement.style.overflow = "";
-  }, []);
+  }, [stopPolling]);
 
   const proceed = useCallback((line: PendingLine) => {
+    stopPolling();
+    clearStoredRef(verificationRefKey(preflightUrl, line));
     line.form.dataset.complianceCleared = "1";
     document.documentElement.style.overflow = "";
     setPending(null);
@@ -130,54 +184,194 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
     // 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]);
+
+  /**
+   * One preflight POST. `null` for a transport error or any body we cannot fully
+   * read — the caller treats both as fail-closed.
+   */
+  const send = useCallback(
+    async (
+      line: PendingLine,
+      opts: { ref: string | null; includeShopper: boolean },
+    ): Promise<PreflightResponse | null> => {
+      const trimmedEmail = email.trim();
+      try {
+        const res = await fetch(preflightUrl, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            lines: [
+              {
+                handle: line.handle,
+                sku: line.sku,
+                variantId: line.variantId,
+                quantity: line.quantity,
+              },
+            ],
+            destination: region ? { region, country: "US" } : null,
+            ageAffirmed: affirmed,
+            ...(opts.ref ? { verificationRef: opts.ref } : {}),
+            ...(opts.includeShopper && trimmedEmail
+              ? {
+                  shopper: {
+                    email: trimmedEmail,
+                    ...(givenName.trim() ? { givenName: givenName.trim() } : {}),
+                    ...(familyName.trim() ? { familyName: familyName.trim() } : {}),
+                  },
+                }
+              : {}),
+          }),
+        });
+        return parsePreflightResponse(await res.json());
+      } catch {
+        return null;
+      }
+    },
+    [preflightUrl, region, affirmed, email, givenName, familyName],
+  );
+
+  /**
+   * Wait for the shopper to finish on their own device by RE-READING the server's
+   * decision. The client is never told "done" by the provider widget — it asks.
+   */
+  const startPolling = useCallback(
+    (line: PendingLine, ref: string) => {
+      stopPolling();
+      const token = { cancelled: false };
+      pollToken.current = token;
+      void pollVerification({
+        poll: () => send(line, { ref, includeShopper: false }),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        cancelled: () => token.cancelled,
+      }).then((outcome) => {
+        if (token.cancelled) return;
+        pollToken.current = null;
+        switch (outcome.kind) {
+          case "cleared":
+            setDecision(outcome.response.decision);
+            proceed(line);
+            return;
+          case "denied":
+            setDecision(outcome.response.decision);
+            setPhase("denied");
+            clearStoredRef(verificationRefKey(preflightUrl, line));
+            setVerificationRef(null);
+            return;
+          case "halted":
+            // Verification settled but the cart still isn't clear (another block,
+            // or a decision polling can't move). Stop, show it, stay re-checkable.
+            setDecision(outcome.response.decision);
+            setPhase(
+              verificationPhase(outcome.response) === "cleared" ? "cleared" : "stalled",
+            );
+            return;
+          case "error":
+            // Fail closed: an unreadable poll never proceeds; it pauses.
+            setError(FAIL_CLOSED_MESSAGE);
+            setPhase("stalled");
+            return;
+          case "timeout":
+            setPhase("stalled");
+            return;
+          default:
+            return;
+        }
+      });
+    },
+    [send, proceed, preflightUrl, stopPolling],
+  );
+
+  const apply = useCallback(
+    (line: PendingLine, res: PreflightResponse) => {
+      const key = verificationRefKey(preflightUrl, line);
+      const meta = res.verification;
+      const ref = meta?.ref ?? null;
+      if (ref) {
+        setVerificationRef(ref);
+        writeStoredRef(key, ref);
+      }
+      if (meta?.continuationUrl) setContinuationUrl(meta.continuationUrl);
+
+      setDecision(res.decision);
+      // Only the server's own verdict releases the handoff.
+      if (res.decision.status === "clear") {
+        proceed(line);
+        return;
+      }
+
+      const next = verificationPhase(res);
+      setPhase(next);
+      if (next === "denied") {
+        clearStoredRef(key);
+        setVerificationRef(null);
+        return;
+      }
+      if (next === "continue" && meta?.continuationUrl && ref) {
+        // The provider's own embedded workflow, opened in a new tab: no
+        // third-party framing/cookie surprises, and nothing here assumes it can
+        // observe completion — the poll below asks the server instead.
+        let opened: Window | null = null;
+        try {
+          opened = window.open(meta.continuationUrl, "_blank", "noopener,noreferrer");
+        } catch {
+          opened = null;
+        }
+        setPopupBlocked(!opened);
+        startPolling(line, ref);
+        return;
+      }
+      if (next === "waiting" && ref) startPolling(line, ref);
+    },
+    [preflightUrl, proceed, startPolling],
+  );
 
   const check = useCallback(async () => {
     if (!pending) return;
+    stopPolling();
     setLoading(true);
     setError(null);
     setDecision(null);
-    try {
-      const res = await fetch(preflightUrl, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-          lines: [
-            {
-              handle: pending.handle,
-              sku: pending.sku,
-              variantId: pending.variantId,
-              quantity: pending.quantity,
-            },
-          ],
-          destination: region ? { region, country: "US" } : null,
-          ageAffirmed: affirmed,
-        }),
-      });
-      const data = (await res.json()) as { decision?: CartComplianceDecision };
-      const d = data.decision;
-      if (!d) {
-        // Fail closed: a regulated tenant never proceeds on an unreadable result.
-        setError(
-          "We couldn't confirm this order can ship. Please try again in a moment.",
-        );
-        return;
-      }
-      setDecision(d);
-      if (d.status === "clear") proceed(pending);
-    } catch {
-      setError(
-        "We couldn't reach our compliance check. For your safety, checkout is paused — please try again.",
-      );
-    } finally {
-      setLoading(false);
+    setPopupBlocked(false);
+    const res = await send(pending, {
+      ref: verificationRef,
+      includeShopper: phase === "collect" || phase === "stalled",
+    });
+    setLoading(false);
+    if (!res) {
+      // Fail closed: a regulated tenant never proceeds on an unreadable result.
+      setError(FAIL_CLOSED_MESSAGE);
+      return;
     }
-  }, [pending, preflightUrl, region, affirmed, proceed]);
+    apply(pending, res);
+  }, [pending, send, apply, verificationRef, phase, stopPolling]);
+
+  /** Abandon a denied attempt and start a brand-new verification (new ref). */
+  const restartVerification = useCallback(() => {
+    stopPolling();
+    setVerificationRef(null);
+    setContinuationUrl(null);
+    setDecision(null);
+    setError(null);
+    setPhase("collect");
+    if (pending) clearStoredRef(verificationRefKey(preflightUrl, pending));
+  }, [pending, preflightUrl, stopPolling]);
 
   if (!pending) return null;
 
   const blocks = decision?.blocks ?? [];
   const adultSignature = decision?.requirements.adultSignature;
+  const waiting = phase === "continue" || phase === "waiting";
+  const primaryLabel = loading
+    ? "Checking…"
+    : waiting
+      ? "Waiting for verification…"
+      : phase === "collect"
+        ? "Start verification"
+        : phase === "stalled"
+          ? "Check verification status"
+          : "Continue to checkout";
 
   return (
     <div
@@ -236,10 +430,64 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
             />
             <span>I confirm I am {minAge} or older.</span>
           </label>
+
+          {/*
+            LIVE provider only. Rendered strictly when the server has told us a
+            verification is required AND unresolved for this attempt — sandbox /
+            no-provider tenants stay on the flow above, untouched.
+          */}
+          {phase === "collect" && (
+            <div class="flex flex-col gap-3 rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-bg)] p-4">
+              <p class="text-sm text-[var(--color-text)]">
+                This order needs a one-time age verification. Enter your email and
+                we'll open a secure step you can complete on this device.
+              </p>
+              <label class="flex flex-col gap-1.5">
+                <span class="font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-muted)]">
+                  Email
+                </span>
+                <input
+                  type="email"
+                  required
+                  autocomplete="email"
+                  name="tot-verification-email"
+                  class="rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-2.5 text-[var(--color-text)]"
+                  value={email}
+                  onInput={(e) => setEmail((e.target as HTMLInputElement).value)}
+                />
+              </label>
+              <div class="flex flex-wrap gap-3">
+                <label class="flex min-w-[9rem] flex-1 flex-col gap-1.5">
+                  <span class="font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-muted)]">
+                    First name (optional)
+                  </span>
+                  <input
+                    type="text"
+                    autocomplete="given-name"
+                    class="rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-2.5 text-[var(--color-text)]"
+                    value={givenName}
+                    onInput={(e) => setGivenName((e.target as HTMLInputElement).value)}
+                  />
+                </label>
+                <label class="flex min-w-[9rem] flex-1 flex-col gap-1.5">
+                  <span class="font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-muted)]">
+                    Last name (optional)
+                  </span>
+                  <input
+                    type="text"
+                    autocomplete="family-name"
+                    class="rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-2.5 text-[var(--color-text)]"
+                    value={familyName}
+                    onInput={(e) => setFamilyName((e.target as HTMLInputElement).value)}
+                  />
+                </label>
+              </div>
+            </div>
+          )}
         </div>
 
         {/* Decision surface */}
-        {blocks.length > 0 && (
+        {blocks.length > 0 && phase !== "denied" && (
           <div
             class="mt-5 rounded-[var(--radius-md)] border border-[var(--color-sale)] bg-[color-mix(in_srgb,var(--color-sale)_8%,transparent)] px-4 py-3"
             role="alert"
@@ -257,6 +505,64 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
           </div>
         )}
 
+        {/* Live verification trip */}
+        {(phase === "continue" || phase === "waiting") && (
+          <div class="mt-5 rounded-[var(--radius-md)] border border-[var(--color-border)] px-4 py-3">
+            <p class="font-display text-sm font-semibold text-[var(--color-text)]">
+              Finish your age verification
+            </p>
+            {phase === "continue" && continuationUrl && (
+              <p class="mt-1.5 text-sm text-[var(--color-text)]">
+                {popupBlocked
+                  ? "Your browser blocked the verification window — open it here:"
+                  : "We opened a secure verification step in a new tab. If you don't see it:"}{" "}
+                <a
+                  href={continuationUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  class="underline"
+                  onClick={() => setPopupBlocked(false)}
+                >
+                  open verification
+                </a>
+                .
+              </p>
+            )}
+            <p class="mt-1.5 text-sm text-[var(--color-muted)]">
+              Keep this page open — checkout continues automatically once your
+              verification is confirmed.
+            </p>
+          </div>
+        )}
+
+        {phase === "denied" && (
+          <div
+            class="mt-5 rounded-[var(--radius-md)] border border-[var(--color-sale)] bg-[color-mix(in_srgb,var(--color-sale)_8%,transparent)] px-4 py-3"
+            role="alert"
+          >
+            <p class="font-display text-sm font-semibold text-[var(--color-sale)]">
+              Verification didn't pass
+            </p>
+            <p class="mt-1.5 text-sm text-[var(--color-text)]">
+              We couldn't confirm you meet the {minAge}+ requirement for this
+              order, so it can't proceed. If you believe this is a mistake you can
+              start a new verification.
+            </p>
+          </div>
+        )}
+
+        {phase === "stalled" && !error && blocks.length === 0 && (
+          <div
+            class="mt-5 rounded-[var(--radius-md)] border border-[var(--color-border)] px-4 py-3"
+            role="status"
+          >
+            <p class="text-sm text-[var(--color-text)]">
+              We stopped waiting for your verification. Checkout is paused — once
+              you've finished the verification step, check again.
+            </p>
+          </div>
+        )}
+
         {error && (
           <p
             class="mt-5 rounded-[var(--radius-md)] border border-[var(--color-sale)] bg-[color-mix(in_srgb,var(--color-sale)_8%,transparent)] px-4 py-3 text-sm text-[var(--color-text)]"
@@ -273,14 +579,24 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
         )}
 
         <div class="mt-6 flex flex-wrap gap-3">
-          <button
-            type="button"
-            disabled={loading}
-            onClick={check}
-            class="rounded-full bg-[var(--color-primary)] px-6 py-3 font-display text-sm font-medium uppercase tracking-[0.08em] text-[var(--color-primary-contrast)] transition-opacity hover:opacity-90 disabled:opacity-60"
-          >
-            {loading ? "Checking…" : "Continue to checkout"}
-          </button>
+          {phase === "denied" ? (
+            <button
+              type="button"
+              onClick={restartVerification}
+              class="rounded-full bg-[var(--color-primary)] px-6 py-3 font-display text-sm font-medium uppercase tracking-[0.08em] text-[var(--color-primary-contrast)] transition-opacity hover:opacity-90 disabled:opacity-60"
+            >
+              Start a new verification
+            </button>
+          ) : (
+            <button
+              type="button"
+              disabled={loading || waiting || (phase === "collect" && !email.trim())}
+              onClick={check}
+              class="rounded-full bg-[var(--color-primary)] px-6 py-3 font-display text-sm font-medium uppercase tracking-[0.08em] text-[var(--color-primary-contrast)] transition-opacity hover:opacity-90 disabled:opacity-60"
+            >
+              {primaryLabel}
+            </button>
+          )}
           <button
             type="button"
             onClick={close}