@blamejs/blamejs-shop 0.0.53 → 0.0.56

package/lib/payment.js

@@ -34,6 +34,20 @@ 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
 
+// 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
+// the replay window below Stripe's own retention.
+var IDEMPOTENCY_TTL_MS       = 24 * 60 * 60 * 1000;
+var IDEMPOTENCY_NAMESPACE    = "payment-idempotency-body";
+var IDEMPOTENT_OPERATIONS    = {
+  "payment_intent.create": true,
+  "refund.create":         true,
+  "subscription.create":   true,
+  "subscription.update":   true,
+  "subscription.cancel":   true,
+};
+
 // ---- validation -----------------------------------------------------------
 
 function _assertSecret(s, label) {
@@ -161,7 +175,8 @@ async function _stripeCall(opts, method, path, params, idempotencyKey) {
   if (idempotencyKey) {
     headers["idempotency-key"] = idempotencyKey;
   }
-  var res = await _b().httpClient.request({
+  var httpClient = opts.httpClient || _b().httpClient;
+  var res = await httpClient.request({
     method:    method,
     url:       url,
     headers:   headers,
@@ -177,17 +192,138 @@ async function _stripeCall(opts, method, path, params, idempotencyKey) {
     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;
 }
 
+// ---- Idempotency ----------------------------------------------------------
+//
+// Canonical-JSON hash. Stable across runtime, OS, node version: sort
+// every object key recursively, JSON.stringify the result, then run
+// through b.crypto.namespaceHash (SHA3-512). Arrays preserve order
+// (their order is semantically meaningful — `items[]` in a Stripe
+// subscription is an ordered list of line items).
+function _canonicalise(v) {
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) {
+    var out = [];
+    for (var i = 0; i < v.length; i += 1) out.push(_canonicalise(v[i]));
+    return out;
+  }
+  var keys = Object.keys(v).sort();
+  var obj  = {};
+  for (var k = 0; k < keys.length; k += 1) {
+    var val = v[keys[k]];
+    if (val === undefined) continue;
+    obj[keys[k]] = _canonicalise(val);
+  }
+  return obj;
+}
+
+function _canonicalHash(obj) {
+  var canonical = JSON.stringify(_canonicalise(obj == null ? {} : obj));
+  return _b().crypto.namespaceHash(IDEMPOTENCY_NAMESPACE, canonical);
+}
+
+function _assertIdempotencyKey(k) {
+  if (typeof k !== "string" || k.length < 8 || k.length > 255) {
+    throw new TypeError("payment: idempotency_key must be a string between 8 and 255 characters");
+  }
+}
+
+// Wraps a single Stripe mutating call in the idempotency cache.
+//
+//   1. Look up (idempotency_key). If present + same request_hash →
+//      replay the stored response verbatim. If present + DIFFERENT
+//      request_hash → throw (security: never let a same-key replay
+//      with a mutated body pass through).
+//   2. Otherwise, call Stripe via `doCall()`. On 2xx, INSERT the
+//      response row. On any throw, leave the cache empty — the next
+//      call with the same key retries cleanly.
+async function _runIdempotent(state, operation, key, requestObj, doCall) {
+  _assertIdempotencyKey(key);
+  if (!IDEMPOTENT_OPERATIONS[operation]) {
+    throw new TypeError("payment: unknown idempotent operation " + JSON.stringify(operation));
+  }
+  var query        = state.query;
+  var now          = state.now();
+  var requestHash  = _canonicalHash(requestObj);
+
+  // Replay lookup. The PRIMARY KEY index makes this an O(1) probe.
+  var existing = (await query(
+    "SELECT request_hash, response_status, response_body " +
+    "FROM payment_idempotency WHERE idempotency_key = ?1 LIMIT 1",
+    [key],
+  )).rows[0];
+
+  if (existing) {
+    if (existing.request_hash !== requestHash) {
+      // Same key, different body — refuse. Stripe itself would reject
+      // this on its own idempotency cache, but we surface a typed
+      // application error so the caller doesn't have to ship the
+      // request first to discover the collision.
+      throw new TypeError("payment: idempotency_key collision (different inputs)");
+    }
+    var replay = null;
+    try { replay = JSON.parse(existing.response_body); } catch (_e) { replay = { _raw: existing.response_body }; }
+    Object.defineProperty(replay, "_stripeStatus",  { value: Number(existing.response_status), enumerable: false });
+    Object.defineProperty(replay, "_replayed",      { value: true,                              enumerable: false });
+    return replay;
+  }
+
+  var result = await doCall();
+  var status = result && result._stripeStatus ? Number(result._stripeStatus) : 200;
+  var rawText = result && result._stripeRawText
+    ? result._stripeRawText
+    : JSON.stringify(result);
+
+  await query(
+    "INSERT INTO payment_idempotency " +
+    "(idempotency_key, operation, request_hash, response_status, response_body, created_at, expires_at) " +
+    "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+    [key, operation, requestHash, status, rawText, now, now + IDEMPOTENCY_TTL_MS],
+  );
+
+  return result;
+}
+
 // ---- adapter --------------------------------------------------------------
 
 function stripe(opts) {
   opts = opts || {};
   _assertSecret(opts.apiKey,        "apiKey");
   _assertSecret(opts.webhookSecret, "webhookSecret");
+  if (opts.query != null && typeof opts.query !== "function") {
+    throw new TypeError("payment: query must be a function (sql, params) => Promise<{ rows }>");
+  }
+  if (opts.now != null && typeof opts.now !== "function") {
+    throw new TypeError("payment: now must be a function returning current epoch ms");
+  }
+
+  // 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
+  // collision detection. Operators opt in by passing `query`.
+  var state = {
+    query: opts.query || null,
+    now:   typeof opts.now === "function" ? opts.now : function () { return Date.now(); },
+  };
+
+  function _maybeIdempotent(operation, idempotencyKey, requestObj, doCall) {
+    if (!state.query || idempotencyKey == null) {
+      return doCall();
+    }
+    return _runIdempotent(state, operation, idempotencyKey, requestObj, doCall);
+  }
 
   return {
     name: "stripe",
@@ -211,7 +347,9 @@ function stripe(opts) {
       if (input.metadata) params.metadata  = input.metadata;
       if (input.description) params.description = input.description;
       if (input.receipt_email) params.receipt_email = input.receipt_email;
-      return _stripeCall(opts, "POST", "/payment_intents", params, idempotencyKey);
+      return _maybeIdempotent("payment_intent.create", idempotencyKey, params, function () {
+        return _stripeCall(opts, "POST", "/payment_intents", params, idempotencyKey);
+      });
     },
 
     retrievePaymentIntent: function (id) {
@@ -246,7 +384,9 @@ function stripe(opts) {
         params.reason = input.reason;
       }
       if (input.metadata) params.metadata = input.metadata;
-      return _stripeCall(opts, "POST", "/refunds", params, idempotencyKey);
+      return _maybeIdempotent("refund.create", idempotencyKey, params, function () {
+        return _stripeCall(opts, "POST", "/refunds", params, idempotencyKey);
+      });
     },
 
     // Stripe Subscriptions API. Operators pre-create the recurring
@@ -270,7 +410,9 @@ function stripe(opts) {
         if (input.metadata) params.metadata = input.metadata;
         if (input.payment_behavior) params.payment_behavior = input.payment_behavior;
         if (input.expand) params.expand = input.expand;
-        return _stripeCall(opts, "POST", "/subscriptions", params, idempotencyKey);
+        return _maybeIdempotent("subscription.create", idempotencyKey, params, function () {
+          return _stripeCall(opts, "POST", "/subscriptions", params, idempotencyKey);
+        });
       },
 
       retrieve: function (id) {
@@ -281,22 +423,58 @@ function stripe(opts) {
       update: function (id, input, idempotencyKey) {
         _assertSecret(id, "subscription id");
         if (!input || typeof input !== "object") throw new TypeError("payment.subscriptions.update: input object required");
-        return _stripeCall(opts, "POST", "/subscriptions/" + encodeURIComponent(id), input, idempotencyKey);
+        // The hashed request body includes the subscription id so an
+        // update against a DIFFERENT subscription with the same key
+        // is detected as a collision (the id is part of the URL,
+        // not the body Stripe sees, but it's part of the semantic
+        // request — replaying against a different sub_ would be the
+        // same security hole as replaying with a different amount).
+        var hashBody = { _id: id, body: input };
+        return _maybeIdempotent("subscription.update", idempotencyKey, hashBody, function () {
+          return _stripeCall(opts, "POST", "/subscriptions/" + encodeURIComponent(id), input, idempotencyKey);
+        });
       },
 
       cancel: function (id, opts2, idempotencyKey) {
         _assertSecret(id, "subscription id");
         opts2 = opts2 || {};
-        if (opts2.at_period_end) {
-          // Stripe modeled "cancel at period end" as an UPDATE so the
-          // subscription stays active through the current billing
-          // window; DELETE is for immediate end-of-life.
-          return _stripeCall(opts, "POST", "/subscriptions/" + encodeURIComponent(id),
-                              { cancel_at_period_end: true }, idempotencyKey);
-        }
-        return _stripeCall(opts, "DELETE", "/subscriptions/" + encodeURIComponent(id), null, idempotencyKey);
+        var atPeriodEnd = !!opts2.at_period_end;
+        var hashBody = { _id: id, at_period_end: atPeriodEnd };
+        return _maybeIdempotent("subscription.cancel", idempotencyKey, hashBody, function () {
+          if (atPeriodEnd) {
+            // Stripe modeled "cancel at period end" as an UPDATE so the
+            // subscription stays active through the current billing
+            // window; DELETE is for immediate end-of-life.
+            return _stripeCall(opts, "POST", "/subscriptions/" + encodeURIComponent(id),
+                                { cancel_at_period_end: true }, idempotencyKey);
+          }
+          return _stripeCall(opts, "DELETE", "/subscriptions/" + encodeURIComponent(id), null, idempotencyKey);
+        });
       },
     },
+
+    // Purges every expired idempotency row. Operators wire this into
+    // a daily schedule (cron, scheduled Worker, etc.) — the table
+    // grows by at most one row per mutating call per 24h window and
+    // a daily sweep keeps the high-water mark bounded. Returns the
+    // number of rows removed so the operator can alert on a sudden
+    // spike.
+    cleanupExpired: async function () {
+      if (!state.query) {
+        throw new TypeError("payment.cleanupExpired: requires `query` factory opt — idempotency cache is opt-in");
+      }
+      var cutoff = state.now();
+      var r = await state.query(
+        "DELETE FROM payment_idempotency WHERE expires_at < ?1",
+        [cutoff],
+      );
+      // D1's DELETE result shape exposes `meta.changes`; fall back to
+      // `rowsAffected` for adapters that surface it differently.
+      if (r && r.meta && typeof r.meta.changes === "number") return r.meta.changes;
+      if (r && typeof r.rowsAffected === "number")           return r.rowsAffected;
+      if (r && typeof r.changes      === "number")           return r.changes;
+      return 0;
+    },
   };
 }
 
@@ -312,7 +490,9 @@ module.exports = {
   create:                    create,
   stripe:                    stripe,
   STRIPE_WEBHOOK_TOLERANCE:  STRIPE_WEBHOOK_TOLERANCE,
+  IDEMPOTENCY_TTL_MS:        IDEMPOTENCY_TTL_MS,
   // Exposed for tests + Worker to share form-encoding shape.
   _formEncode:               _formEncode,
   _verifyWebhook:            _verifyWebhook,
+  _canonicalHash:            _canonicalHash,
 };