@blamejs/blamejs-shop 0.0.53 → 0.0.54

package/lib/newsletter.js

@@ -9,7 +9,12 @@
  *     from the namespace `"newsletter-email"` + the normalised
  *     address (lowercased + trimmed) so two signups for the same
  *     mailbox collapse to a single row regardless of casing
- *     variation.
+ *     variation. Also keys the unsubscribe-token table off
+ *     `"newsletter-unsubscribe"` + the plaintext bearer.
+ *   - `b.crypto.generateBytes` + `b.crypto.toBase64Url` — opaque
+ *     unsubscribe token generation (24 bytes → 32 base64url chars).
+ *   - `b.crypto.timingSafeEqual` — constant-time comparison of the
+ *     supplied token hash against the stored row's hash on consume.
  *   - `b.uuid.v7` — row id.
  *
  * Surface:
@@ -18,19 +23,37 @@
  *   - `byEmailHash(hash)` — operator lookup.
  *   - `count()` — total non-unsubscribed signups (for the live
  *     newsletter-band stat the home page renders).
+ *   - `issueUnsubscribeToken(signup_id)` — mints a one-shot bearer
+ *     for the unsubscribe URL. The plaintext token is returned
+ *     once; the database stores only the namespaceHash. Default
+ *     expiry is one year from issuance.
+ *   - `consumeUnsubscribeToken(plaintext)` — single-use exchange.
+ *     Marks the token consumed and stamps
+ *     `newsletter_signups.unsubscribed_at` for the linked signup.
+ *     Returns a structured result with one of the error codes
+ *     `"not-found" | "already-consumed" | "expired"`, or `"ok"`
+ *     on success.
+ *   - `resubscribe({ email })` — clears `unsubscribed_at` for an
+ *     existing signup looked up by email hash.
  *
  * Storage:
  *   - `newsletter_signups` (migration `0010_newsletter_signups.sql`).
+ *   - `newsletter_unsubscribe_tokens`
+ *     (migration `0014_newsletter_unsubscribe_tokens.sql`).
  *
  * @primitive newsletter
- * @related   b.guardEmail, b.crypto.namespaceHash
+ * @related   b.guardEmail, b.crypto.namespaceHash,
+ *            b.crypto.timingSafeEqual
  */
 
 "use strict";
 
-var EMAIL_NAMESPACE = "newsletter-email";
-var MAX_SOURCE_LEN  = 64;
-var SOURCE_RE       = /^[a-z0-9][a-z0-9._-]{0,62}[a-z0-9]$/;
+var EMAIL_NAMESPACE         = "newsletter-email";
+var UNSUBSCRIBE_NAMESPACE   = "newsletter-unsubscribe";
+var UNSUBSCRIBE_TOKEN_BYTES = 24;
+var UNSUBSCRIBE_TTL_MS      = 365 * 24 * 60 * 60 * 1000;
+var MAX_SOURCE_LEN          = 64;
+var SOURCE_RE               = /^[a-z0-9][a-z0-9._-]{0,62}[a-z0-9]$/;
 
 // Lazy framework handle — matches the pattern used by the rest of
 // the shop primitives; avoids the `require` cycle that would arise
@@ -42,16 +65,37 @@ function _b() {
 }
 
 function _normalizeEmail(s) {
-  if (typeof s !== "string") {
-    throw new TypeError("newsletter: email must be a string");
+  if (typeof s !== "string" || !s.length) {
+    throw new TypeError("newsletter: email must be a non-empty string");
   }
   var trimmed = s.trim();
+  if (!trimmed.length) {
+    throw new TypeError("newsletter: email must be a non-empty string");
+  }
   // Defer the shape check to `b.guardEmail`. The guard refuses
-  // control bytes, empty input, oversized input, and RFC-shape
-  // violations; we just hand it through with the trim already
-  // applied so the canonical form lands in storage.
-  var checked = _b().guardEmail(trimmed, { profile: "strict" });
-  return checked.toLowerCase();
+  // control bytes, oversized input, header-injection sequences,
+  // and RFC-shape violations. `validate` surfaces a structured
+  // `{ ok, issues }` report; we re-raise the first issue's
+  // snippet so the caller gets a precise refusal reason rather
+  // than the generic sanitize message.
+  var guardEmail = _b().guardEmail;
+  var report;
+  try {
+    report = guardEmail.validate(trimmed, { profile: "strict" });
+  } catch (e) {
+    throw new TypeError("newsletter: email — " + (e && e.message || "invalid email"));
+  }
+  if (!report || report.ok === false) {
+    var first = (report && report.issues && report.issues[0]) || {};
+    throw new TypeError("newsletter: email — " + (first.snippet || first.ruleId || "refused at strict profile"));
+  }
+  var canonical;
+  try {
+    canonical = guardEmail.sanitize(trimmed, { profile: "strict" });
+  } catch (e) {
+    throw new TypeError("newsletter: email — " + (e && e.message || "refused"));
+  }
+  return canonical.toLowerCase();
 }
 
 function _normalizeSource(s) {
@@ -134,6 +178,126 @@ function create(opts) {
       );
       return Number((r.rows[0] || {}).n || 0);
     },
+
+    // Mint a single-use opaque bearer for the unsubscribe URL. The
+    // plaintext is returned ONCE — the database stores only its
+    // namespaceHash, so re-issuance is impossible (and a leak of
+    // the storage layer never reveals the live links the operator
+    // emailed out). Caller is responsible for delivering the
+    // plaintext through the transactional-email primitive.
+    issueUnsubscribeToken: async function (signupId) {
+      if (typeof signupId !== "string" || !signupId.length) {
+        throw new TypeError("newsletter.issueUnsubscribeToken: signup_id required");
+      }
+      var row = (await query(
+        "SELECT id FROM newsletter_signups WHERE id = ?1 LIMIT 1",
+        [signupId],
+      )).rows[0];
+      if (!row) {
+        throw new TypeError("newsletter.issueUnsubscribeToken: signup_id not found");
+      }
+      var plaintext = _b().crypto.toBase64Url(
+        _b().crypto.generateBytes(UNSUBSCRIBE_TOKEN_BYTES)
+      );
+      var tokenHash = _b().crypto.namespaceHash(UNSUBSCRIBE_NAMESPACE, plaintext);
+      var now       = Date.now();
+      var expiresAt = now + UNSUBSCRIBE_TTL_MS;
+      await query(
+        "INSERT INTO newsletter_unsubscribe_tokens " +
+        "(token_hash, signup_id, created_at, expires_at) " +
+        "VALUES (?1, ?2, ?3, ?4)",
+        [tokenHash, signupId, now, expiresAt],
+      );
+      // The plaintext leaves this function exactly once. Callers
+      // pass it into the email body; never log it, never persist
+      // it server-side — the row above is the only durable handle.
+      return { token: plaintext, expires_at: expiresAt };
+    },
+
+    // Single-use redeem. Errors are structured (not thrown) because
+    // the caller is typically an HTTP handler that needs to render a
+    // friendly page for each failure mode. The lookup itself runs
+    // off a constant-shape hash → primary-key query; the
+    // `timingSafeEqual` re-comparison on hit equalises the on-CPU
+    // work between the hit and miss paths so an attacker can't
+    // distinguish "this token never existed" from "this token was
+    // already used" through the response-latency channel. The
+    // plaintext token is never logged or echoed back.
+    consumeUnsubscribeToken: async function (plaintext) {
+      if (typeof plaintext !== "string" || !plaintext.length) {
+        return { ok: false, error: "not-found" };
+      }
+      var tokenHash = _b().crypto.namespaceHash(UNSUBSCRIBE_NAMESPACE, plaintext);
+      var row = (await query(
+        "SELECT token_hash, signup_id, consumed_at, expires_at " +
+        "FROM newsletter_unsubscribe_tokens WHERE token_hash = ?1 LIMIT 1",
+        [tokenHash],
+      )).rows[0];
+      if (!row) {
+        // Miss path — burn the same comparison work as the hit
+        // path so the latency profile matches. The compared values
+        // are deliberately equal-length and equal (the hash
+        // against itself); the result is discarded.
+        _b().crypto.timingSafeEqual(tokenHash, tokenHash);
+        return { ok: false, error: "not-found" };
+      }
+      // Constant-time check of the stored hash against the
+      // recomputed hash — defensive belt-and-braces against any
+      // future change to the primary-key index implementation.
+      var matched = _b().crypto.timingSafeEqual(row.token_hash, tokenHash);
+      if (!matched) return { ok: false, error: "not-found" };
+      if (row.consumed_at != null) {
+        return { ok: false, error: "already-consumed" };
+      }
+      var now = Date.now();
+      if (Number(row.expires_at) <= now) {
+        return { ok: false, error: "expired" };
+      }
+      await query(
+        "UPDATE newsletter_unsubscribe_tokens SET consumed_at = ?1 " +
+        "WHERE token_hash = ?2 AND consumed_at IS NULL",
+        [now, tokenHash],
+      );
+      await query(
+        "UPDATE newsletter_signups SET unsubscribed_at = ?1 WHERE id = ?2",
+        [now, row.signup_id],
+      );
+      var signup = (await query(
+        "SELECT email_hash FROM newsletter_signups WHERE id = ?1 LIMIT 1",
+        [row.signup_id],
+      )).rows[0];
+      return {
+        ok:         true,
+        error:      "ok",
+        signup_id:  row.signup_id,
+        email_hash: signup ? signup.email_hash : null,
+      };
+    },
+
+    // A subscriber who unsubscribed and changed their mind. The
+    // signup row stays the same id — we just clear the
+    // `unsubscribed_at` stamp. No new row, no new hash, so the
+    // operator's analytics keep continuity. Returns `ok: false`
+    // (without throwing) when the address has never signed up; the
+    // caller decides whether to surface "you weren't subscribed" or
+    // silently create a fresh signup via `.signup({ email })`.
+    resubscribe: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("newsletter.resubscribe: input object required");
+      }
+      var emailNormalized = _normalizeEmail(input.email);
+      var emailHash       = _b().crypto.namespaceHash(EMAIL_NAMESPACE, emailNormalized);
+      var existing = (await query(
+        "SELECT id FROM newsletter_signups WHERE email_hash = ?1 LIMIT 1",
+        [emailHash],
+      )).rows[0];
+      if (!existing) return { ok: false };
+      await query(
+        "UPDATE newsletter_signups SET unsubscribed_at = NULL WHERE id = ?1",
+        [existing.id],
+      );
+      return { ok: true, signup_id: existing.id };
+    },
   };
 }
 

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,
 };