@tokenoftrust/storefront-runner 3.9.1 → 3.10.0

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,
@@ -108,6 +110,16 @@ async function boundShippingPolicy(
   }
 }
 
+/**
+ * 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,8 +157,11 @@ 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 shipped = await withReturnUrl(shippable, {
+    mode: commerce.mode, secret: signing.secret, returnUrl: submittedFromUrl(context.request, tenant),
+  });
   return new Response(null, {
     status: 303,
     headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.9.1",
+  "version": "3.10.0",
   "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";
@@ -331,12 +335,15 @@ export type CartFieldVisibility = "native" | "internal" | "visible" | "variant-o
 
 /**
  * Characters the checkout store does not keep in a field name, each mapped to a look-alike it
- * keeps. The store validates the name as it rewrites it, not as it was signed: ASCII space, `.`
- * and `[` become `_` (a `[…]` pair turns the field into an array), `||` ends the name, and a name
- * holding `&` or `"` is dropped from validation. Measured 2026-10-23 against tot-preview.foxycart.com
- * by submitting each name with a non-matching hash and reading the name back from its
- * "Cart Validation Error: <name>" refusal. Every other character (NBSP, `/`, `'`, `+`, `-`,
- * non-ASCII) came back unchanged.
+ * keeps. The store hashes `code + name + value` with the name as it received it
+ * (https://wiki.foxycart.com/v/2.0/hmac_validation), and it receives request names through PHP,
+ * which converts "dots and spaces in variable names ... to underscores"
+ * (https://www.php.net/manual/en/language.variables.external.php, "HTML Forms (GET and POST)").
+ * Not documented, measured 2026-10-23 against tot-preview.foxycart.com by submitting each name
+ * with a non-matching hash and reading it back from the "Cart Validation Error: <name>" refusal:
+ * `[` also becomes `_` (a `[…]` pair turns the field into an array), leading spaces are dropped,
+ * `||` ends the name, and a name holding `&` or `"` is never validated. Every other character
+ * (NBSP, `/`, `'`, `+`, `-`, `#`, `=`, `%`, `,`, `:`, a single `|`, non-ASCII) came back unchanged.
  */
 const CHECKOUT_NAME_LOOKALIKES: Readonly<Record<string, string>> = {
   " ": " ",
@@ -927,6 +934,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,