@tokenoftrust/storefront-runner 3.9.2 → 3.10.1

package/apps/storefront/src/components/checkout/storefront/commerce/CheckoutLoader.astro

@@ -14,13 +14,15 @@
  * allowlist set in middleware. It is loaded as a plain cross-origin script
  * (NO `crossorigin` attribute) because the CDN serves it without CORS headers.
  */
+import { cartSessionCookiePath } from "@/lib/checkout/commerce/cartSession";
 import { lazyCheckoutLoaderJs } from "@/lib/checkout/shared/lazyCheckoutLoader";
 
 interface Props {
   nonce?: string;
 }
-const { commerce, storeNotPublic } = Astro.locals;
+const { commerce, storeNotPublic, apiBasePath, basePath } = Astro.locals;
 const { nonce } = Astro.props;
+const apiBase = apiBasePath ?? basePath ?? "";
 ---
 {
   commerce && (
@@ -28,6 +30,8 @@ const { nonce } = Astro.props;
         loaderSrc: commerce.loaderSrc,
         cartOrigin: commerce.origin,
         storeNotPublic: !!storeNotPublic,
+        sessionHref: `${apiBase}/api/commerce/cart-session`,
+        cookiePath: cartSessionCookiePath(apiBase),
       })} />
   )
 }

package/apps/storefront/src/lib/checkout/commerce/cartSession.ts

@@ -0,0 +1,182 @@
+import type { APIContext } from "astro";
+
+/**
+ * Per-tenant cart session on a shared Foxy store.
+ *
+ * The hosted cart session lives on the Foxy host, so two stores on that host
+ * otherwise share one cart. This store keeps the session id Foxy issued in an
+ * HttpOnly cookie on the tenant's own API prefix and sends it as `fcsid` on
+ * every cart open. A stored id Foxy does not echo, or a cart whose lines are
+ * not all this tenant, is discarded for a new empty session. The browser never
+ * asks Foxy for the id: that request would send the shared Foxy cookie.
+ */
+export const CART_SESSION_COOKIE = "tot_fcsid";
+
+/** Issued ids are lowercase alphanumerics. Measured length is 26; garbage fails closed. */
+export const CART_SESSION_ID = /^[a-z0-9]{10,64}$/;
+
+/** Same lifetime Foxy gives its browse-site session cookie. */
+export const CART_SESSION_MAX_AGE = 2_592_000;
+
+export const CART_UNAVAILABLE_MESSAGE =
+  "Checkout is unavailable because this store's cart could not be opened.";
+
+const FOXY_TIMEOUT_MS = 5_000;
+
+export interface CartSessionBinding {
+  cookies: APIContext["cookies"];
+  locals: { apiBasePath?: string; basePath?: string };
+}
+
+/** Cookie path for every revision of one tenant. A host-routed store uses `/`. */
+export function cartSessionCookiePath(basePath: string): string {
+  const trimmed = basePath.trim();
+  if (trimmed === "" || trimmed === "/") return "/";
+  const withLead = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return `${withLead.replace(/\/+$/, "")}/`;
+}
+
+/** Cart URL that selects one Foxy session. Other params are kept. */
+export function withCartSession(cartUrl: string, id: string): string {
+  const url = new URL(cartUrl);
+  url.searchParams.set("fcsid", id);
+  return url.toString();
+}
+
+function saneSessionId(value: unknown): value is string {
+  return typeof value === "string" && CART_SESSION_ID.test(value);
+}
+
+function optionBaseName(option: unknown): string | null {
+  if (!option || typeof option !== "object") return null;
+  const raw = (option as { name?: unknown; class?: unknown }).name
+    ?? (option as { class?: unknown }).class;
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  return raw.split("||")[0] ?? "";
+}
+
+function optionValue(option: unknown): string | null {
+  if (!option || typeof option !== "object") return null;
+  const value = (option as { value?: unknown }).value;
+  return typeof value === "string" ? value : null;
+}
+
+function itemTenant(item: unknown): string | null {
+  if (!item || typeof item !== "object") return null;
+  const options = (item as { options?: unknown }).options;
+  if (Array.isArray(options)) {
+    for (const option of options) {
+      if (optionBaseName(option) === "tenant") return optionValue(option);
+    }
+    return null;
+  }
+  if (options && typeof options === "object") {
+    for (const [key, value] of Object.entries(options as Record<string, unknown>)) {
+      if (key.split("||")[0] === "tenant" && typeof value === "string") return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * An empty cart is usable. A line with no tenant option, or another tenant's
+ * line, is not: a missed session must not check out a mixed cart.
+ */
+export function cartAcceptsTenant(body: unknown, tenantId: string): boolean {
+  if (!tenantId || !body || typeof body !== "object") return false;
+  const items = (body as { items?: unknown }).items;
+  if (items == null) {
+    const count = (body as { item_count?: unknown }).item_count;
+    return count == null || count === 0;
+  }
+  if (!Array.isArray(items)) return false;
+  return items.every((item) => itemTenant(item) === tenantId);
+}
+
+type CartRead = { status: "cart"; body: unknown } | { status: "unreadable"; reason: string };
+
+/** A cart Foxy returned, or a read that failed. A failure is not an empty cart. */
+async function readFoxyCart(
+  cartUrl: string,
+  fcsid: string | null,
+  fetchImpl: typeof fetch,
+): Promise<CartRead> {
+  let url: URL;
+  try {
+    url = new URL(cartUrl);
+  } catch (error) {
+    return { status: "unreadable", reason: error instanceof Error ? error.name : "Error" };
+  }
+  url.searchParams.set("output", "json");
+  if (fcsid) url.searchParams.set("fcsid", fcsid);
+  try {
+    const response = await fetchImpl(url.toString(), {
+      method: "GET",
+      redirect: "manual",
+      credentials: "omit",
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(FOXY_TIMEOUT_MS),
+    });
+    if (!response.ok) return { status: "unreadable", reason: `HTTP ${response.status}` };
+    return { status: "cart", body: await response.json() };
+  } catch (error) {
+    return { status: "unreadable", reason: error instanceof Error ? error.name : "Error" };
+  }
+}
+
+function sessionIdOf(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const id = (body as { session_id?: unknown }).session_id;
+  return saneSessionId(id) ? id : null;
+}
+
+/**
+ * The session this tenant may add to. A sane stored id is reused only when
+ * Foxy echoes it and every line is this tenant. A read that fails stays closed
+ * and does not mint. Otherwise Foxy is asked for a new empty session, with no
+ * cookie and no id. Null when no usable id comes back.
+ */
+export async function resolveTenantCartSession(input: {
+  cartUrl: string;
+  tenantId: string;
+  existing: string | null;
+  fetch?: typeof fetch;
+}): Promise<string | null> {
+  if (!input.tenantId) return null;
+  const fetchImpl = input.fetch ?? fetch;
+  const existing = saneSessionId(input.existing) ? input.existing : null;
+  if (existing) {
+    const read = await readFoxyCart(input.cartUrl, existing, fetchImpl);
+    if (read.status === "unreadable") return null;
+    if (sessionIdOf(read.body) === existing && cartAcceptsTenant(read.body, input.tenantId)) return existing;
+  }
+  const fresh = await readFoxyCart(input.cartUrl, null, fetchImpl);
+  if (fresh.status !== "cart") return null;
+  const id = sessionIdOf(fresh.body);
+  if (id && cartAcceptsTenant(fresh.body, input.tenantId)) return id;
+  return null;
+}
+
+/** Read the tenant cookie, resolve a Foxy session, and store the id when one is usable. */
+export async function bindCartSession(
+  context: CartSessionBinding,
+  commerce: { cartUrl: string },
+  tenantId: string,
+  fetchImpl?: typeof fetch,
+): Promise<string | null> {
+  const id = await resolveTenantCartSession({
+    cartUrl: commerce.cartUrl,
+    tenantId,
+    existing: context.cookies.get(CART_SESSION_COOKIE)?.value ?? null,
+    fetch: fetchImpl,
+  });
+  if (!id) return null;
+  context.cookies.set(CART_SESSION_COOKIE, id, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: cartSessionCookiePath(context.locals.apiBasePath ?? context.locals.basePath ?? ""),
+    maxAge: CART_SESSION_MAX_AGE,
+  });
+  return id;
+}

package/apps/storefront/src/lib/checkout/commerce/checkoutHandoffRoute.ts

@@ -30,6 +30,8 @@ import {
   takeVerificationRef,
   withVerificationRef,
   withShippingPolicy,
+  withReturnUrl,
+  trustedCartReturnUrl,
   SHIPPING_UNAVAILABLE_CART_MESSAGE,
   ShippingPolicyUnavailableError,
   type CartDenialCode,
@@ -39,6 +41,7 @@ import {
   type ResolvedManagedCheckout,
 } from "@tot/public-runtime";
 import { resolveCheckoutHandoffCorrelation } from "@/lib/checkout/commerce/checkoutHandoffCorrelation";
+import { bindCartSession, CART_UNAVAILABLE_MESSAGE, withCartSession } from "@/lib/checkout/commerce/cartSession";
 import { resolveCartSigning, shopperCartDenialMessage } from "@/lib/checkout/shared/checkoutCommerce";
 
 export type SampleProductReader = (tenant: TenantConfig, handle: string, commerce: ResolvedManagedCheckout) => Promise<CatalogProduct | null>;
@@ -108,6 +111,29 @@ async function boundShippingPolicy(
   }
 }
 
+/** Redirect onto this tenant's Foxy session. A shopper-supplied fcsid is dropped. */
+async function sessionedCartLocation(
+  context: APIContext,
+  commerce: ResolvedManagedCheckout,
+  tenant: TenantConfig,
+  fields: readonly CartSubmissionField[],
+): Promise<string | null> {
+  const fcsid = await bindCartSession(context, commerce, commerceTenantId(tenant));
+  if (!fcsid) return null;
+  const kept = fields.filter((field) => field.name.split("||")[0] !== "fcsid");
+  return foxyCartRedirectUrl(withCartSession(commerce.cartUrl, fcsid), kept);
+}
+
+/**
+ * The page the shopper submitted from, when it is served by this request's host or the tenant's
+ * declared domain. The browser's Referer is the only source; a foreign or absent one yields none.
+ */
+function submittedFromUrl(request: Request, tenant: TenantConfig): string | null {
+  const domain = tenant.appDomain?.toLowerCase();
+  const hosts = [new URL(request.url).host, ...(domain ? [domain, `www.${domain}`] : [])];
+  return trustedCartReturnUrl(request.headers.get("referer"), hosts);
+}
+
 /** Native cart POST. Browser preflight is not consulted. Payment is never authorized. */
 async function cartFormPost(context: APIContext): Promise<Response> {
   const { tenant, commerce } = context.locals;
@@ -145,12 +171,17 @@ async function cartFormPost(context: APIContext): Promise<Response> {
     return cartDenial(result.code, shopperCartDenialMessage(result.code, result.message), status);
   }
   const verified = await withVerificationRef(result.fields, { mode: commerce.mode, secret: signing.secret, ref });
-  const shipped = await boundShippingPolicy(verified, tenant, commerce.mode, signing.secret);
-  if (!shipped) return cartDenial("shipping", SHIPPING_UNAVAILABLE_CART_MESSAGE, 409);
+  const shippable = await boundShippingPolicy(verified, tenant, commerce.mode, signing.secret);
+  if (!shippable) return cartDenial("shipping", SHIPPING_UNAVAILABLE_CART_MESSAGE, 409);
+  const returned = await withReturnUrl(shippable, {
+    mode: commerce.mode, secret: signing.secret, returnUrl: submittedFromUrl(context.request, tenant),
+  });
+  const location = await sessionedCartLocation(context, commerce, tenant, returned);
+  if (!location) return cartDenial("signing-unavailable", CART_UNAVAILABLE_MESSAGE, 503);
   return new Response(null, {
     status: 303,
     headers: {
-      location: foxyCartRedirectUrl(commerce.cartUrl, shipped),
+      location,
       "cache-control": "no-store",
       "x-tot-payment-authorized": "false",
     },
@@ -252,7 +283,9 @@ export async function sampleCartGet(
     if (!result.ok) return invalid();
     const shipped = await boundShippingPolicy(result.fields, tenant, "signed", signing.secret);
     if (!shipped) return sampleResponse('{"error":"shipping_unavailable"}', 409);
-    return sampleResponse(null, 303, foxyCartRedirectUrl(commerce.cartUrl, shipped));
+    const location = await sessionedCartLocation(context, commerce, tenant, shipped);
+    if (!location) return sampleResponse('{"error":"cart_unavailable"}', 503);
+    return sampleResponse(null, 303, location);
   } catch { return sampleResponse('{"error":"sample_unavailable"}', 503); }
 }
 

package/apps/storefront/src/lib/checkout/shared/lazyCheckoutLoader.ts

@@ -22,16 +22,24 @@
  * after every page handler, so an action another handler already took over (the
  * compliance gate) is left alone.
  *
+ * Every cart open waits for this store's Foxy session. The id comes from the
+ * same-origin session endpoint (an HttpOnly cookie the browser cannot read) and
+ * is applied in the loader's `onLoad`, before the drawer reads its own cookie.
+ * Cart links get the same id on the URL. If the session cannot be opened, the
+ * cart is not followed.
+ *
  * On a store that is not public (`storeNotPublic`), a managed add-to-cart is
  * checked before it leaves the page: the checkout route refuses a viewer admitted
  * only by a preview grant, so instead of navigating to the gate's holding page
- * the form says checkout is unavailable here and offers sign-in. A public store
- * never pays that round trip.
+ * the form says checkout is unavailable here and offers sign-in.
  *
  * Emitted by <CheckoutLoader> with the page nonce (an attribute cannot carry
  * one), and identical on the Cloudflare-served preview and the statically
- * published (CloudFront/S3) output — both render Layout.astro.
+ * published (CloudFront/S3) output — both render Layout.astro. The session id
+ * is not part of that HTML.
  */
+import { CART_UNAVAILABLE_MESSAGE } from "@/lib/checkout/commerce/cartSession";
+
 export const LAZY_CHECKOUT_LOADER_IDLE_MS = 8000;
 
 /** Upper bound on waiting for the drawer to report ready before replaying a held action. */
@@ -49,6 +57,10 @@ export interface LazyCheckoutLoaderOptions {
   loaderSrc: string;
   /** `https://<store domain>` — the cart origin whose links and forms the drawer takes over. */
   cartOrigin: string;
+  /** Same-origin URL that returns this store's `{ fcsid }`. A path, never an id. */
+  sessionHref: string;
+  /** Foxy browse-site cookie path for this host. `/` or a tenant prefix with a trailing slash. */
+  cookiePath: string;
   /** The store is not public on this host, so its checkout route may refuse this viewer. */
   storeNotPublic?: boolean;
 }
@@ -63,10 +75,14 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
   return `(function () {
   var src = ${literal(options.loaderSrc)};
   var cartOrigin = ${literal(options.cartOrigin)};
+  var sessionHref = ${literal(options.sessionHref)};
+  var cookiePath = ${literal(options.cookiePath)};
   var storeNotPublic = ${options.storeNotPublic ? "true" : "false"};
   var events = ${literal(LAZY_CHECKOUT_LOADER_EVENTS)};
   var state = 'idle';
   var waiters = [];
+  var sessionId = null;
+  var sessionPromise = null;
   function targetsCart(url) {
     if (!url) return false;
     try { return new URL(url, document.baseURI).origin === cartOrigin; } catch (e) { return false; }
@@ -80,6 +96,37 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     }
     return false;
   }
+  function ensureSession() {
+    if (sessionId) return Promise.resolve(sessionId);
+    if (sessionPromise) return sessionPromise;
+    sessionPromise = fetch(sessionHref, {
+      credentials: 'same-origin',
+      cache: 'no-store',
+      signal: AbortSignal.timeout(5000),
+    }).then(function (res) {
+      return res.ok ? res.json() : null;
+    }).then(function (body) {
+      var id = body && typeof body.fcsid === 'string' ? body.fcsid : '';
+      if (!/^[a-z0-9]{10,64}$/.test(id)) {
+        sessionPromise = null;
+        return null;
+      }
+      sessionId = id;
+      return id;
+    }, function () {
+      sessionPromise = null;
+      return null;
+    });
+    return sessionPromise;
+  }
+  function markSessionUnavailable() {
+    waiters = [];
+    state = 'idle';
+    document.documentElement.setAttribute('data-cart-session', 'unavailable');
+    for (var i = 0; i < events.length; i++) {
+      document.addEventListener(events[i], onInput, { capture: true, passive: true });
+    }
+  }
   function ready() {
     if (state === 'ready') return;
     state = 'ready';
@@ -87,10 +134,15 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     waiters = [];
     for (var i = 0; i < run.length; i++) run[i]();
   }
-  function start() {
-    if (state !== 'idle') return;
-    state = 'loading';
-    for (var i = 0; i < events.length; i++) document.removeEventListener(events[i], onInput, true);
+  function armDrawer(id) {
+    document.documentElement.removeAttribute('data-cart-session');
+    window.FC = window.FC || {};
+    window.FC.onLoad = function () {
+      window.FC.settings = window.FC.settings || {};
+      window.FC.settings.session_id = id;
+      window.FC.settings.cookiepath = cookiePath;
+      window.FC.settings.sitedomain = location.hostname;
+    };
     setTimeout(ready, ${LAZY_CHECKOUT_READY_TIMEOUT_MS});
     var s = document.createElement('script');
     s.src = src;
@@ -110,6 +162,15 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     s.addEventListener('error', ready);
     document.body.appendChild(s);
   }
+  function start() {
+    if (state !== 'idle') return;
+    state = 'loading';
+    for (var i = 0; i < events.length; i++) document.removeEventListener(events[i], onInput, true);
+    ensureSession().then(function (id) {
+      if (!id) return markSessionUnavailable();
+      armDrawer(id);
+    });
+  }
   function whenReady(fn) {
     if (state === 'ready') return fn();
     waiters.push(fn);
@@ -124,14 +185,40 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
   function arm() { setTimeout(start, ${LAZY_CHECKOUT_LOADER_IDLE_MS}); }
   if (document.readyState === 'complete') arm();
   else window.addEventListener('load', arm);
+  function stampAnchor(anchor) {
+    if (!sessionId) return;
+    try {
+      var url = new URL(anchor.href, document.baseURI);
+      url.searchParams.set('fcsid', sessionId);
+      anchor.href = url.toString();
+    } catch (e) {}
+  }
+  function stampForm(form) {
+    if (!sessionId || !targetsCart(form.getAttribute('action'))) return;
+    var input = form.querySelector('input[name="fcsid"]');
+    if (!input) {
+      input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = 'fcsid';
+      form.appendChild(input);
+    }
+    input.value = sessionId;
+  }
 
   window.addEventListener('click', function (event) {
-    if (state === 'ready' || event.defaultPrevented) return;
     if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
     var anchor = event.target && event.target.closest ? event.target.closest('a[href]') : null;
     if (!anchor || anchor.target === '_blank' || !targetsCart(anchor.href)) return;
+    if (state === 'ready') {
+      stampAnchor(anchor);
+      return;
+    }
+    if (event.defaultPrevented) return;
     event.preventDefault();
-    whenReady(function () { anchor.click(); });
+    whenReady(function () {
+      stampAnchor(anchor);
+      anchor.click();
+    });
   });
 
   function resubmit(form) {
@@ -156,19 +243,51 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     note.appendChild(link);
     form.insertAdjacentElement('afterend', note);
   }
-  function proceed(form) {
-    form.dataset.checkoutReachable = '1';
-    resubmit(form);
+  function showCartUnavailable(form) {
+    var next = form.nextElementSibling;
+    if (next && next.hasAttribute('data-cart-unavailable')) return;
+    var note = document.createElement('p');
+    note.setAttribute('role', 'alert');
+    note.setAttribute('data-cart-unavailable', '');
+    note.className = 'mt-2 text-sm';
+    note.textContent = ${literal(CART_UNAVAILABLE_MESSAGE)};
+    form.insertAdjacentElement('afterend', note);
+  }
+  function openSessionThen(form, fn) {
+    ensureSession().then(function (id) {
+      if (!id) { showCartUnavailable(form); return; }
+      form.dataset.cartSession = '1';
+      fn();
+    });
   }
   window.addEventListener('submit', function (event) {
     if (event.defaultPrevented) return;
     var form = event.target;
     if (!form || typeof form.getAttribute !== 'function') return;
-    if (storeNotPublic && form.matches(${managedCart}) && form.dataset.checkoutReachable !== '1') {
+    var managed = form.matches(${managedCart});
+    var cartForm = targetsCart(form.getAttribute('action'));
+    if (!managed && !cartForm) return;
+    if (form.dataset.cartSession === '1') {
+      if (!cartForm || state === 'ready') return;
       event.preventDefault();
+      whenReady(function () { stampForm(form); resubmit(form); });
+      return;
+    }
+    event.preventDefault();
+    function afterGate() {
+      openSessionThen(form, function () {
+        if (cartForm) {
+          stampForm(form);
+          whenReady(function () { resubmit(form); });
+          return;
+        }
+        resubmit(form);
+      });
+    }
+    if (storeNotPublic && managed && form.dataset.checkoutReachable !== '1') {
       // The handoff route's JSON form only mints an unattributed correlation, so it answers
       // "may this viewer reach checkout?" without starting one. Any other answer, or no
-      // answer, submits natively and the route decides.
+      // answer, continues to this store's session and the route decides.
       fetch(form.action, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
@@ -179,13 +298,15 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
           return res.json().then(function (body) { return body && body.signIn; }, function () { return null; })
             .then(function (signIn) { showUnavailable(form, signIn); });
         }
-        proceed(form);
-      }, function () { proceed(form); });
+        form.dataset.checkoutReachable = '1';
+        afterGate();
+      }, function () {
+        form.dataset.checkoutReachable = '1';
+        afterGate();
+      });
       return;
     }
-    if (state === 'ready' || !targetsCart(form.getAttribute('action'))) return;
-    event.preventDefault();
-    whenReady(function () { resubmit(form); });
+    afterGate();
   });
 })();`;
 }

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

@@ -0,0 +1,25 @@
+/** This store's Foxy session id. The id is never written into a page. */
+import type { APIRoute } from "astro";
+import { commerceTenantId } from "@tot/public-runtime";
+import { bindCartSession } from "@/lib/checkout/commerce/cartSession";
+
+export const prerender = false;
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+export const GET: APIRoute = async (context) => {
+  const { commerce, tenant } = context.locals;
+  if (!commerce) return json({ error: "no-store" }, 409);
+  const tenantId = tenant ? commerceTenantId(tenant) : "";
+  const fcsid = tenantId ? await bindCartSession(context, commerce, tenantId) : null;
+  if (!fcsid) return json({ error: "cart-unavailable" }, 503);
+  return json({ fcsid }, 200);
+};

package/apps/storefront/src/pages/cart.ts

@@ -1,4 +1,6 @@
 import type { APIRoute } from "astro";
+import { commerceTenantId } from "@tot/public-runtime";
+import { bindCartSession, CART_UNAVAILABLE_MESSAGE, withCartSession } from "@/lib/checkout/commerce/cartSession.js";
 import { managedCartHref } from "@/lib/content/chrome/managedCart.js";
 
 export const prerender = false;
@@ -8,15 +10,27 @@ export const prerender = false;
  * Chrome now links straight to managed checkout, but this route prevents stale
  * links from falling through the content catch-all to a misleading storefront
  * 404. Tenant resolution and preview authorization have already run in
- * middleware before this redirect is selected.
+ * middleware before this redirect is selected. The redirect carries this
+ * tenant's Foxy session and never the shared cart.
  */
-export const GET: APIRoute = ({ locals }) => {
-  const location = managedCartHref(locals.commerce);
-  if (!location) return new Response(null, { status: 404 });
+export const GET: APIRoute = async (context) => {
+  const location = managedCartHref(context.locals.commerce);
+  if (!location || !context.locals.commerce) return new Response(null, { status: 404 });
+  const tenantId = context.locals.tenant ? commerceTenantId(context.locals.tenant) : "";
+  const sessionId = tenantId ? await bindCartSession(context, context.locals.commerce, tenantId) : null;
+  if (!sessionId) {
+    return new Response(CART_UNAVAILABLE_MESSAGE, {
+      status: 503,
+      headers: {
+        "cache-control": "private, no-store",
+        "content-type": "text/plain; charset=utf-8",
+      },
+    });
+  }
   return new Response(null, {
     status: 302,
     headers: {
-      location,
+      location: withCartSession(location, sessionId),
       "cache-control": "private, no-store",
     },
   });

package/package.json

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

package/packages/public-runtime/src/checkout.ts

@@ -204,9 +204,13 @@ export class CartSigningUnavailableError extends Error {
  * item option: `enforceCartSubmission` and the commerce pre-payment callback
  * both bind the cart to it. `verification` carries the shopper's verification
  * ref when the gate produced one (`withVerificationRef`). `shipping_policy` carries the
- * store's declared shipping charge (`withShippingPolicy`).
+ * store's declared shipping charge (`withShippingPolicy`). `return_url` carries the page the
+ * shopper submitted from (`withReturnUrl`).
  */
-export const INTERNAL_CART_FIELDS = ["currency", "tenant", "verification", "shipping_policy"] as const;
+export const INTERNAL_CART_FIELDS = ["currency", "tenant", "verification", "shipping_policy", "return_url"] as const;
+
+/** The signed cart option the checkout store's Continue Shopping link reads (`withReturnUrl`). */
+export const RETURN_URL_CART_FIELD = "return_url";
 
 /** The signed cart option the checkout store reads the shipping charge from. */
 export const SHIPPING_POLICY_CART_FIELD = "shipping_policy";
@@ -379,6 +383,8 @@ const DEFAULT_CHECKOUT_HOST_SUFFIX = ".foxycart.com";
 const SUBSCRIPTION_FREQUENCY_RE = /^(?:\d+(?:\.\d+)?|\.\d+)[dwmy]$/;
 const PREVIEW_PIN_RE = /\/preview\/(?:staged|candidate)(?:\/|$)/;
 const UNSIGNED_PREFIXES = ["h:", "x:", "__", "utm_"] as const;
+/** Cart-level selector. Not a product field, so it never enters the signature. */
+const CART_LEVEL_PARAMS = new Set(["fcsid"]);
 
 /**
  * Cart line name. The product title is the line. A multi-variant product appends
@@ -752,7 +758,7 @@ interface ParsedCartField {
 }
 
 function isPassthroughName(name: string): boolean {
-  return UNSIGNED_PREFIXES.some((prefix) => name.startsWith(prefix));
+  return CART_LEVEL_PARAMS.has(name) || UNSIGNED_PREFIXES.some((prefix) => name.startsWith(prefix));
 }
 
 function parseSubmittedField(rawName: string, value: string): ParsedCartField {
@@ -930,6 +936,51 @@ export async function withShippingPolicy(
   return [...kept, await signField(opts.secret, code, field)];
 }
 
+const MAX_RETURN_URL_LENGTH = 1500;
+
+/**
+ * The page a cart was submitted from, or `null` when it is not one this store serves. Only an
+ * http(s) URL without credentials whose host is in `servedHosts` qualifies, so a form posted from
+ * another site, or a crafted cart link, can never make the checkout domain link to a foreign
+ * origin. The fragment is dropped. `servedHosts` comes from the request's own host and the
+ * tenant's declared domain, never from the client.
+ */
+export function trustedCartReturnUrl(
+  candidate: string | null | undefined,
+  servedHosts: readonly string[],
+): string | null {
+  if (!candidate || candidate.length > MAX_RETURN_URL_LENGTH) return null;
+  if (!URL.canParse(candidate)) return null;
+  const url = new URL(candidate);
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  if (url.username || url.password) return null;
+  const served = servedHosts.map((host) => host.trim().toLowerCase()).filter(Boolean);
+  if (!served.includes(url.host.toLowerCase())) return null;
+  url.hash = "";
+  const href = url.toString();
+  return href.length <= MAX_RETURN_URL_LENGTH ? href : null;
+}
+
+/**
+ * Bind the originating page into an enforced cart as the internal `return_url` option, signed
+ * against the cart's product code. Any `return_url` the shopper submitted is dropped first, so only
+ * the server-derived, host-checked value reaches the cart. No trusted URL leaves the cart without
+ * one, and the checkout falls back to its own Continue Shopping target.
+ */
+export async function withReturnUrl(
+  fields: readonly CartSubmissionField[],
+  opts: { mode: ManagedCheckoutConfig["mode"]; secret?: string; returnUrl: string | null },
+): Promise<CartSubmissionField[]> {
+  const kept = fields.filter((field) => field.name.split("||")[0] !== RETURN_URL_CART_FIELD);
+  if (!opts.returnUrl) return kept;
+  const code = kept.find((field) => field.name.split("||")[0] === "code")?.value;
+  if (!code) return kept;
+  const field: CartField = { name: RETURN_URL_CART_FIELD, value: opts.returnUrl };
+  if (opts.mode !== "signed") return [...kept, field];
+  if (!opts.secret) throw new CartSigningUnavailableError();
+  return [...kept, await signField(opts.secret, code, field)];
+}
+
 /** Cart URL the browser may navigate to after enforcement. Not a payment. */
 export function foxyCartRedirectUrl(
   cartUrl: string,