@blamejs/blamejs-shop 0.3.10 → 0.3.12

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.12 (2026-05-30) — **Currency and outbound-host validation consolidated behind one shared check.** Input validation that was duplicated across the codebase is now a single shared module. Currency codes are validated against the ISO 4217 catalog consistently wherever the admin binds money — the same check the gift-card flow gained last release — and the outbound webhook host guard (refusing loopback, private, link-local, reserved, and cloud-metadata destinations, including trailing-dot forms) is one shared function used by both the delivery and registration paths. The shared module composes the framework's Unicode codepoint catalog so free-text fields can reject control, bidi-override, and zero-width characters when needed. Behavior is equal-or-stricter than before; no operator action is required. **Changed:** *Currency validation is consistently ISO 4217* — Admin paths that bind a currency now validate it against the ISO 4217 catalog in one place, so a code that isn't a real currency is rejected consistently rather than only in some flows. · *Outbound-host SSRF guard is a single shared check* — The webhook delivery and registration paths now share one host guard — loopback, private (RFC 1918), link-local, reserved, and cloud-metadata addresses (by IP literal or known name, including trailing-dot forms) are refused identically on both, so the two can't drift apart.
+
+- v0.3.11 (2026-05-30) — **Webhook endpoints reject internal addresses; admin errors stay clean and typed.** Outbound webhook endpoints can no longer be pointed at loopback, private, link-local, or cloud-metadata addresses, closing a server-side request forgery path from operator-supplied URLs. Several admin endpoints that previously returned a 500 on bad input now return the correct 4xx — a duplicate slug or SKU is a 409 Conflict, a missing referenced record and malformed JSON are a 400 — and none of them echo internal database or parser text back in the response. Gift cards now reject a currency that isn't a real ISO 4217 code, and the returns refund action reports a malformed id the same way its sibling actions do. No configuration change is required; upgrading picks these up automatically. **Fixed:** *Admin errors return the right status and don't leak internals* — Creating a product, variant, or inventory row with a duplicate key now returns 409 Conflict instead of 500; attaching media to a missing product, and pasting malformed JSON into the shipping-zone editor, now return 400. None of these responses include raw database or JSON-parser text — the detail is a generic, operator-facing message and the underlying error is recorded server-side. The same applies to the receipt and packing-slip routes. · *Gift cards validate the currency* — Issuing a gift card with a currency that isn't a real ISO 4217 code is now rejected with a 400 instead of creating a card in a non-existent currency. · *Consistent error status for refunds* — The returns refund action reports a malformed return id with the same 400 its approve, receive, and reject siblings use; a well-formed id that doesn't exist is still a 404. **Security:** *Webhook endpoints can't target internal addresses* — A webhook endpoint URL that points at a loopback, private (RFC 1918), link-local, reserved, or cloud-metadata address — by IP literal or by a known name such as localhost, metadata.google.internal, or any *.internal host — is now refused when the subscription is created, on both the delivery and outbound-registration paths. A trailing-dot form of those hosts (for example localhost. or 169.254.169.254.) is normalized before the check so it can't slip past. Public https endpoints are unaffected.
+
 - v0.3.10 (2026-05-30) — **Order discounts are split across lines for accurate partial refunds.** When an order carries a cart-level discount, the admin console now records how that discount split across the order's lines — proportional to each line's value — so a later partial refund of one line knows that line's discounted share rather than the whole-order amount. A new read-only Discount splits screen shows the per-line breakdown for an order. This is back-office bookkeeping recorded after the order is placed; it has no effect on what the shopper is charged, and an order with no discount records nothing. **Added:** *Per-line discount allocation + admin view* — An order that carried an automatic cart discount now gets a recorded breakdown of how that discount split across its lines — proportional to each line's subtotal, summing exactly to the discount. A read-only Discount splits admin screen shows the breakdown for an order. The recording runs after the order is placed and never affects the charged amount; an order with no discount records nothing.
 
 - v0.3.9 (2026-05-30) — **Automatic discounts now apply at checkout.** The automatic-discount rules you define in the admin console — an amount or percentage off a cart that meets a threshold — now reduce the order total at checkout. When a rule matches, the discount is applied (capped so it never exceeds the order subtotal) and shown in the quote the shopper pays; when no rule matches, or none are defined, the total is exactly as before, so a store that has not set up rules is unaffected. The admin screen for managing rules already shipped; this wires it through to the checkout quote and the charge. **Added:** *Automatic cart discounts at checkout* — When a cart matches a configured automatic-discount rule, the checkout reduces the order total by the rule's saving — capped to the order subtotal so the total is never negative — and the reduced amount is what the shopper is charged. With no matching rule, or no rules defined, the order total is unchanged, so the change stays invisible until you set rules up; any rule-engine error degrades to no discount rather than blocking checkout.

package/lib/admin.js

@@ -33,6 +33,7 @@
 var pricing = require("./pricing");
 var collectionsModule = require("./collections");
 var quantityDiscountsModule = require("./quantity-discounts");
+var textGuard = require("./text-guard");
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
 var b = require("./vendor/blamejs");
@@ -411,7 +412,34 @@ function _wrap(handler, opts) {
       return result;
     } catch (e) {
       if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
-      return _problem(res, 500, "internal-error", (e && e.message) || String(e));
+      // Malformed JSON body — the body parser raises a SyntaxError whose
+      // message echoes the parser's position ("...JSON at position 1").
+      // Surface a clean 400 with a generic detail rather than leaking the
+      // parser internals (also the defense-in-depth net for any call site
+      // that JSON.parses an operator-supplied field without its own guard).
+      if (e instanceof SyntaxError) return _problem(res, 400, "bad-request", "Invalid JSON in request.");
+      // Storage-engine constraint violations reach here as plain Errors
+      // whose message names the table/column/SQL ("UNIQUE constraint
+      // failed: products.slug"). Map the class to a clean 4xx with a
+      // GENERIC operator-facing detail — never echo the table/column/SQL.
+      var msg = (e && e.message) || "";
+      if (/UNIQUE constraint failed/i.test(msg) || /FOREIGN KEY constraint failed/i.test(msg)) {
+        return _problem(res, 409, "conflict",
+          /FOREIGN KEY/i.test(msg) ? "A referenced record does not exist." : "That value is already in use.");
+      }
+      if (/(?:CHECK|NOT NULL) constraint failed/i.test(msg)) {
+        return _problem(res, 400, "bad-request", "A required value is missing or invalid.");
+      }
+      // Genuine unknown error — record it server-side via the framework
+      // audit (drop-silent) so operators can correlate, then return a
+      // generic 500 with NO detail. The raw message never reaches the
+      // client.
+      b.audit.safeEmit({
+        action:   AUDIT_NAMESPACE + "." + (opts.audit || "request") + ".error",
+        outcome:  "failure",
+        metadata: { message: msg || String(e) },
+      });
+      return _problem(res, 500, "internal-error");
     }
   };
 }
@@ -2455,6 +2483,7 @@ function mount(router, deps) {
         try {
           result = await _refundOrder(o, req.body || {});
         } catch (e) {
+          // allow:admin-5xx-echoes-raw-error-message — 502 surfaces the PAYMENT PROVIDER's refund-failure reason (e.g. "charge already refunded"), an operator-actionable upstream message, not a server/storage internal.
           return _problem(res, 502, "stripe-refund-failed", (e && e.message) || String(e));
         }
         _json(res, 200, result);
@@ -3017,12 +3046,11 @@ function mount(router, deps) {
     router.post("/admin/returns/:id/refund", _pageOrApi(false,
       W("return.refund", async function (req, res) {
         var body = req.body || {};
-        var rma;
-        try { rma = await returns.get(req.params.id); }
-        catch (e) {
-          if (e instanceof TypeError) return _problem(res, 404, "return-not-found", e.message);
-          throw e;
-        }
+        // A malformed rma id is a bad request, not a missing record — let
+        // the guardUuid TypeError surface as a clean 400 via _wrap, matching
+        // the approve/received/reject siblings. Only a well-formed id that
+        // resolves to no row (rma === null) is a genuine 404.
+        var rma = await returns.get(req.params.id);
         if (!rma) return _problem(res, 404, "return-not-found");
         var rmaCtx = await _rmaProviderContext(rma);
         // Provider-backed path: move money first, then record the RMA.
@@ -3032,6 +3060,7 @@ function mount(router, deps) {
           catch (e) {
             var ce = _returnsClientError(e);
             if (ce) return _problem(res, ce.status, ce.slug, e.message);
+            // allow:admin-5xx-echoes-raw-error-message — 502 surfaces the PAYMENT PROVIDER's refund-failure reason, an operator-actionable upstream message, not a server/storage internal.
             return _problem(res, 502, "provider-refund-failed", (e && e.message) || String(e));
           }
           _json(res, 200, result.rma);
@@ -4314,7 +4343,10 @@ function mount(router, deps) {
             shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
           }));
         }
-        return _problem(res, 500, "internal-error", (e && e.message) || String(e));
+        // Record the real error server-side; return a generic 500 with no
+        // detail so a renderer fault never echoes its internals to the client.
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.receipt.error", outcome: "failure", metadata: { message: (e && e.message) || String(e) } });
+        return _problem(res, 500, "internal-error");
       }
       _sendHtml(res, 200, _injectMasthead(html, await _shopMastheadHtml()));
     });
@@ -4335,7 +4367,10 @@ function mount(router, deps) {
             shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
           }));
         }
-        return _problem(res, 500, "internal-error", (e && e.message) || String(e));
+        // Record the real error server-side; return a generic 500 with no
+        // detail so a renderer fault never echoes its internals to the client.
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.packing_slip.error", outcome: "failure", metadata: { message: (e && e.message) || String(e) } });
+        return _problem(res, 500, "internal-error");
       }
       _sendHtml(res, 200, _injectMasthead(html, await _shopMastheadHtml()));
     });
@@ -4729,6 +4764,13 @@ function mount(router, deps) {
   // the amount; the giftcards primitive enforces the rest.
   async function _issueGiftCard(body) {
     var input = { currency: typeof body.currency === "string" ? body.currency.trim().toUpperCase() : body.currency };
+    // The giftcards primitive only shape-checks the currency (/^[A-Z]{3}$/),
+    // so a well-formed-but-nonexistent code like "ZZZ" would issue a card in
+    // a currency the rest of the shop can't price. Validate against the
+    // framework's ISO 4217 catalog (the same b.money.CURRENCIES surface the
+    // currency-rounding + display primitives compose) and refuse unknown
+    // codes with a clean 400.
+    textGuard.currencyCode(input.currency, "giftcards: currency");
     if (body.amount_minor != null && body.amount_minor !== "") {
       input.amount_minor = _strictMinorInt(body.amount_minor, "giftcards", "amount_minor (minor units)");
     }
@@ -5346,12 +5388,18 @@ function mount(router, deps) {
     // via the hidden marker so a partial JSON edit doesn't flip active.
     if (body.active_present === "1") patch.active = (body.active === "on" || body.active === "1");
     if (typeof body.regions_json === "string" && body.regions_json.trim() !== "") {
-      patch.regions = JSON.parse(body.regions_json);
+      // A pasted JSON blob that doesn't parse is operator input, not a
+      // server fault — throw a TypeError so both surfaces (bearer via
+      // _wrap, cookie via the htmlHandler's TypeError catch) degrade to a
+      // clean 400 instead of a 500 that echoes the parser's position.
+      try { patch.regions = JSON.parse(body.regions_json); }
+      catch (_e) { throw new TypeError("shippingZones: regions_json must be valid JSON"); }
     } else if (Array.isArray(body.regions)) {
       patch.regions = body.regions;
     }
     if (typeof body.rates_json === "string" && body.rates_json.trim() !== "") {
-      patch.rates = JSON.parse(body.rates_json);
+      try { patch.rates = JSON.parse(body.rates_json); }
+      catch (_e) { throw new TypeError("shippingZones: rates_json must be valid JSON"); }
     } else if (Array.isArray(body.rates)) {
       patch.rates = body.rates;
     }

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.10",
+  "version": "0.3.12",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/lib/currency-rounding.js

@@ -81,6 +81,7 @@
  */
 
 var b = require("./vendor/blamejs");
+var textGuard = require("./text-guard");
 
 // ---- constants ----------------------------------------------------------
 
@@ -97,20 +98,7 @@ var MAX_LIST_LIMIT = 500;
 // typo at config-time rather than at the first checkout that touches
 // the bad code.
 function _currency(code) {
-  if (typeof code !== "string" || !/^[A-Z]{3}$/.test(code)) {
-    throw new TypeError(
-      "currencyRounding: currency must be a 3-letter uppercase ISO 4217 code, got " +
-      JSON.stringify(code)
-    );
-  }
-  var catalog = b.money.CURRENCIES;
-  if (!Object.prototype.hasOwnProperty.call(catalog, code)) {
-    throw new TypeError(
-      "currencyRounding: currency " + JSON.stringify(code) +
-      " is not in the ISO 4217 catalog"
-    );
-  }
-  return code;
+  return textGuard.currencyCode(code, "currencyRounding: currency");
 }
 
 function _incrementMinor(n) {

package/lib/index.js

@@ -252,4 +252,5 @@ Object.assign(module.exports, {
   winbackCampaigns:      require("./winback-campaigns"),
   wishlistDigest:        require("./wishlist-digest"),
   operatorHelpCenter:    require("./operator-help-center"),
+  textGuard:             require("./text-guard"),
 });

package/lib/text-guard.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * @module shop.textGuard
+ * @title  Shop input-validation primitives over the framework's codepoint catalog
+ *
+ * @intro
+ *   One home for the cross-cutting string validators the shop's
+ *   handlers reach for at the request boundary: the ISO 4217 currency
+ *   code, the URL slug label, the outbound host label, and the
+ *   dangerous-codepoint screen for unconstrained free text. Each was
+ *   previously open-coded at several call sites with subtly different
+ *   shapes; centralizing them keeps the discipline identical
+ *   everywhere and gives the codebase one place to tighten.
+ *
+ *   The dangerous-codepoint surface (bidi overrides, C0 control bytes,
+ *   null bytes, zero-width / invisible formatting, mixed-script
+ *   confusables) is NOT reinvented here — it composes the framework's
+ *   own codepoint catalog, the single source of truth the guard-*
+ *   family already builds on. The framework does not yet re-export the
+ *   catalog on its public index; until it does, this module reaches
+ *   the catalog leaf directly. The leaf has no dependency on any shop
+ *   module, so requiring it is refresh-safe; an upstream one-line
+ *   `module.exports` add would let this collapse to `b.codepointClass`
+ *   with no behavior change.
+ *
+ *   Validators THROW a `TypeError` on bad input. The admin / account
+ *   request wrappers map a thrown `TypeError` to a clean 400, so a
+ *   typo or a hostile value surfaces as a bad-request to the caller
+ *   instead of a 500 — the validators are written to be called at the
+ *   handler boundary, before the value reaches storage or an outbound
+ *   dial.
+ *
+ *   Surface:
+ *     - re-exports of the framework codepoint catalog (BIDI_RE,
+ *       C0_CTRL_RE, ZERO_WIDTH_RE, NULL_BYTE, scriptFor,
+ *       detectMixedScripts, detectCharThreats, assertNoCharThreats,
+ *       applyCharStripPolicies) so consumers grab one import
+ *     - asciiUpperLetters(s, label, n?) — fixed-length A-Z token
+ *     - currencyCode(s, label?) — ISO 4217 shape + catalog membership
+ *     - slugLabel(s, label, opts?) — lowercase URL-slug label
+ *     - hostLabel(host, label?) — outbound host SSRF + by-name denylist
+ *     - freeText(s, label, policy?) — dangerous-codepoint screen for
+ *       unconstrained UTF-8 text fields
+ *
+ * @primitive textGuard
+ * @related   b.money, b.ssrfGuard, b.safeUrl, shop.currencyRounding,
+ *            shop.webhooks, shop.webhookSubscriptions
+ */
+
+var b = require("./vendor/blamejs");
+
+// The framework's codepoint catalog (bidi / control / null / zero-width
+// tables + regexes, the script ranges, and the detect/assert/strip
+// helpers the guard-* family composes). It is not on the framework's
+// public index yet; the catalog leaf has no shop-module dependency, so
+// composing it directly stays refresh-safe and keeps a single source of
+// truth instead of a second copy of the tables.
+// allow:vendor-hand-edit — composing the framework's codepoint catalog leaf (no shop dependency, refresh-safe); collapses to b.codepointClass once upstream re-exports it
+var codepointClass = require("./vendor/blamejs/lib/codepoint-class");
+
+// ---- shop validators ----------------------------------------------------
+
+// asciiUpperLetters(s, label, n?) — exactly `n` (default 3) ASCII
+// uppercase letters, nothing else. The generalized shape behind every
+// `/^[A-Z]{3}$/` token check. ASCII-allowlist by construction, so bidi
+// / control / zero-width / confusable codepoints are rejected for free
+// (they are not in A-Z). Throws TypeError on a miss.
+function asciiUpperLetters(s, label, n) {
+  var name = label || "value";
+  var len = n == null ? 3 : n;
+  if (typeof len !== "number" || !Number.isInteger(len) || len <= 0) {
+    throw new TypeError("textGuard: length must be a positive integer, got " + JSON.stringify(n));
+  }
+  // allow:dynamic-regex — len is a validated positive integer, not external input
+  var re = new RegExp("^[A-Z]{" + len + "}$");
+  if (typeof s !== "string" || !re.test(s)) {
+    throw new TypeError(
+      name + " must be exactly " + len + " uppercase ASCII letter(s), got " + JSON.stringify(s)
+    );
+  }
+  return s;
+}
+
+// currencyCode(s, label?) — ISO 4217 currency code: the asciiUpperLetters
+// shape check THEN membership in the framework's catalog (b.money.CURRENCIES,
+// the same surface currency-rounding + currency-display compose). Rejects
+// both malformed codes ("usd", "US") and well-formed-but-nonexistent codes
+// ("ZZZ") that would shape-check past `/^[A-Z]{3}$/` but bind money to a
+// currency the rest of the shop can't price. Throws TypeError on a miss.
+function currencyCode(s, label) {
+  var name = label || "currency";
+  if (typeof s !== "string" || !/^[A-Z]{3}$/.test(s)) {
+    throw new TypeError(
+      name + " must be a 3-letter uppercase ISO 4217 code, got " + JSON.stringify(s)
+    );
+  }
+  if (!Object.prototype.hasOwnProperty.call(b.money.CURRENCIES, s)) {
+    throw new TypeError(name + " " + JSON.stringify(s) + " is not in the ISO 4217 catalog");
+  }
+  return s;
+}
+
+// slugLabel(s, label, opts?) — a lowercase URL-slug label: starts and
+// ends with [a-z0-9], inner chars [a-z0-9-], no leading / trailing /
+// doubled hyphen, length 1..maxLen (default 80). ASCII-allowlist, so
+// dangerous codepoints are rejected by construction. Throws TypeError.
+function slugLabel(s, label, opts) {
+  var name = label || "slug";
+  opts = opts || {};
+  var maxLen = opts.maxLen == null ? 80 : opts.maxLen;
+  if (typeof maxLen !== "number" || !Number.isInteger(maxLen) || maxLen <= 0) {
+    throw new TypeError("textGuard: maxLen must be a positive integer, got " + JSON.stringify(opts.maxLen));
+  }
+  if (typeof s !== "string" || s.length < 1 || s.length > maxLen) {
+    throw new TypeError(
+      name + " must be a 1.." + maxLen + "-character lowercase slug, got " + JSON.stringify(s)
+    );
+  }
+  // Single char must itself be [a-z0-9]; longer must match start/inner/end.
+  var ok = s.length === 1
+    ? /^[a-z0-9]$/.test(s)
+    : /^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(s);
+  if (!ok || /--/.test(s)) {
+    throw new TypeError(
+      name + " must be a lowercase URL slug ([a-z0-9] separated by single hyphens), got " + JSON.stringify(s)
+    );
+  }
+  return s;
+}
+
+// Hostnames that name an internal / metadata destination by name rather
+// than by IP literal. The cloud-metadata services answer on a hostname as
+// well as the 169.254.169.254 link-local IP; localhost resolves to
+// loopback. A literal-IP host is classified directly via b.ssrfGuard
+// (no DNS); these names cover the by-name reach of the same targets.
+var BLOCKED_HOSTS = Object.freeze({
+  "localhost":                1,
+  "metadata.google.internal": 1,
+});
+
+// hostLabel(host, label?) — refuse an outbound host that targets an
+// internal / loopback / link-local / reserved / cloud-metadata
+// destination. A literal-IP host is classified via b.ssrfGuard.classify
+// (IPv4 + IPv6 + IPv4-mapped, no DNS); a hostname is matched against the
+// by-name metadata / loopback denylist plus the *.internal suffix. A
+// trailing FQDN dot and IPv6 brackets are stripped first so neither check
+// is evaded. DNS-rebinding (a public name resolving to a private IP) is
+// out of scope at this gate by design — the resolving guard belongs on
+// the delivery dial. Throws TypeError when the host is not allowed.
+// Returns the normalized (bracket / trailing-dot stripped, lowercased)
+// host on success.
+function hostLabel(host, label) {
+  var name = label || "host";
+  if (typeof host !== "string" || host.length === 0) {
+    throw new TypeError(name + " must be a non-empty string");
+  }
+  var h = host.replace(/^\[|\]$/g, "").toLowerCase().replace(/\.+$/, "");
+  if (b.ssrfGuard.classify(h) ||
+      BLOCKED_HOSTS[h] ||
+      h === "internal" || /\.internal$/.test(h)) {
+    throw new TypeError(name + " is not allowed (internal/loopback/metadata address)");
+  }
+  return h;
+}
+
+// freeText(s, label, policy?) — the dangerous-codepoint screen for an
+// UNCONSTRAINED UTF-8 text field (customer note, review body, gift
+// message, product Q&A). Unlike the ASCII-allowlist validators above,
+// these fields legitimately carry arbitrary letters, so the codepoint
+// catalog is the right backing: bidi overrides (CVE-2021-42574 Trojan
+// Source), null bytes, and C0 control characters are refused by default;
+// zero-width / invisible formatting is refused when policy.zeroWidth is
+// "reject"; a mixed-script confusable (Cyrillic 'а' inside an otherwise
+// Latin label) is refused when policy.mixedScript is "reject". Throws
+// TypeError on a refused codepoint. Returns the input on success.
+function freeText(s, label, policy) {
+  var name = label || "value";
+  if (typeof s !== "string") {
+    throw new TypeError(name + " must be a string");
+  }
+  policy = policy || {};
+  var bidiP    = policy.bidi    || "reject";
+  var nullP    = policy.nullByte || "reject";
+  var controlP = policy.control || "reject";
+  if (bidiP === "reject" && codepointClass.BIDI_RE.test(s)) {
+    throw new TypeError(name + " contains a Unicode bidi override (CVE-2021-42574 Trojan Source)");
+  }
+  if (nullP === "reject" && s.indexOf(codepointClass.NULL_BYTE) !== -1) {
+    throw new TypeError(name + " contains a null byte");
+  }
+  if (controlP === "reject" && codepointClass.C0_CTRL_RE.test(s)) {
+    throw new TypeError(name + " contains a C0 control character");
+  }
+  if (policy.zeroWidth === "reject" && codepointClass.ZERO_WIDTH_RE.test(s)) {
+    throw new TypeError(name + " contains a zero-width / invisible formatting character");
+  }
+  if (policy.mixedScript === "reject") {
+    var scripts = codepointClass.detectMixedScripts(s, policy.allowedScripts);
+    if (scripts) {
+      throw new TypeError(
+        name + " mixes writing systems (" + scripts.join(", ") + ") — possible confusable / homograph"
+      );
+    }
+  }
+  return s;
+}
+
+module.exports = {
+  // Re-exports of the framework codepoint catalog (single source of truth).
+  BIDI_RE:                codepointClass.BIDI_RE,
+  C0_CTRL_RE:             codepointClass.C0_CTRL_RE,
+  ZERO_WIDTH_RE:          codepointClass.ZERO_WIDTH_RE,
+  NULL_BYTE:              codepointClass.NULL_BYTE,
+  BOM_CHAR:               codepointClass.BOM_CHAR,
+  scriptFor:              codepointClass.scriptFor,
+  detectMixedScripts:     codepointClass.detectMixedScripts,
+  detectCharThreats:      codepointClass.detectCharThreats,
+  assertNoCharThreats:    codepointClass.assertNoCharThreats,
+  applyCharStripPolicies: codepointClass.applyCharStripPolicies,
+
+  // Shop validators.
+  asciiUpperLetters: asciiUpperLetters,
+  currencyCode:      currencyCode,
+  slugLabel:         slugLabel,
+  hostLabel:         hostLabel,
+  freeText:          freeText,
+};

package/lib/webhook-subscriptions.js

@@ -49,6 +49,7 @@
  */
 
 var b = require("./vendor/blamejs");
+var textGuard = require("./text-guard");
 
 var OWNER_TYPES         = Object.freeze(["operator", "app", "customer"]);
 var MAX_OWNER_ID_LEN    = 200;
@@ -125,12 +126,27 @@ function _endpointUrl(url) {
   }
   // safeUrl.parse defaults to ALLOW_HTTP_TLS (https only). The framework
   // refuses http:// + non-http schemes + user:pass@ userinfo + bracketed
-  // raw-IP forms at this gate — no separate validation needed here.
+  // raw-IP forms at this gate.
+  var parsed;
   try {
-    b.safeUrl.parse(url);
+    parsed = b.safeUrl.parse(url);
   } catch (e) {
     throw new TypeError("webhookSubscriptions: endpoint_url — " + (e && e.message || "rejected"));
   }
+  // SSRF: refuse internal / loopback / link-local / cloud-metadata
+  // destinations so a registered subscription can't probe the host's own
+  // network or the instance-credential metadata service. textGuard.hostLabel
+  // classifies a literal-IP host via the framework SSRF guard (no DNS) and
+  // matches a hostname against the by-name metadata / loopback denylist plus
+  // the *.internal suffix, after stripping a trailing FQDN dot + IPv6
+  // brackets so neither check is evaded. DNS-rebinding (a public name
+  // resolving to a private IP) is out of scope here by design — the
+  // resolving guard belongs on the delivery dial.
+  try {
+    textGuard.hostLabel(parsed.hostname, "webhookSubscriptions: endpoint_url host");
+  } catch (_e) {
+    throw new TypeError("webhookSubscriptions: endpoint_url host is not allowed (internal/loopback/metadata address)");
+  }
   return url;
 }
 

package/lib/webhooks.js

@@ -37,6 +37,7 @@
  */
 
 var b = require("./vendor/blamejs");
+var textGuard = require("./text-guard");
 
 var C = b.constants;
 
@@ -91,11 +92,28 @@ function _validateUrl(url) {
   }
   // Refuse http:// outright for outbound — the framework's safe-url
   // parser carries the ALLOW_HTTP_TLS preset that admits only https.
+  var parsed;
   try {
-    b.safeUrl.parse(url, { allowedProtocols: ["https:"] });
+    parsed = b.safeUrl.parse(url, { allowedProtocols: ["https:"] });
   } catch (e) {
     throw new TypeError("webhooks: url must be https:// — " + (e && e.message || "rejected"));
   }
+  // SSRF: refuse any internal / loopback / link-local / cloud-metadata
+  // destination so a registered receiver can't be turned into a probe of
+  // the host's own network or the instance-credential metadata service.
+  // textGuard.hostLabel classifies a literal-IP host directly via the
+  // framework SSRF guard (loopback / private / link-local / reserved /
+  // cloud-metadata, IPv4 + IPv6 + IPv4-mapped) and matches a hostname
+  // against the by-name metadata / loopback denylist plus the *.internal
+  // suffix, after stripping a trailing FQDN dot + IPv6 brackets so neither
+  // check is evaded. DNS-rebinding (a public name that resolves to a
+  // private IP) is OUT OF SCOPE here by design — the resolving guard
+  // belongs on the delivery dial.
+  try {
+    textGuard.hostLabel(parsed.hostname, "webhooks: url host");
+  } catch (_e) {
+    throw new TypeError("webhooks: url host is not allowed (internal/loopback/metadata address)");
+  }
 }
 
 function _validateEvents(events) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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": {