@tokenoftrust/storefront-runner 2.4.48 → 2.4.50

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

@@ -129,10 +129,116 @@ export interface BuildVariantCartPayloadOptions {
    * — subscriptions visible) so existing callers are unaffected.
    */
   autopilotEnabled?: boolean;
+  /**
+   * Tenant id from the request's authenticated context (`locals.tenant`).
+   * Signed into the cart when present. Never taken from the submitted form.
+   */
+  tenantId?: string;
+}
+
+/** Declared public serving substrate (ADR 0013 `serving.provider`). */
+export type CartRouteProvider = "worker-r2-pointer" | "s3-overwrite";
+
+/** Preview is any non-live stage. Publication is the live public site. */
+export type CartRoutePhase = "preview" | "publication";
+
+export const CART_API_ENDPOINT = "/api/commerce/checkout-handoff";
+
+/** Inclusive upper bound for a cart line quantity. */
+export const MAX_CART_QUANTITY = 99;
+
+export const CART_SIGNING_OPERATOR_ERROR =
+  "Signed checkout is unavailable: set FOXY_CART_SECRET (the cart secret) for this environment. No cart was signed.";
+
+export type CartDenialCode =
+  | "signature"
+  | "price"
+  | "quantity"
+  | "tenant"
+  | "signing-unavailable";
+
+export class CartSigningUnavailableError extends Error {
+  readonly code = "signing-unavailable" as const;
+  constructor() {
+    super(CART_SIGNING_OPERATOR_ERROR);
+    this.name = "CartSigningUnavailableError";
+  }
 }
 
 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 line name. The product title is the line. A multi-variant product appends
+ * the variant title unless that title is the placeholder "Default Title".
+ */
+export function cartLineName(
+  product: CatalogProduct,
+  variant: CatalogVariant,
+): string {
+  const productTitle = product.title.trim();
+  const variantTitle = variant.title.trim();
+  const generic =
+    variantTitle.length === 0 || variantTitle.toLowerCase() === "default title";
+  if (product.variants.length > 1 && !generic) {
+    return `${productTitle} — ${variantTitle}`;
+  }
+  return productTitle || variantTitle;
+}
+
+/** Drop a preview pin if one was passed as the API prefix. */
+export function unpinnedApiBase(apiBasePath: string): string {
+  const trimmed = apiBasePath.trim().replace(/\/+$/, "");
+  const idx = trimmed.search(PREVIEW_PIN_RE);
+  if (idx === -1) return trimmed;
+  return trimmed.slice(0, idx).replace(/\/+$/, "");
+}
+
+/**
+ * Worker route for a cart API call. Preview (both providers) and Cloudflare
+ * publication use the unpinned tenant prefix. CloudFront publication uses a
+ * root `/api/...` path, which is the declared CDN behavior. Never a preview pin
+ * and never a public-page origin.
+ */
+export function workerCartApiPath(input: {
+  provider: CartRouteProvider;
+  phase: CartRoutePhase;
+  apiBasePath: string;
+  endpoint?: string;
+}): string {
+  const endpoint = input.endpoint ?? CART_API_ENDPOINT;
+  if (!endpoint.startsWith("/api/") || endpoint.includes("?") || endpoint.includes("#")) {
+    throw new Error("workerCartApiPath: endpoint must be an /api path");
+  }
+  if (PREVIEW_PIN_RE.test(endpoint)) {
+    throw new Error("workerCartApiPath: endpoint must not include a preview pin");
+  }
+  if (input.phase === "publication" && input.provider === "s3-overwrite") {
+    return endpoint;
+  }
+  return `${unpinnedApiBase(input.apiBasePath)}${endpoint}`;
+}
+
+/** True when `path` is a worker-routed cart API path for this provider and phase. */
+export function cartApiReachesWorker(
+  path: string,
+  input: { provider: CartRouteProvider; phase: CartRoutePhase },
+): boolean {
+  const pathname = path.replace(/^https?:\/\/[^/]+/, "").split("?")[0] ?? "";
+  if (PREVIEW_PIN_RE.test(pathname)) return false;
+  if (input.phase === "publication" && input.provider === "s3-overwrite") {
+    return /^\/api\/.+/.test(pathname);
+  }
+  return /^(?:\/[^/]+)?\/api\/.+/.test(pathname);
+}
+
+export function quantityAllowed(value: string): boolean {
+  if (!/^[1-9]\d*$/.test(value)) return false;
+  const n = Number(value);
+  return n >= 1 && n <= MAX_CART_QUANTITY;
+}
 
 /** Resolve the full request-scoped commerce facts from a tenant's config. */
 export function resolveManagedCheckout(
@@ -160,7 +266,7 @@ export function cartFieldsForVariant(
   product: CatalogProduct,
   variant: CatalogVariant,
   purchaseOption?: ProductPurchaseOption,
-  opts?: { signedPrice?: number },
+  opts?: { signedPrice?: number; tenantId?: string },
 ): { code: string; fields: CartField[] } {
   const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
@@ -172,12 +278,19 @@ export function cartFieldsForVariant(
     opts?.signedPrice !== undefined
       ? assertEffectivePrice(opts.signedPrice, variant.price)
       : purchaseOptionPrice(variant.price, purchaseOption);
+  if (!variant.currency) {
+    throw new Error("cartFieldsForVariant: variant currency is required");
+  }
   const fields: CartField[] = [
-    { name: "name", value: variant.title || product.title },
+    { name: "name", value: cartLineName(product, variant) },
     { name: "price", value: price.toFixed(2) },
+    { name: "currency", value: variant.currency },
     { name: "code", value: code },
     { name: "quantity", value: "1", open: true },
   ];
+  if (opts?.tenantId) {
+    fields.push({ name: "tenant", value: opts.tenantId });
+  }
   if (image) fields.push({ name: "image", value: image });
   // Variant options (Flavor, Nicotine strength, …) travel as product options so
   // the cart line reflects the exact variant the shopper picked.
@@ -357,13 +470,11 @@ export async function buildVariantCartPayload(
     product,
     variant,
     opts.purchaseOption,
-    { signedPrice: opts.signedPrice },
+    { signedPrice: opts.signedPrice, tenantId: opts.tenantId },
   );
   const signed = opts.mode === "signed";
   if (signed && !opts.secret) {
-    throw new Error(
-      "buildVariantCartPayload: signed mode requires a cart secret",
-    );
+    throw new CartSigningUnavailableError();
   }
 
   const rendered: RenderedCartField[] = signed
@@ -376,3 +487,158 @@ export async function buildVariantCartPayload(
   const hidden = rendered.filter((_, i) => i !== qtyIdx);
   return { hidden, quantityName };
 }
+
+const CART_DENIAL_MESSAGE: Record<CartDenialCode, string> = {
+  signature: "Checkout was refused because the cart signature does not match.",
+  price: "Checkout was refused because the price does not match the signed price.",
+  quantity: "Checkout was refused because the quantity is not an allowed amount.",
+  tenant: "Checkout was refused because the cart tenant does not match this store.",
+  "signing-unavailable": CART_SIGNING_OPERATOR_ERROR,
+};
+
+export interface CartSubmissionField {
+  name: string;
+  value: string;
+}
+
+export type CartEnforcement =
+  | { ok: true; fields: CartSubmissionField[]; paymentAuthorized: false }
+  | { ok: false; code: CartDenialCode; message: string; paymentAuthorized: false };
+
+interface ParsedCartField {
+  rawName: string;
+  baseName: string;
+  value: string;
+  hash?: string;
+  open: boolean;
+  passthrough: boolean;
+}
+
+function isPassthroughName(name: string): boolean {
+  return UNSIGNED_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+function parseSubmittedField(rawName: string, value: string): ParsedCartField {
+  if (isPassthroughName(rawName)) {
+    return { rawName, baseName: rawName, value, open: false, passthrough: true };
+  }
+  const parts = rawName.split("||");
+  if (parts.length === 3 && parts[2] === "open") {
+    return {
+      rawName,
+      baseName: parts[0] ?? "",
+      value,
+      hash: parts[1],
+      open: true,
+      passthrough: false,
+    };
+  }
+  if (parts.length === 2) {
+    return {
+      rawName,
+      baseName: parts[0] ?? "",
+      value,
+      hash: parts[1],
+      open: false,
+      passthrough: false,
+    };
+  }
+  return { rawName, baseName: rawName, value, open: false, passthrough: false };
+}
+
+function denial(code: CartDenialCode): CartEnforcement {
+  return {
+    ok: false,
+    code,
+    message: CART_DENIAL_MESSAGE[code],
+    paymentAuthorized: false,
+  };
+}
+
+function specificCode(baseName: string): CartDenialCode {
+  if (baseName === "price") return "price";
+  if (baseName === "quantity") return "quantity";
+  if (baseName === "tenant") return "tenant";
+  return "signature";
+}
+
+/**
+ * Server cart check. A browser preflight result is not an input and cannot
+ * authorize payment. Tenant is compared to the trusted request tenant. Price,
+ * quantity, and signature failures are distinct. The returned fields are what
+ * may be handed to the cart; `paymentAuthorized` is always false.
+ */
+export async function enforceCartSubmission(input: {
+  entries: Iterable<[string, string]>;
+  mode: ManagedCheckoutConfig["mode"];
+  secret?: string;
+  trustedTenantId: string;
+}): Promise<CartEnforcement> {
+  if (input.mode === "signed" && !input.secret) return denial("signing-unavailable");
+  if (!input.trustedTenantId) return denial("tenant");
+
+  const parsed = [...input.entries].map(([name, value]) => parseSubmittedField(name, value));
+  const byBase = new Map<string, ParsedCartField>();
+  for (const field of parsed) {
+    if (field.passthrough) continue;
+    if (byBase.has(field.baseName)) return denial("signature");
+    byBase.set(field.baseName, field);
+  }
+
+  const codeField = byBase.get("code");
+  if (!codeField || !codeField.value) return denial("signature");
+
+  const failures = new Set<CartDenialCode>();
+  const signed = input.mode === "signed";
+  const secret = input.secret ?? "";
+
+  const hashOk = async (field: ParsedCartField): Promise<boolean> => {
+    if (!field.hash) return false;
+    const valueToHash = field.open ? "--OPEN--" : field.value;
+    const expected = await hmacHex(secret, codeField.value + field.baseName + valueToHash);
+    return expected === field.hash;
+  };
+
+  if (signed) {
+    if (!(await hashOk(codeField))) failures.add("signature");
+    for (const field of byBase.values()) {
+      if (field.baseName === "code") continue;
+      if (!(await hashOk(field))) failures.add(specificCode(field.baseName));
+    }
+  }
+
+  const tenantField = byBase.get("tenant");
+  if (!tenantField || tenantField.value !== input.trustedTenantId) {
+    failures.add("tenant");
+  }
+  const priceField = byBase.get("price");
+  if (!priceField || !/^\d+\.\d{2}$/.test(priceField.value)) failures.add("price");
+  const quantityField = byBase.get("quantity");
+  if (!quantityField || !quantityAllowed(quantityField.value)) failures.add("quantity");
+  if (signed) {
+    for (const required of ["name", "currency"]) {
+      if (!byBase.get(required)) failures.add("signature");
+    }
+  }
+
+  const order: CartDenialCode[] = ["tenant", "price", "quantity", "signature"];
+  for (const code of order) {
+    if (failures.has(code)) return denial(code);
+  }
+
+  return {
+    ok: true,
+    paymentAuthorized: false,
+    fields: parsed.map((field) => ({ name: field.rawName, value: field.value })),
+  };
+}
+
+/** Cart URL the browser may navigate to after enforcement. Not a payment. */
+export function foxyCartRedirectUrl(
+  cartUrl: string,
+  fields: readonly CartSubmissionField[],
+): string {
+  const url = new URL(cartUrl);
+  for (const field of fields) url.searchParams.append(field.name, field.value);
+  return url.toString();
+}