@blamejs/blamejs-shop 0.4.21 → 0.4.23

package/lib/operator-audit-log.js

@@ -84,6 +84,11 @@ var SHA3_512_HEX_LEN      = 128;
 
 var ZERO_HASH = "0".repeat(SHA3_512_HEX_LEN);
 
+// Canonical prefix for the bytes a checkpoint signs. Stable forever —
+// changing it invalidates every prior checkpoint signature. Mirrors the
+// framework audit chain's "blamejs-audit-checkpoint-v1" format.
+var CHECKPOINT_FORMAT = "blamejs-operator-audit-checkpoint-v1";
+
 var ALLOWED_ACTOR_TYPES = Object.freeze(["operator", "system", "app"]);
 var ALLOWED_UA_CLASSES  = Object.freeze([
   "browser",
@@ -581,6 +586,152 @@ function create(opts) {
     return { ok: true, rows_verified: rows.length, last_hash: prevHash };
   }
 
+  // -- checkpoint anchoring ----------------------------------------------
+  //
+  // The hash chain is tamper-EVIDENT against a single edited/deleted row,
+  // but an attacker who can rewrite the whole table can re-hash from a
+  // forged genesis and leave the chain internally consistent. Anchoring
+  // the tip with a post-quantum signature over the head row_hash — keyed
+  // off the framework's b.auditSign keypair, whose private half never
+  // touches D1 — closes that hole: a full-chain rewrite can't reproduce a
+  // valid checkpoint signature over the rewritten tip.
+  //
+  // checkpoint() signs the CURRENT head and inserts an anchor row.
+  // verifyCheckpoints() re-derives every anchor's signature and confirms
+  // the anchored row still carries the signed hash. Both no-op gracefully
+  // when b.auditSign isn't initialized (the chain stays hash-linked; the
+  // signature layer is simply absent) so a deployment without the
+  // audit-signing keypair still records + verifies the linkage.
+
+  function _auditSignReady() {
+    try { b.auditSign.getPublicKeyFingerprint(); return true; }
+    catch (_e) { return false; }
+  }
+
+  // Canonical signed bytes for a checkpoint. STABLE FOREVER — changing
+  // this layout invalidates every prior checkpoint signature.
+  function _checkpointPayload(atRowId, atOccurredAt, atRowHash, createdAt) {
+    return Buffer.from(
+      CHECKPOINT_FORMAT + "\n" +
+      atRowId + "\n" +
+      String(atOccurredAt) + "\n" +
+      atRowHash + "\n" +
+      String(createdAt),
+      "utf8",
+    );
+  }
+
+  // Anchor the current chain tip with a fresh PQC signature. Returns the
+  // inserted checkpoint row, or null when the chain is empty (nothing to
+  // anchor) or `skipIfUnchanged` and the tip hasn't advanced since the
+  // last checkpoint. Throws OperatorAuditCheckpointSigningUnavailable-
+  // shaped TypeError only if asked to checkpoint without a signing key —
+  // callers that want a soft skip check `signingAvailable()` first.
+  async function checkpoint(checkpointOpts) {
+    checkpointOpts = checkpointOpts || {};
+    if (!_auditSignReady()) {
+      throw new TypeError("operatorAuditLog.checkpoint: b.auditSign is not initialized — " +
+        "no signing key to anchor the chain with");
+    }
+    var head = await _currentHead();
+    if (head.id === null) return null;  // empty chain — nothing to anchor
+
+    if (checkpointOpts.skipIfUnchanged) {
+      var last = await query(
+        "SELECT at_row_hash FROM operator_audit_checkpoints " +
+        "ORDER BY created_at DESC, id DESC LIMIT 1",
+        [],
+      );
+      if (last.rows.length && last.rows[0].at_row_hash === head.row_hash) {
+        return null;  // already anchored at this exact tip
+      }
+    }
+
+    var createdAt = _now();
+    var payload   = _checkpointPayload(head.id, head.occurred_at, head.row_hash, createdAt);
+    var signature = b.auditSign.sign(payload).toString("base64");
+    var pubFp     = b.auditSign.getPublicKeyFingerprint();
+    var id        = b.uuid.v7();
+
+    await query(
+      "INSERT INTO operator_audit_checkpoints " +
+      "(id, created_at, at_row_id, at_occurred_at, at_row_hash, signature, public_key_fingerprint) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+      [id, createdAt, head.id, head.occurred_at, head.row_hash, signature, pubFp],
+    );
+
+    return {
+      id:                     id,
+      created_at:             createdAt,
+      at_row_id:              head.id,
+      at_occurred_at:         head.occurred_at,
+      at_row_hash:            head.row_hash,
+      public_key_fingerprint: pubFp,
+    };
+  }
+
+  // Walk every checkpoint oldest-first, re-derive its signature, and
+  // confirm the anchored row still carries the signed hash. Reports the
+  // first divergence — a forged signature, a key-rotation fingerprint
+  // mismatch, a vanished anchor row, or a rewritten tip whose hash no
+  // longer matches what was signed.
+  async function verifyCheckpoints() {
+    if (!_auditSignReady()) {
+      return { ok: true, checkpoints_verified: 0, reason: "audit-sign-unavailable" };
+    }
+    var r = await query(
+      "SELECT * FROM operator_audit_checkpoints ORDER BY created_at ASC, id ASC",
+      [],
+    );
+    var rows = r.rows;
+    if (!rows.length) return { ok: true, checkpoints_verified: 0 };
+
+    var currentFp  = b.auditSign.getPublicKeyFingerprint();
+    var currentPub = b.auditSign.getPublicKey();
+
+    for (var i = 0; i < rows.length; i += 1) {
+      var c = rows[i];
+      // Only the current key verifies (no key-history table). A rotation
+      // without re-signing surfaces here rather than silently failing.
+      if (c.public_key_fingerprint !== currentFp) {
+        return {
+          ok: false, checkpoints_verified: i, break_at: i, checkpoint_id: c.id,
+          reason: "public key fingerprint mismatch (key rotated without re-signing?)",
+          expected: currentFp, actual: c.public_key_fingerprint,
+        };
+      }
+      var payload = _checkpointPayload(c.at_row_id, Number(c.at_occurred_at), c.at_row_hash, Number(c.created_at));
+      var sigBuf;
+      try { sigBuf = Buffer.from(c.signature, "base64"); }
+      catch (_e) {
+        return { ok: false, checkpoints_verified: i, break_at: i, checkpoint_id: c.id,
+          reason: "checkpoint signature not decodable" };
+      }
+      if (!b.auditSign.verify(payload, sigBuf, currentPub)) {
+        return { ok: false, checkpoints_verified: i, break_at: i, checkpoint_id: c.id,
+          reason: "post-quantum signature failed" };
+      }
+      // The anchored row must still exist AND still carry the signed hash.
+      // A full-chain rewrite changes row_hash → this mismatch is the catch.
+      var anchored = await query(
+        "SELECT row_hash FROM operator_audit_events WHERE id = ?1 LIMIT 1",
+        [c.at_row_id],
+      );
+      if (!anchored.rows.length) {
+        return { ok: false, checkpoints_verified: i, break_at: i, checkpoint_id: c.id,
+          reason: "anchored audit row missing (id=" + c.at_row_id + ")" };
+      }
+      if (anchored.rows[0].row_hash !== c.at_row_hash) {
+        return {
+          ok: false, checkpoints_verified: i, break_at: i, checkpoint_id: c.id,
+          reason: "anchored row_hash mismatch — operator_audit_events was rewritten",
+          expected: c.at_row_hash, actual: anchored.rows[0].row_hash,
+        };
+      }
+    }
+    return { ok: true, checkpoints_verified: rows.length };
+  }
+
   return {
     MAX_ACTOR_ID_LEN:      MAX_ACTOR_ID_LEN,
     MAX_ACTION_LEN:        MAX_ACTION_LEN,
@@ -593,12 +744,20 @@ function create(opts) {
     ALLOWED_UA_CLASSES:    ALLOWED_UA_CLASSES,
     ZERO_HASH:             ZERO_HASH,
 
-    record:         record,
-    listByActor:    listByActor,
-    listByResource: listByResource,
-    searchAction:   searchAction,
-    chainHead:      chainHead,
-    verifyChain:    verifyChain,
+    record:            record,
+    listByActor:       listByActor,
+    listByResource:    listByResource,
+    searchAction:      searchAction,
+    chainHead:         chainHead,
+    verifyChain:       verifyChain,
+    // Checkpoint anchoring — sign the chain tip out-of-band so a
+    // full-chain rewrite (which verifyChain alone can't catch) becomes
+    // detectable. `signingAvailable()` lets callers soft-skip when the
+    // audit-signing key isn't initialized.
+    checkpoint:        checkpoint,
+    verifyCheckpoints: verifyCheckpoints,
+    signingAvailable:  _auditSignReady,
+    CHECKPOINT_FORMAT: CHECKPOINT_FORMAT,
   };
 }
 
@@ -614,4 +773,5 @@ module.exports = {
   ALLOWED_ACTOR_TYPES:   ALLOWED_ACTOR_TYPES,
   ALLOWED_UA_CLASSES:    ALLOWED_UA_CLASSES,
   ZERO_HASH:             ZERO_HASH,
+  CHECKPOINT_FORMAT:     CHECKPOINT_FORMAT,
 };

package/lib/order-export.js

@@ -212,7 +212,8 @@ function _limit(n) {
 // RFC-4180 quoting: every cell wrapped in `"`, embedded `"` doubled.
 // We quote unconditionally — the cost is a few extra bytes per cell;
 // the win is that a downstream parser never has to track quote-vs-
-// bare-cell state for a column with mixed shapes.
+// bare-cell state for a column with mixed shapes. The injection
+// neutralization runs first via the shared vendored primitive.
 function _csvCell(value) {
   var s = _coerceCell(value);
   s = _neutralizeInjection(s);
@@ -227,23 +228,19 @@ function _coerceCell(value) {
   return JSON.stringify(value);
 }
 
-// Numeric-with-sign detector — `+15.00` / `-3.50` / `+0` parse as
-// legitimate amounts and should pass through unmolested. The
-// detector rejects anything with embedded whitespace or trailing
-// non-numeric tail so `+15 SUM(A1)` still gets escaped.
-var _NUMERIC_SIGN_RE = /^[+-](?:\d+(?:\.\d+)?|\.\d+)$/;
-
-// CSV injection neutralization — see OWASP "CSV Injection". A cell
-// beginning with `=`, `+`, `-`, or `@` is interpreted as a formula
-// by most spreadsheet renderers. The defense is to prefix with `'`
-// so the renderer treats the cell as literal text. Signed numerics
-// are the deliberate exception (legitimate amount strings).
+// CSV injection neutralization — composes the vendored b.guardCsv.escapeCell
+// (OWASP "CSV Injection" defense). The vendored primitive is the single
+// shared neutralizer across every CSV export surface (order-export +
+// customer-segments). It prefixes a leading TAB when a cell starts with ANY
+// formula-trigger char — `= + - @` AND the tab / CR / LF / pipe / full-width
+// variants a hand-rolled `= + - @`-only check misses. A leading tab renders
+// as invisible whitespace in a spreadsheet, so the cell reads as text and
+// never evaluates as a formula. The earlier in-tree check exempted signed
+// numerics (`+15.00`); the shared primitive prefixes those too (the safe
+// OWASP posture — `-2+3+cmd|…` is a real injection that begins like an
+// amount), which is the more complete behavior this consolidation buys.
 function _neutralizeInjection(s) {
-  if (s.length === 0) return s;
-  var first = s.charAt(0);
-  if (first !== "=" && first !== "+" && first !== "-" && first !== "@") return s;
-  if ((first === "+" || first === "-") && _NUMERIC_SIGN_RE.test(s)) return s;
-  return "'" + s;
+  return b.guardCsv.escapeCell(s);
 }
 
 function _csvRow(cells) {

package/lib/payment.js

@@ -8,9 +8,15 @@
  *   verification (HMAC-SHA256 over `<timestamp>.<body>` with
  *   `whsec_...` secret, ±5 min tolerance, constant-time compare) and
  *   outbound API calls (PaymentIntent create / retrieve / confirm /
- *   cancel + Refund) composed on `b.httpClient` (SSRF-gated, retried,
- *   circuit-broken, ALPN HTTP/2). No `stripe` npm dep — every byte is
- *   either node built-in or vendored blamejs primitive.
+ *   cancel + Refund) on `b.httpClient` (SSRF-gated, response-capped,
+ *   ALPN HTTP/2). Each adapter instance wraps its dials in a per-upstream
+ *   `b.circuitBreaker` plus a bounded `b.retry` (the latter only on
+ *   idempotent dials — GET reads + idempotency-keyed writes — so a
+ *   transient blip never re-sends a one-shot charge). While the breaker is
+ *   open the dial fast-fails with `code: "CIRCUIT_OPEN"` BEFORE the
+ *   request, so checkout renders the recoverable payment-unavailable page
+ *   rather than stranding an order mid-charge. No `stripe` npm dep — every
+ *   byte is either node built-in or vendored blamejs primitive.
  *
  *   Future Adyen / Mollie / Paddle adapters land as additional
  *   factory functions returning the same `{ verifyWebhook,
@@ -48,6 +54,59 @@ var STRIPE_WEBHOOK_TOLERANCE = 300;   // ± 5 minutes (Stripe default)
 var STRIPE_HTTP_TIMEOUT_MS   = 15000;
 var CURRENCY_RE              = /^[a-z]{3}$/;   // Stripe wants lowercase ISO 4217
 
+// ---- PSP dial resilience (circuit breaker + bounded retry) ----------------
+//
+// b.httpClient does NOT itself circuit-break or retry — it SSRF-gates, caps,
+// and pools, but the failure-threshold breaker + backoff retry are separate
+// primitives a consumer composes around it. Each adapter instance owns ONE
+// breaker per upstream (Stripe / PayPal): per-target is the only correct
+// scope — sharing a breaker across unrelated peers defeats the
+// failure-threshold semantic.
+//
+// Open-circuit posture: while the breaker is open every dial fast-fails with
+// a plain Error carrying `code: "CIRCUIT_OPEN"` (NOT a TypeError), so the
+// storefront's checkout handler renders it through the existing recoverable
+// "checkout didn't go through" page — the same structured payment-unavailable
+// surface a raw upstream 5xx already produces — rather than charging or
+// 400-ing a field. Nothing is captured: the breaker fails BEFORE the dial, so
+// no order is stranded mid-charge.
+//
+// Retry rides ONLY on idempotent dials — GET reads and writes carrying an
+// idempotency key (Stripe Idempotency-Key / PayPal-Request-Id). A
+// keyless POST is sent exactly once: re-driving it could double-charge.
+var BREAKER_FAILURE_THRESHOLD = 5;                 // consecutive failures before opening
+var BREAKER_COOLDOWN_MS       = C.TIME.seconds(30); // open → half-open probe delay
+var BREAKER_SUCCESS_THRESHOLD = 2;                 // half-open probes to re-close
+var DIAL_RETRY_MAX_ATTEMPTS   = 3;                 // total tries incl. first (idempotent only)
+var DIAL_RETRY_BASE_DELAY_MS  = 200;
+var DIAL_RETRY_MAX_DELAY_MS   = C.TIME.seconds(2);
+
+// One breaker per adapter instance. `idempotent` selects whether the dial
+// also rides the bounded backoff retry — the breaker counts the retry loop's
+// FINAL outcome as a single call (b.retry.withBreaker), so a transient blip
+// that the retry rides out never inflates the failure counter.
+function _makeBreaker(name) {
+  return b.circuitBreaker.create({
+    name:             name,
+    failureThreshold: BREAKER_FAILURE_THRESHOLD,
+    cooldownMs:       BREAKER_COOLDOWN_MS,
+    successThreshold: BREAKER_SUCCESS_THRESHOLD,
+  });
+}
+
+function _dial(breaker, idempotent, fn) {
+  if (!breaker) return fn();
+  if (!idempotent) return breaker.wrap(fn);
+  return b.retry.withBreaker(fn, {
+    breaker: breaker,
+    retry:   {
+      maxAttempts: DIAL_RETRY_MAX_ATTEMPTS,
+      baseDelayMs: DIAL_RETRY_BASE_DELAY_MS,
+      maxDelayMs:  DIAL_RETRY_MAX_DELAY_MS,
+    },
+  });
+}
+
 // Stripe holds idempotency keys for 24h, so the local cache row
 // expires on the same window — operators who run `cleanupExpired()`
 // on a daily schedule keep the table small without ever shortening
@@ -196,33 +255,47 @@ async function _stripeCall(opts, method, path, params, idempotencyKey) {
     headers["idempotency-key"] = idempotencyKey;
   }
   var httpClient = opts.httpClient || b.httpClient;
-  var res = await httpClient.request({
-    method:    method,
-    url:       url,
-    headers:   headers,
-    body:      body || undefined,
-    timeoutMs: opts.timeoutMs || STRIPE_HTTP_TIMEOUT_MS,
-    agent:     _PSP_TLS_AGENT,
+  // A GET read is always idempotent; a write is idempotent only when it
+  // carries an Idempotency-Key (Stripe dedupes a replay of the SAME key
+  // server-side). A keyless POST rides the breaker but NOT the retry, so
+  // a transient blip never re-sends it (double-charge guard).
+  var idempotent = method === "GET" || !!idempotencyKey;
+  // The HTTP request AND the non-2xx → throw both run INSIDE the dialed
+  // closure so the breaker counts a 5xx / transport error as a failure
+  // (and the idempotent-path retry retries it). A 4xx is the request's
+  // fault, not the peer's health — `err.statusCode` makes the retry
+  // classifier skip it, and a 4xx still increments the breaker, which is
+  // acceptable since a sustained stream of 4xx is itself a degraded state.
+  var json = await _dial(opts._breaker, idempotent, async function () {
+    var res = await httpClient.request({
+      method:    method,
+      url:       url,
+      headers:   headers,
+      body:      body || undefined,
+      timeoutMs: opts.timeoutMs || STRIPE_HTTP_TIMEOUT_MS,
+      agent:     _PSP_TLS_AGENT,
+    });
+    var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+    var parsed = null;
+    try { parsed = text.length ? JSON.parse(text) : {}; } catch (_e) { parsed = { _raw: text }; }
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      var err = new Error("stripe: " + method + " " + path + " → HTTP " + res.statusCode +
+                          (parsed && parsed.error && parsed.error.message ? " — " + parsed.error.message : ""));
+      err.code = (parsed && parsed.error && parsed.error.code) || "STRIPE_HTTP_" + res.statusCode;
+      err.statusCode = res.statusCode;
+      err.stripe = parsed && parsed.error || null;
+      err._stripeRawText   = text;
+      err._stripeStatus    = res.statusCode;
+      throw err;
+    }
+    // Carry the raw status + serialised body alongside the parsed JSON
+    // so the idempotency layer can persist them verbatim for replay
+    // without re-stringifying (preserves byte-for-byte fidelity with
+    // what Stripe returned, including field ordering).
+    Object.defineProperty(parsed, "_stripeStatus",  { value: res.statusCode, enumerable: false });
+    Object.defineProperty(parsed, "_stripeRawText", { value: text,           enumerable: false });
+    return parsed;
   });
-  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
-  var json = null;
-  try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = { _raw: text }; }
-  if (res.statusCode < 200 || res.statusCode >= 300) {
-    var err = new Error("stripe: " + method + " " + path + " → HTTP " + res.statusCode +
-                        (json && json.error && json.error.message ? " — " + json.error.message : ""));
-    err.code = (json && json.error && json.error.code) || "STRIPE_HTTP_" + res.statusCode;
-    err.statusCode = res.statusCode;
-    err.stripe = json && json.error || null;
-    err._stripeRawText   = text;
-    err._stripeStatus    = res.statusCode;
-    throw err;
-  }
-  // Carry the raw status + serialised body alongside the parsed JSON
-  // so the idempotency layer can persist them verbatim for replay
-  // without re-stringifying (preserves byte-for-byte fidelity with
-  // what Stripe returned, including field ordering).
-  Object.defineProperty(json, "_stripeStatus",  { value: res.statusCode, enumerable: false });
-  Object.defineProperty(json, "_stripeRawText", { value: text,           enumerable: false });
   return json;
 }
 
@@ -330,6 +403,13 @@ function stripe(opts) {
     throw new TypeError("payment: now must be a function returning current epoch ms");
   }
 
+  // One circuit breaker per adapter instance, guarding every Stripe dial.
+  // Stashed on opts so the module-level `_stripeCall` reaches it without a
+  // signature change. Skippable in tests via `breaker: false`.
+  if (opts._breaker === undefined) {
+    opts._breaker = opts.breaker === false ? null : _makeBreaker("psp-stripe");
+  }
+
   // Idempotency state shared across every mutating call. When `query`
   // is not supplied the primitive runs in legacy mode — every
   // mutating call goes straight to Stripe, no cache writes, no
@@ -349,6 +429,11 @@ function stripe(opts) {
   return {
     name: "stripe",
 
+    // The per-adapter circuit breaker (or null when disabled). Exposed so
+    // an operator dashboard can read `breaker.getState()` ("closed" /
+    // "open" / "half") and reset it after a confirmed recovery.
+    breaker: opts._breaker,
+
     verifyWebhook: function (headers, rawBody, vOpts) {
       return _verifyWebhook(headers, rawBody, opts.webhookSecret, vOpts);
     },
@@ -648,28 +733,33 @@ async function _paypalToken(opts, state) {
   if (state.token && now < state.tokenExpiresAt) return state.token;
   var httpClient = opts.httpClient || b.httpClient;
   var basic = Buffer.from(opts.clientId + ":" + opts.secret).toString("base64");
-  var res = await httpClient.request({
-    method:  "POST",
-    url:     _paypalApiBase(opts) + "/v1/oauth2/token",
-    headers: {
-      "authorization":  "Basic " + basic,
-      "accept":         "application/json",
-      "content-type":   "application/x-www-form-urlencoded",
-      "user-agent":     "blamejs-shop (zero-dep)",
-    },
-    body:      "grant_type=client_credentials",
-    timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
-    agent:     _PSP_TLS_AGENT,
+  // The client-credentials token exchange is idempotent (re-asking for a
+  // token is always safe), so it rides the breaker AND the bounded retry.
+  var json = await _dial(opts._breaker, true, async function () {
+    var res = await httpClient.request({
+      method:  "POST",
+      url:     _paypalApiBase(opts) + "/v1/oauth2/token",
+      headers: {
+        "authorization":  "Basic " + basic,
+        "accept":         "application/json",
+        "content-type":   "application/x-www-form-urlencoded",
+        "user-agent":     "blamejs-shop (zero-dep)",
+      },
+      body:      "grant_type=client_credentials",
+      timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
+      agent:     _PSP_TLS_AGENT,
+    });
+    var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+    var parsed; try { parsed = text.length ? JSON.parse(text) : {}; } catch (_e) { parsed = {}; }
+    if (res.statusCode < 200 || res.statusCode >= 300 || !parsed.access_token) {
+      var err = new Error("paypal: OAuth2 token exchange failed → HTTP " + res.statusCode +
+                          (parsed && parsed.error_description ? " — " + parsed.error_description : ""));
+      err.code = "PAYPAL_AUTH_" + res.statusCode;
+      err.statusCode = res.statusCode;
+      throw err;
+    }
+    return parsed;
   });
-  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
-  var json; try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = {}; }
-  if (res.statusCode < 200 || res.statusCode >= 300 || !json.access_token) {
-    var err = new Error("paypal: OAuth2 token exchange failed → HTTP " + res.statusCode +
-                        (json && json.error_description ? " — " + json.error_description : ""));
-    err.code = "PAYPAL_AUTH_" + res.statusCode;
-    err.statusCode = res.statusCode;
-    throw err;
-  }
   state.token = json.access_token;
   var ttlMs = (typeof json.expires_in === "number" ? json.expires_in : 0) * 1000; // allow:raw-time-literal — PayPal expires_in is a runtime seconds value; *1000 → ms
   state.tokenExpiresAt = now + Math.max(0, ttlMs - PAYPAL_TOKEN_SKEW_MS);
@@ -688,26 +778,34 @@ async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
   var body = bodyObj != null ? JSON.stringify(bodyObj) : undefined;
   if (body) headers["content-length"] = Buffer.byteLength(body, "utf8");
   var httpClient = opts.httpClient || b.httpClient;
-  var res = await httpClient.request({
-    method:    method,
-    url:       _paypalApiBase(opts) + path,
-    headers:   headers,
-    body:      body,
-    timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
-    agent:     _PSP_TLS_AGENT,
+  // A GET is idempotent; a write is idempotent only when it carries a
+  // PayPal-Request-Id (PayPal dedupes a replay of the SAME id, and the
+  // same id rides every retry attempt within one call). A keyless write
+  // rides the breaker but not the retry.
+  var idempotent = method === "GET" || !!requestId;
+  var json = await _dial(opts._breaker, idempotent, async function () {
+    var res = await httpClient.request({
+      method:    method,
+      url:       _paypalApiBase(opts) + path,
+      headers:   headers,
+      body:      body,
+      timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
+      agent:     _PSP_TLS_AGENT,
+    });
+    var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+    var parsed; try { parsed = text.length ? JSON.parse(text) : {}; } catch (_e) { parsed = { _raw: text }; }
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      var detail = parsed && (parsed.message || (parsed.details && parsed.details[0] && parsed.details[0].description)) || "";
+      var err = new Error("paypal: " + method + " " + path + " → HTTP " + res.statusCode + (detail ? " — " + detail : ""));
+      err.code = (parsed && parsed.name) || "PAYPAL_HTTP_" + res.statusCode;
+      err.statusCode = res.statusCode;
+      err.paypal = parsed || null;
+      throw err;
+    }
+    Object.defineProperty(parsed, "_paypalStatus",  { value: res.statusCode, enumerable: false });
+    Object.defineProperty(parsed, "_paypalRawText", { value: text,           enumerable: false });
+    return parsed;
   });
-  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
-  var json; try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = { _raw: text }; }
-  if (res.statusCode < 200 || res.statusCode >= 300) {
-    var detail = json && (json.message || (json.details && json.details[0] && json.details[0].description)) || "";
-    var err = new Error("paypal: " + method + " " + path + " → HTTP " + res.statusCode + (detail ? " — " + detail : ""));
-    err.code = (json && json.name) || "PAYPAL_HTTP_" + res.statusCode;
-    err.statusCode = res.statusCode;
-    err.paypal = json || null;
-    throw err;
-  }
-  Object.defineProperty(json, "_paypalStatus",  { value: res.statusCode, enumerable: false });
-  Object.defineProperty(json, "_paypalRawText", { value: text,           enumerable: false });
   return json;
 }
 
@@ -721,6 +819,13 @@ function paypal(opts) {
   if (opts.now != null && typeof opts.now !== "function") {
     throw new TypeError("payment: now must be a function returning current epoch ms");
   }
+  // One circuit breaker per adapter instance, guarding every PayPal dial
+  // (the token exchange + every Orders-v2 call). Skippable in tests via
+  // `breaker: false`.
+  if (opts._breaker === undefined) {
+    opts._breaker = opts.breaker === false ? null : _makeBreaker("psp-paypal");
+  }
+
   var state = {
     query:          opts.query || null,
     now:            typeof opts.now === "function" ? opts.now : function () { return Date.now(); },
@@ -744,6 +849,10 @@ function paypal(opts) {
   return {
     name: "paypal",
 
+    // The per-adapter circuit breaker (or null when disabled). Same
+    // operator-dashboard surface as the Stripe adapter's.
+    breaker: opts._breaker,
+
     // Create an Orders-v2 order (intent CAPTURE). The returned `id` is the
     // PayPal order id the buyer approves; `captureOrder` finalizes it.
     createOrder: function (input, idempotencyKey) {

package/lib/security-middleware.js

@@ -58,11 +58,19 @@ var _vendoredSecurityHeaders = require("./vendor/blamejs/lib/middleware/security
 
 var C = b.constants;
 
-// Payment webhooks are server-to-server POSTs from Stripe / PayPal:
-// cross-site by nature, unthrottleable by a per-IP human budget, and
-// already authenticated by an HMAC signature the edge + container both
-// verify. They are exempt from BOTH the rate limiters and fetch-metadata.
-var WEBHOOK_PATHS = ["/api/webhooks/stripe", "/api/webhooks/paypal"];
+// Server-to-server webhooks: cross-site by nature, unthrottleable by a
+// per-IP human budget, and each authenticated by its own gate the handler
+// verifies first thing — an HMAC signature (Stripe / PayPal) or a per-
+// endpoint signing secret (the ESP bounce / complaint intake). They are
+// exempt from the rate limiters, fetch-metadata, and the double-submit CSRF
+// token (a third-party POST carries no session cookie or token). The
+// `/api/` prefix also lands them in the vendored bot-guard's onlyForHtml
+// skip, so the secret / signature gate is the deciding check.
+var WEBHOOK_PATHS = [
+  "/api/webhooks/stripe",
+  "/api/webhooks/paypal",
+  "/api/webhooks/mail-bounce",
+];
 
 // Liveness / readiness probe — the container's Docker HEALTHCHECK hits
 // this on a fixed cadence; never rate-limit it or a slow cold start