@blamejs/blamejs-shop 0.3.56 → 0.3.58

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.58 (2026-06-04) — **Browser form submissions no longer refused as cross-origin, server-side shipping-address validation, and a repaired checkout layout.** Every navigational form POST served by the container — checkout, magic-link sign-in, product reviews, returns, the account area, and the admin console — was refused with a 403 in real browsers. Pages shipped Referrer-Policy: no-referrer, which makes browsers send Origin: null on same-origin form submissions, and the CSRF gate's origin pre-check refuses a null Origin before the token is read. Both the edge and the container now send Referrer-Policy: same-origin: referrer information still never leaves the site, while same-origin posts carry the real Origin the gate verifies. Cross-site and sandboxed-iframe submissions are still refused. Checkout additionally gains backend shipping-address validation with accessible per-field errors that preserve everything the shopper typed, and the checkout page's layout is repaired — fields fill the form column instead of collapsing to its center, and the gift, store-pickup, and loyalty options render inside the form above the submit button. **Added:** *Server-side shipping-address validation with per-field errors* — The checkout POST validates the shipping address on the backend and, on rejection, re-renders the form with the one bad field marked (aria-invalid plus an adjacent role="alert" message) and every typed value preserved — replacing the previous dead-end error page. Country must be a real ISO 3166-1 alpha-2 code, validated against the platform's Intl region data (no new dependencies). US and Canadian destinations validate the state or province code and the ZIP (12345 or 12345-6789) / postal (A1A 1A1) format, and require street, city, region, and postal — the figures that feed destination tax. Every other country keeps lenient length-bounded checks, so international addresses are never over-validated. Email gains a shape check alongside the existing content-safety gate, and the customer name is length-bounded. Headless callers of checkout.confirm keep the presence-optional contract for digital-only orders; malformed values are now refused everywhere. **Fixed:** *Form posts from real browsers were refused as cross-origin (403)* — Pages were served with Referrer-Policy: no-referrer, which per the Fetch specification makes browsers serialize the Origin header as the literal string "null" on same-origin navigational POSTs. The CSRF gate's origin pre-check refuses a null Origin before the double-submit token is validated, so every container-rendered form returned {"error":"CSRF cross-origin request refused."} on submit — checkout, magic-link sign-in, reviews, returns, account self-service, and the admin console. JSON fetch() calls (passkeys, saved cards, the cart-count island) carry a real Origin and were unaffected. Both substrates now send Referrer-Policy: same-origin: no referrer information ever leaves the site (matching the previous policy's intent), same-origin posts carry a real Origin verified against the configured public origins, and cross-site or sandboxed-iframe posts still arrive as null and are still refused. The integration suite now drives the full Origin matrix — same-origin accepted, null and cross-origin refused — closing the gap between loopback tests (which send no Origin header) and real browsers. Operators composing their own securityHeaders options should not reinstate no-referrer: it re-breaks every tokened form post. · *Checkout layout: fields fill the column; gift and pickup options join the form* — A global form rule leaked align-items: center into the checkout's stacked form, collapsing every field to its content width in the middle of a wide column; the stacked form now stretches its rows. The gift-options, store-pickup, and loyalty-redeem blocks were spliced in after the submit button, rendering as an unstyled run of fields below the call to action — they now render inside the form above the submit row, framed as cards consistent with the order summary, with labels matching the shipping fields.
+
+- v0.3.57 (2026-06-02) — **Vendored blamejs framework refreshed from v0.14.16 to v0.14.19.** The storefront runs on a vendored copy of the blamejs framework. This refreshes it across three upstream patch releases (v0.14.16 to v0.14.19), picking up framework fixes and hardening. The most operator-relevant is a PKCE-downgrade defense in the OAuth/OIDC client, which the storefront composes for Sign in with Google and Apple, so the federated sign-in flow inherits it. The remaining upstream changes are in framework areas the storefront does not expose (archive writing, SCIM, verifiable-credential issuance, SPF/DMARC tooling, OpenAPI), and the storefront's own behavior is unchanged — verified by the full test suite and the vendored-tree integrity gate against the new tree. **Changed:** *Updated the vendored framework to blamejs v0.14.19* — The vendored framework moves from v0.14.16 to v0.14.19 (three upstream patch releases of fixes and additive, opt-in changes). Notably, the OAuth/OIDC client now refuses an identity provider that advertises PKCE methods without S256 — a stripped-S256 downgrade defense — which hardens the storefront's Sign in with Google and Apple. The integrity manifest over the vendored tree was re-stamped as part of the refresh.
+
 - v0.3.56 (2026-06-02) — **Opt-in wishlist alert and digest emails, passwordless magic-link sign-in, and a documented list of planned integrations.** Two opt-in capabilities are wired, and the operator docs now state plainly which integrations are planned-but-not-yet-available so nothing reads as silently missing. A customer can opt in to wishlist price-drop and back-in-stock alerts and a periodic wishlist digest; and a passwordless email magic-link offers an account sign-in path alongside passkeys and OAuth. Both stay inert until an operator configures email sending, so a store with no mailer behaves exactly as before. **Added:** *Opt-in wishlist alert and digest emails* — A customer can opt in, from their wishlist, to price-drop and back-in-stock alerts and to a periodic wishlist digest. Scheduled sweeps send them. The feature is off until an operator configures email sending and an email resolver; with no mailer it is a no-op. Digest emails are rendered field-by-field with output escaping. · *Passwordless magic-link sign-in* — When a mailer is configured, a customer can request a single-use, time-limited sign-in link by email, in addition to passkeys and OAuth. The request response is identical whether or not the email matches an account (no account enumeration), and the link establishes a sealed session on use. **Changed:** *Documented planned integrations* — The README and SECURITY docs now list the integrations that are intentionally not yet available — address validation, live chat, web-push notifications, in-console payment-key configuration, an age gate, and per-page promo banners — each with the condition under which it would be built, so operators know what is and isn't supported rather than discovering a gap.
 
 - v0.3.55 (2026-06-02) — **Accessibility: field-level form-error messages and horizontally scrollable admin tables.** Two accessibility improvements. When a storefront form is rejected, the specific field at fault is now marked for assistive technology with an inline error message tied to that input, in addition to the existing summary at the top of the form. And wide tables in the admin console now scroll horizontally inside their own container instead of overflowing the page on a narrow or zoomed viewport. **Fixed:** *Field-level error messages on storefront forms* — When the address, review, product-question, or support-ticket form is rejected, the offending field is now marked aria-invalid with an inline error message associated to it (aria-describedby), so a screen-reader user is taken to the exact field to fix rather than only hearing a top-of-form summary. The server remains the only validator; this only changes how a rejected field is presented. Forms that fail on a whole-form condition continue to show the summary message. · *Admin tables reflow on narrow screens* — Wide data tables in the admin console (orders, products, inventory, and the rest) are now wrapped in a horizontal-scroll container, so columns stay reachable on a smaller laptop window, a split screen, or at high zoom instead of overflowing the layout. Column header semantics are preserved.

package/README.md

@@ -68,7 +68,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/shipping.js`** | Operator-table adapter. Services with zones (flat or per-gram + base + min/max), free-over-threshold, `digital_only` flag. |
 | **`lib/payment.js`** | Payment adapters — **Stripe** (verify webhook HMAC-SHA256 via upstream `b.webhook.verify`, create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains for Apple/Google Pay) and **PayPal** (`adapter: "paypal"` — OAuth2 client-credentials token, create / capture / get / refund Orders v2, webhook verify via PayPal's verify-webhook-signature API). No `stripe` / `paypal` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
 | **`lib/order.js`** | FSM-driven post-checkout record via upstream `b.fsm`. States: pending → paid → fulfilling → shipped → delivered (+ refunded / cancelled). Every transition appends to `order_transitions`. |
-| **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` creates a Stripe PaymentIntent + persists order pending; `handleStripeEvent()` verifies webhook + fires the FSM transition. PayPal path: `createPaypalOrder()` opens a PayPal order + persists pending, `capturePaypalOrder()` captures → paid, `handlePaypalEvent()` is the webhook backstop. All idempotent on re-delivery. |
+| **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` validates the ship-to address (real ISO 3166-1 country; US/CA state + ZIP/postal formats; lenient elsewhere) and the customer email shape, then creates a Stripe PaymentIntent + persists order pending; `handleStripeEvent()` verifies webhook + fires the FSM transition. PayPal path: `createPaypalOrder()` opens a PayPal order + persists pending, `capturePaypalOrder()` captures → paid, `handlePaypalEvent()` is the webhook backstop. All idempotent on re-delivery. |
 | **`lib/email.js`** | Transactional templates — order receipt, ship notification, refund confirmation, wishlist price-drop, abandoned-cart, review request, back-in-stock, **wishlist digest** (the periodic saved-items rollup, rendered per-line from the structured digest so every title / price is independently escaped), and **email magic-link sign-in**. Strict `{{var}}` renderer with HTML escape + refusal of unknown / unused placeholders. Composed on `b.mail` (DKIM/SPF/DMARC/BIMI upstream). |
 | **`lib/storefront.js`** | Server-rendered HTML — utility bar + sticky header + dark hero with code-preview card + primitives marquee + featured-product callout + collections grid + framework feature band + designed catalog grid + newsletter band + four-column footer. Designed surfaces also for PDP, cart, checkout, pay, order, account login / register / dashboard, search results, `/admin` API landing, 404. Image-bearing cards on the home + search grids pull from `catalog.media`. The default theme stylesheet is external (R2-served `themes/default/assets/css/main.css`) and CSP-compliant; the typeface (Inter / Inter Tight) is self-hosted from `themes/default/assets/fonts`, so no page loads a cross-origin font. Operators override by uploading a replacement at the same key, by passing `opts.theme_css` to renderers, or by registering a named theme through the `theme` primitive. |
 | **`lib/customers.js`** | Customer accounts — passkey (WebAuthn) + **Sign in with Google / Apple** (OIDC). Email is stored hash-only (`b.crypto.namespaceHash` namespace `customer-email`); the raw address never lands in D1. Passkey credentials carry CBOR-encoded public keys, transport hints, and SHA3-512-fingerprinted attestation. `signInWithOIDC` keys federated accounts on the provider `(provider, subject)` and links an existing account only on a provider-verified email (never on an unverified one). `mintAppleClientSecret` produces Apple's required ES256 client-secret JWT from a Services-ID `.p8` key (the one classical signature the protocol mandates; the PQC default doesn't apply to an external IdP's wire format). Account routes (`/account/login`, `/account/register`, `/account`, `/account/login/google`, `/account/login/apple`) ship as designed cards on the storefront; signed-in customers manage their own passkeys (`/account/passkeys` — list, add another, confirm-gated revoke scoped to the account with a last-sign-in-method guard) and edit their profile (`/account/profile`). |

package/SECURITY.md

@@ -120,6 +120,17 @@ node -e "
   the value identically on the Worker (`wrangler secret put
   D1_BRIDGE_SECRET`) and the container env. Rotate quarterly or after
   any Worker-credential compromise.
+- **Referrer-Policy is load-bearing for CSRF.** The app sends
+  `Referrer-Policy: same-origin` on both the edge and the container.
+  Browsers serialize the `Origin` header as `null` on same-origin
+  navigational form POSTs when the page's referrer policy is
+  `no-referrer`, and the CSRF gate's origin pre-check refuses a null
+  Origin before the token is read — switching the policy back to
+  `no-referrer` 403s every tokened form submission (checkout,
+  sign-in, account, admin) in real browsers while loopback tests
+  stay green. Keep `same-origin` (referrer data still never leaves
+  the site), or pair any stricter policy with an origin-tolerant
+  CSRF configuration you have tested in a real browser.
 - **Stripe webhook signature.** Inbound `POST` to
   `/api/webhooks/stripe` is signature-verified at the Worker edge
   (HMAC-SHA256 over `<timestamp>.<body>`, 5-minute tolerance window)

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.3.56",
+  "version": "0.3.58",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",
       "fingerprinted": "css/admin.44eb97700c660798.css"
     },
     "css/main.css": {
-      "integrity": "sha384-2nlE5YDlOjcnP/l1EY5kcYwvbV/TboHx+Hi6fAaDNyaau3nzQppJnNyXoLiFE8w1",
-      "fingerprinted": "css/main.59afbe779336867a.css"
+      "integrity": "sha384-pEf1nxijlK9mXs8LacGqzNmr+WzjMR7c17Gsx24YS1PharS/BWa62RU/fUL8XSa6",
+      "fingerprinted": "css/main.bb97cd4c4b867440.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",

package/lib/checkout.js

@@ -47,16 +47,83 @@ function _email(s) {
   catch (e) { throw new TypeError("checkout: customer.email — " + (e && e.message || "invalid email")); }
 }
 
+// ---- address format validation -------------------------------------------
+//
+// ISO 3166-1 alpha-2 validity via the platform Intl data (zero-dep): an
+// assigned region code resolves to a display name, an unknown one round-
+// trips unchanged, so the `.of()` echo test distinguishes them. CLDR also
+// names a handful of reserved/sentinel codes that are NOT assigned ISO
+// 3166-1 countries (ZZ "Unknown Region", UK/EU/EZ/UN/SU/FX, the XA/XB
+// pseudo-locales, QO) — deny-listed below so a shopper typing "UK" gets
+// the crisp field error pointing at GB instead of a confusing no-
+// shipping-zone failure later. XK (Kosovo, user-assigned) stays accepted
+// — it ships. Memoized — one formatter per process. Falls back to the
+// shape check if Intl region data is unavailable so checkout never
+// hard-fails on a stripped ICU build.
+var _NON_ISO_REGION = Object.freeze({
+  ZZ: 1, UK: 1, EU: 1, EZ: 1, UN: 1, SU: 1, FX: 1, XA: 1, XB: 1, QO: 1,
+});
+var _regionNames = null;
+function _isIsoCountry(cc) {
+  if (typeof cc !== "string" || !/^[A-Z]{2}$/.test(cc)) return false;
+  if (_NON_ISO_REGION[cc]) return false;
+  try {
+    if (!_regionNames) _regionNames = new Intl.DisplayNames(["en"], { type: "region" });
+    return _regionNames.of(cc) !== cc; // unknown codes echo the input back
+  } catch (_e) {
+    return true; // Intl region data unavailable → shape-only validation
+  }
+}
+
+// USPS state/territory and Canada Post province/territory codes, plus the
+// two countries' postal formats. Format validation tightens ONLY for these
+// two well-known sets; every other destination keeps the lenient length-
+// bounded checks — international address formats defy tight rules, and
+// over-validating them locks real customers out of checkout.
+var _US_STATES = Object.freeze({
+  AL: 1, AK: 1, AZ: 1, AR: 1, CA: 1, CO: 1, CT: 1, DE: 1, DC: 1, FL: 1,
+  GA: 1, HI: 1, ID: 1, IL: 1, IN: 1, IA: 1, KS: 1, KY: 1, LA: 1, ME: 1,
+  MD: 1, MA: 1, MI: 1, MN: 1, MS: 1, MO: 1, MT: 1, NE: 1, NV: 1, NH: 1,
+  NJ: 1, NM: 1, NY: 1, NC: 1, ND: 1, OH: 1, OK: 1, OR: 1, PA: 1, RI: 1,
+  SC: 1, SD: 1, TN: 1, TX: 1, UT: 1, VT: 1, VA: 1, WA: 1, WV: 1, WI: 1,
+  WY: 1, AS: 1, GU: 1, MP: 1, PR: 1, VI: 1,
+});
+var _CA_PROVINCES = Object.freeze({
+  AB: 1, BC: 1, MB: 1, NB: 1, NL: 1, NS: 1, NT: 1, NU: 1, ON: 1, PE: 1,
+  QC: 1, SK: 1, YT: 1,
+});
+var _US_ZIP = /^\d{5}(-\d{4})?$/;
+var _CA_POSTAL = /^[A-Za-z]\d[A-Za-z] ?\d[A-Za-z]\d$/;
+
 function _shipTo(s) {
   if (!s || typeof s !== "object") throw new TypeError("checkout: ship_to must be an object");
-  if (typeof s.country !== "string" || !/^[A-Z]{2}$/.test(s.country)) {
-    throw new TypeError("checkout: ship_to.country must be a 2-letter ISO 3166-1 code");
+  if (typeof s.country !== "string" || !_isIsoCountry(s.country)) {
+    throw new TypeError("checkout: ship_to.country — Enter a valid two-letter country code (e.g. US, GB).");
   }
-  if (s.state  && (typeof s.state  !== "string" || !/^[A-Z0-9]{1,5}$/.test(s.state))) {
-    throw new TypeError("checkout: ship_to.state malformed");
-  }
-  if (s.postal && (typeof s.postal !== "string" || !/^[A-Za-z0-9 -]{1,16}$/.test(s.postal))) {
-    throw new TypeError("checkout: ship_to.postal malformed");
+  // US + Canada get real region-code and postal-format validation when the
+  // fields are present; presence itself is the storefront form's contract
+  // (a digital-only order legitimately carries a bare country). The
+  // messages are customer-facing — the checkout form echoes them on the
+  // rejected field.
+  if (s.country === "US" || s.country === "CA") {
+    var regionCodes = s.country === "US" ? _US_STATES : _CA_PROVINCES;
+    if (s.state && (typeof s.state !== "string" || !Object.prototype.hasOwnProperty.call(regionCodes, s.state))) {
+      throw new TypeError(s.country === "US"
+        ? "checkout: ship_to.state — Enter a valid US state or territory code (e.g. CA)."
+        : "checkout: ship_to.state — Enter a valid Canadian province code (e.g. ON).");
+    }
+    if (s.postal && (typeof s.postal !== "string" || !(s.country === "US" ? _US_ZIP : _CA_POSTAL).test(s.postal))) {
+      throw new TypeError(s.country === "US"
+        ? "checkout: ship_to.postal — Enter a valid ZIP code (12345 or 12345-6789)."
+        : "checkout: ship_to.postal — Enter a valid postal code (A1A 1A1).");
+    }
+  } else {
+    if (s.state  && (typeof s.state  !== "string" || !/^[A-Za-z0-9 .-]{1,32}$/.test(s.state))) {
+      throw new TypeError("checkout: ship_to.state — Enter a valid state / province code.");
+    }
+    if (s.postal && (typeof s.postal !== "string" || !/^[A-Za-z0-9 -]{1,16}$/.test(s.postal))) {
+      throw new TypeError("checkout: ship_to.postal — Enter a valid postal code.");
+    }
   }
   // Street address + city are free-text (international addresses defy a
   // tight character class), so validation is shape + length only. They
@@ -66,13 +133,13 @@ function _shipTo(s) {
   // export). The checkout form marks line1 + city required so the
   // common physical-goods path collects a complete address.
   if (s.line1 && (typeof s.line1 !== "string" || s.line1.length > 200)) {
-    throw new TypeError("checkout: ship_to.line1 malformed");
+    throw new TypeError("checkout: ship_to.line1 — Enter a street address of 200 characters or fewer.");
   }
   if (s.line2 && (typeof s.line2 !== "string" || s.line2.length > 200)) {
-    throw new TypeError("checkout: ship_to.line2 malformed");
+    throw new TypeError("checkout: ship_to.line2 — Enter an apt / suite of 200 characters or fewer.");
   }
   if (s.city  && (typeof s.city  !== "string" || s.city.length  > 120)) {
-    throw new TypeError("checkout: ship_to.city malformed");
+    throw new TypeError("checkout: ship_to.city — Enter a city of 120 characters or fewer.");
   }
   return s;
 }
@@ -611,6 +678,18 @@ function create(deps) {
       if (!input || typeof input !== "object") throw new TypeError("checkout.confirm: input required");
       if (!input.customer || typeof input.customer !== "object") throw new TypeError("checkout.confirm: customer required");
       var email = _email(input.customer.customer_email || input.customer.email);
+      // guardEmail.sanitize is a content-safety gate (CRLF smuggling,
+      // homoglyphs, multi-@) — it passes a plain non-address string
+      // through unchanged, so the shape gate lives here: a single @, a
+      // dotted domain, the RFC 5321 length cap. Customer-facing message —
+      // the checkout form echoes it on the field.
+      if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email) || email.length > 254) {
+        throw new TypeError("checkout: customer.email — Enter a valid email address.");
+      }
+      var custName = input.customer.name;
+      if (custName != null && (typeof custName !== "string" || custName.length > 120)) {
+        throw new TypeError("checkout: customer.name — Enter a name of 120 characters or fewer.");
+      }
       if (!input.selected_shipping_id) throw new TypeError("checkout.confirm: selected_shipping_id required");
       var idempotencyKey = input.idempotency_key;
       if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8) {

package/lib/security-middleware.js

@@ -193,9 +193,25 @@ function clientKey(req) {
  * Options, etc.) stays ON. Pass-through to the framework primitive — we
  * compose its `documentPolicy: false` override, never patch the vendored
  * tree.
+ *
+ * `referrerPolicy: "same-origin"` overrides the vendored `no-referrer`
+ * default. Under `no-referrer`, browsers serialize the Origin header as
+ * the opaque string "null" on same-origin NAVIGATIONAL form POSTs (Fetch
+ * spec: a no-referrer referrer policy opaques the Origin on non-GET
+ * navigations). The CSRF gate's origin pre-check refuses "null" before
+ * the double-submit token is read, so every checkout / sign-in / account
+ * / admin form submit 403s in a real browser — while loopback tests,
+ * which send no Origin header at all, pass. `same-origin` keeps the
+ * external privacy posture identical (no referrer ever leaves the site)
+ * while restoring a real Origin on same-origin POSTs, which the gate
+ * verifies against PUBLIC_ORIGINS. Cross-site and sandboxed-iframe
+ * submits still arrive with a foreign or "null" Origin and are still
+ * refused — the defense is unchanged; only the false positive is gone.
+ * The Worker emits the same policy (worker/index.js _SECURITY_HEADERS)
+ * so both substrates stay header-consistent.
  */
 function securityHeadersOpts() {
-  return { documentPolicy: false };
+  return { documentPolicy: false, referrerPolicy: "same-origin" };
 }
 
 // ---- route-scoped CSP (payment processors + CAPTCHA providers) ----------

package/lib/storefront.js

@@ -2218,6 +2218,25 @@ function _fieldFromValidatorError(e, modulePrefix, formFields) {
   return { field: field, message: raw.replace(prefixRe, "") };
 }
 
+// Checkout's validators throw dotted container paths — "checkout:
+// ship_to.<field> <reason>" / "checkout: customer.<field> <reason>" — so the
+// shared extractor above (whose <field> token is undotted) can't map them to
+// the checkout form's flat input names. This strips the container segment
+// (and the em-dash separator the checkout messages carry) and maps the inner
+// token to the form's fields; non-form internals return null so only the
+// page-top banner shows for them.
+var _CHECKOUT_FORM_FIELDS = {
+  email: 1, name: 1, line1: 1, line2: 1, city: 1, state: 1, postal: 1, country: 1,
+};
+function _checkoutFieldFromError(e) {
+  var raw = (e && e.message) || "";
+  var m = /^checkout(?:\.\w+)?:\s+(?:ship_to|customer)\.([a-z_0-9]+)\b/.exec(raw);
+  var field = m && m[1];
+  if (!field || !Object.prototype.hasOwnProperty.call(_CHECKOUT_FORM_FIELDS, field)) return null;
+  var message = raw.replace(/^checkout(?:\.\w+)?:\s+(?:ship_to|customer)\.[a-z_0-9]+\s*(?:—|-)?\s*/, "");
+  return { field: field, message: message || "Please check this field." };
+}
+
 // Build the aria-invalid + aria-describedby attribute fragment for an input
 // when `inv` (a { field, message } from _fieldFromValidatorError) names this
 // field. Empty string otherwise. `idPrefix` + field is the static, escaped id.
@@ -6388,29 +6407,46 @@ var CART_LINE_EDITABLE =
 // same labelled-input builder the account address book uses) so the
 // checkout + saved-address forms collect an identical address shape.
 // `p` pre-fills each field (from a signed-in customer's default shipping
-// address); every value is escaped by `_addrField` / the email builder.
+// address, or the shopper's own typed values on a validation re-render);
+// every value is escaped by `_addrField` / the email builder.
 // Street line 1 + city are marked required for the common physical-goods
-// path; the backend (checkout._shipTo) is authoritative and treats them
-// as optional so a digital-only order still completes.
-function _checkoutShippingFields(p) {
+// path, and the POST handler enforces the same set server-side via
+// _requireCheckoutFields (backend validates, frontend displays). The
+// service tier (checkout._shipTo) stays presence-optional so a non-form
+// caller can still complete a digital-only order with a bare country.
+function _checkoutShippingFields(p, inv) {
   p = p || {};
   var esc = b.template.escapeHtml;
+  // Merge the per-field invalid marker (a { field, message } from
+  // _checkoutFieldFromError) into a field's opts when it is the one the
+  // backend validator rejected. Static "co-err-<name>" id — attacker-
+  // uncontrolled. Mirrors _addressForm's _mark.
+  function _mark(name, opts) {
+    if (inv && inv.field === name) {
+      opts.invalid = true;
+      opts.error_id = "co-err-" + name;
+      opts.error_msg = inv.message;
+    }
+    return opts;
+  }
   var email =
     "<label class=\"form-field\">" +
       "<span class=\"form-field__label\">Email <span class=\"form-field__req\" aria-hidden=\"true\">*</span><span class=\"sr-only\">(required)</span></span>" +
-      "<input type=\"email\" name=\"email\" value=\"" + esc(p.email == null ? "" : String(p.email)) + "\" required autocomplete=\"email\">" +
+      "<input type=\"email\" name=\"email\" value=\"" + esc(p.email == null ? "" : String(p.email)) + "\" required autocomplete=\"email\"" +
+        _fieldAriaAttr("co-err-", "email", inv) + ">" +
+      _fieldErrorSpan("co-err-", "email", inv) +
     "</label>";
   return email +
-    _addrField("name",  "Full name",      p.name,  { required: true, maxlength: 120, autocomplete: "name" }) +
-    _addrField("line1", "Street address", p.line1, { required: true, maxlength: 200, autocomplete: "address-line1" }) +
-    _addrField("line2", "Apt / suite / unit (optional)", p.line2, { maxlength: 200, autocomplete: "address-line2" }) +
+    _addrField("name",  "Full name",      p.name,  _mark("name",  { required: true, maxlength: 120, autocomplete: "name" })) +
+    _addrField("line1", "Street address", p.line1, _mark("line1", { required: true, maxlength: 200, autocomplete: "address-line1" })) +
+    _addrField("line2", "Apt / suite / unit (optional)", p.line2, _mark("line2", { maxlength: 200, autocomplete: "address-line2" })) +
     "<div class=\"form-row form-row--inline\">" +
-      _addrField("city",  "City", p.city, { required: true, maxlength: 120, autocomplete: "address-level2" }) +
-      _addrField("state", "State / province code", p.state, { maxlength: 5, pattern: "[A-Za-z0-9]{1,5}", autocomplete: "address-level1" }) +
+      _addrField("city",  "City", p.city, _mark("city", { required: true, maxlength: 120, autocomplete: "address-level2" })) +
+      _addrField("state", "State / province code", p.state, _mark("state", { maxlength: 5, pattern: "[A-Za-z0-9]{1,5}", autocomplete: "address-level1" })) +
     "</div>" +
     "<div class=\"form-row form-row--inline\">" +
-      _addrField("postal",  "Postal code", p.postal, { maxlength: 16, autocomplete: "postal-code" }) +
-      _addrField("country", "Country (ISO 3166-1)", p.country || "US", { required: true, maxlength: 2, pattern: "[A-Za-z]{2}", autocomplete: "country" }) +
+      _addrField("postal",  "Postal code", p.postal, _mark("postal", { maxlength: 16, autocomplete: "postal-code" })) +
+      _addrField("country", "Country (ISO 3166-1)", p.country || "US", _mark("country", { required: true, maxlength: 2, pattern: "[A-Za-z]{2}", autocomplete: "country" })) +
     "</div>";
 }
 
@@ -6432,6 +6468,41 @@ function _shipToFromBody(body) {
   };
 }
 
+// Required fields for the checkout FORM path, enforced before confirm so an
+// empty field gets its own per-field error instead of a service-tier shape
+// failure deeper in. The service tier (checkout._shipTo) keeps presence
+// optional — a digital-only order legitimately ships nothing — but the
+// storefront form marks email / name / line1 / city required, and the
+// backend enforces the same contract (backend validates, frontend
+// displays). US + Canada additionally need a region code and postal code:
+// both feed destination tax math. Throws in the same "checkout:
+// <container>.<field> — <message>" shape as the service tier so
+// _checkoutFieldFromError maps each to its input. The PayPal create route
+// shares _shipToFromBody but not this gate — its format errors surface
+// through the same service-tier validators.
+function _requireCheckoutFields(body, shipTo) {
+  if (!body.email || !String(body.email).trim()) {
+    throw new TypeError("checkout: customer.email — Enter your email address.");
+  }
+  if (!body.name || !String(body.name).trim()) {
+    throw new TypeError("checkout: customer.name — Enter the recipient's full name.");
+  }
+  if (!shipTo.line1) throw new TypeError("checkout: ship_to.line1 — Enter a street address.");
+  if (!shipTo.city)  throw new TypeError("checkout: ship_to.city — Enter a city.");
+  if (shipTo.country === "US" || shipTo.country === "CA") {
+    if (!shipTo.state) {
+      throw new TypeError(shipTo.country === "US"
+        ? "checkout: ship_to.state — Enter a US state or territory code (e.g. CA)."
+        : "checkout: ship_to.state — Enter a Canadian province code (e.g. ON).");
+    }
+    if (!shipTo.postal) {
+      throw new TypeError(shipTo.country === "US"
+        ? "checkout: ship_to.postal — Enter a ZIP code."
+        : "checkout: ship_to.postal — Enter a postal code.");
+    }
+  }
+}
+
 // Checkout mirrors the cart's two-column shell: the shipping form on the
 // left, a sticky order-summary rail on the right. The summary lists the
 // cart line items + a full Subtotal → tax → shipping → discount → Total
@@ -6470,6 +6541,13 @@ var CHECKOUT_PAGE =
   "  </div>\n" +
   "</section>\n";
 
+// Splice anchor for the optional checkout sub-blocks (pickup picker, gift
+// options, loyalty redeem, CAPTCHA). They insert BEFORE this literal so
+// they land inside the form, above the submit row — appending before
+// "</form>" instead would orphan them below the CTA. Must stay
+// byte-identical to the action-row line in CHECKOUT_PAGE above.
+var CHECKOUT_ACTIONS_ANCHOR = "        <div class=\"form-actions\">";
+
 // One order-summary line item in the checkout rail: thumbnail + title +
 // qty + line total, mirroring the cart row but compact. `l` is the raw
 // cart line; `lookup` is the variant_id → { product, hero_media } map the
@@ -6531,9 +6609,9 @@ function _checkoutGiftFields(opts) {
     (hasWrap
       ? "<p class=\"checkout-gift__note\">A gift wrap is in your cart. Add a message and recipient below.</p>"
       : "<p class=\"checkout-gift__note\">Sending this as a gift? Add a message and recipient. (Choose a gift wrap on the cart page.)</p>") +
-    "<label class=\"form-field\"><span>Recipient name <small>(optional)</small></span>" +
+    "<label class=\"form-field\"><span class=\"form-field__label\">Recipient name <span class=\"small\">(optional)</span></span>" +
       "<input type=\"text\" name=\"gift_recipient_name\" maxlength=\"120\" autocomplete=\"off\"></label>" +
-    "<label class=\"form-field\"><span>Gift message <small>(optional)</small></span>" +
+    "<label class=\"form-field\"><span class=\"form-field__label\">Gift message <span class=\"small\">(optional)</span></span>" +
       "<textarea name=\"gift_message\" rows=\"3\" maxlength=\"500\" placeholder=\"Add a note for the recipient\"></textarea></label>" +
     "<label class=\"form-field form-field--check\"><input type=\"checkbox\" name=\"gift_hide_prices\" value=\"1\">" +
       "<span>Hide prices on the packing slip (gift receipt)</span></label>" +
@@ -6558,7 +6636,7 @@ function _checkoutPickupPicker(opts) {
     }).join("");
   return "<fieldset class=\"checkout-pickup\">" +
     "<legend>Delivery method</legend>" +
-    "<label class=\"form-field\"><span>How would you like to get your order?</span>" +
+    "<label class=\"form-field\"><span class=\"form-field__label\">How would you like to get your order?</span>" +
       "<select name=\"pickup_location_code\">" + options + "</select></label>" +
     "<p class=\"checkout-pickup__note\">Choose a store to pick up in person, or ship to your address. Shipping is still quoted on the total.</p>" +
     "</fieldset>";
@@ -6620,44 +6698,42 @@ function renderCheckoutForm(opts) {
   var inlineError = opts.inline_error
     ? "<p class=\"auth-form__message auth-form__message--err\" role=\"alert\">" + b.template.escapeHtml(String(opts.inline_error)) + "</p>"
     : "";
-  var body = _render(CHECKOUT_PAGE, {})
-    .replace("RAW_TOTALS_ROWS", totalsRows)
-    .replace("RAW_SUMMARY_NOTE", summaryNote)
-    .replace("RAW_INLINE_ERROR", inlineError)
-    .replace("RAW_SHIPPING_FIELDS", _checkoutShippingFields(opts.prefill))
-    .replace("RAW_SUMMARY_LINES", summaryLines);
-  // CAPTCHA challenge inside the form — when the operator has an active
-  // provider (opts.captcha_kind + opts.captcha_public_key set), the widget
-  // renders just above the submit button so its hidden token field rides the
-  // form POST. Absent a provider this is "" — the checkout is byte-identical
-  // to the unconfigured store. The route-scoped CSP that admits the provider
-  // SDK host is set by the GET/POST /checkout handlers.
-  if (checkoutCaptcha) {
-    body = body.replace("</form>", checkoutCaptcha + "</form>");
-  }
-  // Pick-up-in-store location picker + gift personalization fields, appended
-  // into the form (container-only). Spliced via _spliceRaw so an operator
-  // free-text location name carrying a `$` can't trip dollar substitution.
-  var checkoutPickup = _checkoutPickupPicker(opts);
-  if (checkoutPickup) {
-    body = _spliceRaw(body, "</form>", checkoutPickup + "</form>");
+  // Every RAW_* swap goes through _spliceRaw: the shipping fields echo
+  // customer-typed values on a validation re-render and the summary lines
+  // carry operator product titles — a `$&`/"$`" in either would corrupt
+  // the document via String.replace dollar substitution. `opts.
+  // invalid_field` (a { field, message } from _checkoutFieldFromError)
+  // marks the one rejected input with aria-invalid + a per-field error
+  // span; null renders the no-error form byte-identically.
+  var body = _render(CHECKOUT_PAGE, {});
+  body = _spliceRaw(body, "RAW_TOTALS_ROWS", totalsRows);
+  body = _spliceRaw(body, "RAW_SUMMARY_NOTE", summaryNote);
+  body = _spliceRaw(body, "RAW_INLINE_ERROR", inlineError);
+  body = _spliceRaw(body, "RAW_SHIPPING_FIELDS", _checkoutShippingFields(opts.prefill, opts.invalid_field));
+  body = _spliceRaw(body, "RAW_SUMMARY_LINES", summaryLines);
+  // Pick-up-in-store picker, gift personalization, loyalty redeem, and the
+  // CAPTCHA widget are spliced in ABOVE the submit action row — inside the
+  // form in reading order, never after the CTA where they render as an
+  // orphaned block below the button. Order: delivery method, gift options,
+  // loyalty redeem, then the CAPTCHA directly above the button so its
+  // hidden token field rides the form POST. Each builder returns "" when
+  // its feature isn't wired, so an unconfigured store's checkout is
+  // byte-identical. Spliced via _spliceRaw (never String.replace) so an
+  // operator free-text location name carrying a `$` can't trip dollar
+  // substitution. The loyalty block's balance + value are numbers we
+  // control and the conversion ratio is the ledger's own constant; it
+  // renders only when there's a balance to spend.
+  var preActions = _checkoutPickupPicker(opts) + _checkoutGiftFields(opts);
+  if (opts.loyalty_balance && opts.loyalty_balance.balance > 0) {
+    preActions += _loyaltyCheckoutField(opts.loyalty_balance, opts.loyalty_points_per_usd);
   }
-  var checkoutGift = _checkoutGiftFields(opts);
-  if (checkoutGift) {
-    body = body.replace("</form>", checkoutGift + "</form>");
+  // The route-scoped CSP that admits the CAPTCHA provider SDK host is set
+  // by the GET/POST /checkout handlers.
+  if (checkoutCaptcha) {
+    preActions += checkoutCaptcha;
   }
-  // Signed-in customer with a spendable points balance — surface a
-  // redeem-at-checkout field. The block is appended as raw HTML (the
-  // balance + value are numbers we control, the conversion ratio is the
-  // ledger's own constant) so it slots into the existing form via a
-  // small client island that copies the field into the POST. Rendered
-  // only when there's a balance to spend; absent that the checkout is
-  // unchanged for guests + zero-balance customers.
-  if (opts.loyalty_balance && opts.loyalty_balance.balance > 0) {
-    body = body.replace(
-      "</form>",
-      _loyaltyCheckoutField(opts.loyalty_balance, opts.loyalty_points_per_usd) + "</form>",
-    );
+  if (preActions) {
+    body = _spliceRaw(body, CHECKOUT_ACTIONS_ANCHOR, preActions + CHECKOUT_ACTIONS_ANCHOR);
   }
   // When PayPal is configured, append its button below the card form. The
   // block is built as raw HTML (appended after the strict render) so the SDK
@@ -12235,6 +12311,7 @@ function mount(router, deps) {
       }
       var shipTo = _shipToFromBody(body);
       try {
+        _requireCheckoutFields(body, shipTo);
         // default_shipping_id may be a literal string or an
         // operator-supplied async resolver (e.g. backed by the
         // config primitive) so re-reads happen per request without
@@ -12303,6 +12380,34 @@ function mount(router, deps) {
             }
           } catch (_re) { /* fall through to the styled error page */ }
         }
+        // A validation TypeError naming one of the form's own fields is the
+        // shopper's to fix in place: re-render the shipping form with that
+        // field marked (aria-invalid + adjacent error span) and every typed
+        // value preserved. Guests have no saved-address prefill, so the POST
+        // body is the only source of what they typed — echo it (escaped at
+        // the field builder). Totals re-render as the estimate (confirmedTo
+        // null): the rejected address can't be priced, and re-pricing
+        // against it would just re-throw the same validator.
+        if (e instanceof TypeError) {
+          var invField = _checkoutFieldFromError(e);
+          if (invField) {
+            try {
+              var vLines = await _repriceCartLines(await deps.cart.listLines(c.id));
+              if (vLines.length) {
+                _setCheckoutCsp(res);
+                var vOpts = await _checkoutRenderOpts(req, c, vLines,
+                  "Some shipping details need a correction — check the highlighted field.", null);
+                vOpts.prefill = {
+                  email: body.email, name: body.name,
+                  line1: body.line1, line2: body.line2, city: body.city,
+                  state: body.state, postal: body.postal, country: body.country,
+                };
+                vOpts.invalid_field = invField;
+                return _send(res, 400, renderCheckoutForm(vOpts));
+              }
+            } catch (_re) { /* fall through to the styled error page */ }
+          }
+        }
         // A malformed address shape (TypeError) is still the shopper's to
         // fix; anything else is a server-side failure. Either way, render a
         // styled, recoverable page rather than raw text — back to the cart,