@blamejs/blamejs-shop 0.3.57 → 0.3.58

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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.

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.57",
+  "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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.57",
+  "version": "0.3.58",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {