@tokenoftrust/storefront-runner 3.8.0 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.8.0",
+  "version": "3.9.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

@@ -329,16 +329,46 @@ export const VISIBLE_CART_FIELDS = ["Purchase option"] as const;
 
 export type CartFieldVisibility = "native" | "internal" | "visible" | "variant-option" | "undeclared";
 
+/**
+ * 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.
+ */
+const CHECKOUT_NAME_LOOKALIKES: Readonly<Record<string, string>> = {
+  " ": " ",
+  ".": "․",
+  "[": "(",
+  "]": ")",
+  "&": "＆",
+  '"': "”",
+  "|": "¦",
+};
+const CHECKOUT_NAME_REWRITTEN = /[ .[\]&"|]/g;
+
+/**
+ * The name a cart field is emitted AND signed under. The checkout store validates this exact
+ * string, and the shopper's cart line shows it, so "Nic Strength" stays readable as
+ * "Nic Strength" (with a no-break space) instead of failing as `Nic_Strength`.
+ */
+export function checkoutFieldName(name: string): string {
+  return name.trim().replace(CHECKOUT_NAME_REWRITTEN, (ch) => CHECKOUT_NAME_LOOKALIKES[ch] ?? ch);
+}
+
 /**
  * How a field emitted by `cartFieldsForVariant` reaches the shopper. A field
  * that is none of native, internal, declared-visible, or one of the variant's
  * own options is `undeclared`: it would render on the cart line unreviewed.
+ * `name` is the emitted name (`checkoutFieldName`).
  */
 export function cartFieldVisibility(name: string, variant: Pick<CatalogVariant, "option_values">): CartFieldVisibility {
   if ((NATIVE_CART_FIELDS as readonly string[]).includes(name)) return "native";
   if ((INTERNAL_CART_FIELDS as readonly string[]).includes(name)) return "internal";
-  if ((VISIBLE_CART_FIELDS as readonly string[]).includes(name)) return "visible";
-  if (Object.prototype.hasOwnProperty.call(variant.option_values, name)) return "variant-option";
+  if (VISIBLE_CART_FIELDS.some((visible) => checkoutFieldName(visible) === name)) return "visible";
+  if (Object.keys(variant.option_values).some((option) => checkoutFieldName(option) === name)) return "variant-option";
   return "undeclared";
 }
 
@@ -476,7 +506,9 @@ export function cartFieldsForVariant(
   // Variant options (Flavor, Nicotine strength, …) travel as product options so
   // the cart line reflects the exact variant the shopper picked.
   for (const [optName, optVal] of Object.entries(variant.option_values)) {
-    if (optName && optVal) fields.push({ name: optName, value: optVal });
+    const name = checkoutFieldName(optName);
+    const value = optVal.trim();
+    if (name && value) fields.push({ name, value });
   }
   // Bind the SELECTED purchase option into the signed payload so a shopper can't
   // switch one-time↔subscription (or between plans) after the form is signed —
@@ -486,7 +518,7 @@ export function cartFieldsForVariant(
   // on every non-subscription cart. Any authored option (a real one-time plan or
   // a subscription) is emitted and signed → modifying it fails validation.
   if (purchaseOption && !isDefaultOneTimeOption(purchaseOption)) {
-    fields.push({ name: "Purchase option", value: purchaseOption.label });
+    fields.push({ name: checkoutFieldName("Purchase option"), value: purchaseOption.label });
   }
   if (purchaseOption?.kind === "subscription") {
     fields.push(...subscriptionCartFields(purchaseOption));
@@ -617,8 +649,14 @@ function constantTimeHexEqual(expected: string, presented: string): boolean {
   return acc === 0;
 }
 
+/** A field as the checkout receives it unsigned: under its `checkoutFieldName`. */
+function unsignedField(field: CartField): RenderedCartField {
+  return { name: checkoutFieldName(field.name), value: field.value };
+}
+
 /**
- * Sign one field for product `code`. Editable fields hash the sentinel
+ * Sign one field for product `code`. The hashed name and the emitted name are the
+ * same `checkoutFieldName`, so they cannot diverge. Editable fields hash the sentinel
  * `--OPEN--` and gain the `||open` suffix so checkout accepts a user-entered value.
  */
 async function signField(
@@ -626,11 +664,12 @@ async function signField(
   code: string,
   field: CartField,
 ): Promise<RenderedCartField> {
+  const fieldName = checkoutFieldName(field.name);
   const valueToHash = field.open ? "--OPEN--" : field.value;
-  const hash = await hmacHex(secret, code + field.name + valueToHash);
+  const hash = await hmacHex(secret, code + fieldName + valueToHash);
   const name = field.open
-    ? `${field.name}||${hash}||open`
-    : `${field.name}||${hash}`;
+    ? `${fieldName}||${hash}||open`
+    : `${fieldName}||${hash}`;
   return { name, value: field.value };
 }
 
@@ -673,7 +712,7 @@ export async function buildVariantCartPayload(
 
   const rendered: RenderedCartField[] = signed
     ? await Promise.all(fields.map((f) => signField(opts.secret!, code, f)))
-    : fields.map((f) => ({ name: f.name, value: f.value }));
+    : fields.map(unsignedField);
 
   // Split the quantity field out: the island puts it on the visible stepper.
   const qtyIdx = fields.findIndex((f) => f.name === "quantity");
@@ -861,7 +900,7 @@ export async function withVerificationRef(
   const code = fields.find((field) => field.name.split("||")[0] === "code")?.value;
   if (!code) return [...fields];
   const field: CartField = { name: "verification", value: opts.ref };
-  if (opts.mode !== "signed") return [...fields, field];
+  if (opts.mode !== "signed") return [...fields, unsignedField(field)];
   if (!opts.secret) throw new CartSigningUnavailableError();
   return [...fields, await signField(opts.secret, code, field)];
 }
@@ -883,7 +922,7 @@ export async function withShippingPolicy(
   const currency = kept.find((field) => field.name.split("||")[0] === "currency")?.value;
   if (!code || !currency) throw new ShippingPolicyUnavailableError();
   const field: CartField = { name: SHIPPING_POLICY_CART_FIELD, value: shippingPolicyOptionValue(opts.policy, currency) };
-  if (opts.mode !== "signed") return [...kept, field];
+  if (opts.mode !== "signed") return [...kept, unsignedField(field)];
   if (!opts.secret) throw new CartSigningUnavailableError();
   return [...kept, await signField(opts.secret, code, field)];
 }