@blamejs/core 0.11.24 → 0.11.25

package/lib/webhook.js

@@ -735,6 +735,232 @@ function _writeError(res, status, code, message) {
   res.end(JSON.stringify({ error: code, message: message }));
 }
 
+// ---- Stripe-compatible inbound HMAC-SHA-256 verifier (v0.11.25) ----
+//
+// Stripe (+ Stripe-shaped: Paddle, Shopify) ships inbound webhooks with
+// `Stripe-Signature: t=<unix>,v1=<hex>[,v0=<hex>...]`. The signed payload
+// is the literal string `<t>.<rawBody>` and the MAC is HMAC-SHA-256 keyed
+// by the operator's `whsec_...` secret bytes (the `whsec_` prefix IS the
+// key — Stripe's spec preserves it; do NOT strip).
+//
+// Spec: https://docs.stripe.com/webhooks/signature
+// Paddle:   https://developer.paddle.com/webhooks/signature-verification
+// Shopify:  https://shopify.dev/docs/apps/webhooks/configuration/https
+//
+// RFC 2104 (HMAC) + RFC 6234 (SHA-256). Constant-time compare via
+// b.crypto.timingSafeEqual — never `===`.
+
+var STRIPE_HMAC_ALG = "hmac-sha256-stripe";
+var STRIPE_SIG_MAX_HEX = 256;                                                                          // allow:raw-byte-literal — hex-char anti-DoS cap, not bytes
+var STRIPE_DEFAULT_TOLERANCE_MS = C.TIME.minutes(5);                                                   // RFC 3161-ish 5 minute window default
+var STRIPE_MIN_TOLERANCE_MS = C.TIME.seconds(30);                                                      // refuse below 30s
+
+function _hmacSha256Hex(keyBytes, dataString) {
+  return nodeCrypto.createHmac("sha256", keyBytes).update(dataString, "utf8").digest("hex");
+}
+
+function _parseStripeSignatureHeader(header) {
+  if (typeof header !== "string" || header.length === 0) {
+    throw new WebhookError("webhook/bad-stripe-header",
+      "verify: Stripe-Signature header must be a non-empty string");
+  }
+  if (header.length > 4096) {                                                                          // allow:raw-byte-literal — anti-DoS header cap
+    throw new WebhookError("webhook/bad-stripe-header",
+      "verify: Stripe-Signature header exceeds 4096 bytes");
+  }
+  var parts = header.split(",");
+  var ts = null;
+  var v1 = [];
+  for (var i = 0; i < parts.length; i += 1) {
+    var p = parts[i].trim();
+    var eq = p.indexOf("=");
+    if (eq <= 0) continue;
+    var k = p.slice(0, eq);
+    var v = p.slice(eq + 1);
+    if (k === "t") ts = v;
+    else if (k === "v1") {
+      if (v.length > STRIPE_SIG_MAX_HEX) {
+        throw new WebhookError("webhook/bad-stripe-header",
+          "verify: Stripe-Signature v1 entry exceeds " + STRIPE_SIG_MAX_HEX + " hex chars");
+      }
+      if (!/^[0-9a-f]+$/i.test(v)) continue;
+      v1.push(v.toLowerCase());
+    }
+  }
+  if (ts === null || !/^\d+$/.test(ts)) {
+    throw new WebhookError("webhook/bad-stripe-header",
+      "verify: Stripe-Signature missing or malformed t=<unix>");
+  }
+  if (v1.length === 0) {
+    throw new WebhookError("webhook/bad-stripe-header",
+      "verify: Stripe-Signature missing v1=<hex> entry");
+  }
+  return { timestamp: parseInt(ts, 10), v1: v1 };
+}
+
+function _timingSafeHexEqual(aHex, bHex) {
+  if (typeof aHex !== "string" || typeof bHex !== "string") return false;
+  if (aHex.length !== bHex.length) return false;
+  // Route through the framework's length-tolerant timing-safe compare;
+  // bCrypto handles the hex-string shape directly without manual
+  // Buffer.from coercion.
+  return bCrypto.timingSafeEqual(aHex, bHex);
+}
+
+function _coerceSecretBytes(secret) {
+  if (typeof secret === "string") return Buffer.from(secret, "utf8");
+  if (Buffer.isBuffer(secret)) return Buffer.from(secret);
+  throw new WebhookError("webhook/bad-secret",
+    "verify: secret must be a non-empty string or Buffer");
+}
+
+function _coerceBodyString(body) {
+  if (typeof body === "string") return body;
+  if (Buffer.isBuffer(body)) return body.toString("utf8");
+  throw new WebhookError("webhook/bad-body",
+    "verify: body must be a Buffer or string");
+}
+
+/**
+ * @primitive b.webhook.verify
+ * @signature b.webhook.verify(input)
+ * @since     0.11.25
+ * @status    stable
+ *
+ * Stripe-spec inbound webhook signature verifier. Validates the
+ * `Stripe-Signature: t=<unix>,v1=<hex>[,v1=<hex>...]` header against an
+ * HMAC-SHA-256 over the literal `<t>.<rawBody>` string using the
+ * operator's `whsec_...` secret bytes verbatim (the prefix IS the key).
+ * Refuses signatures older than the tolerance window (default 5 min,
+ * minimum 30 s). When `nonceStore` is supplied the verifier records
+ * the accepted v1 signature so a replay within the tolerance window
+ * is refused. Constant-time compare via `b.crypto.timingSafeEqual`.
+ *
+ * @example
+ *   b.webhook.verify({
+ *     alg:    "hmac-sha256-stripe",
+ *     secret: "whsec_abc...",
+ *     header: req.headers["stripe-signature"],
+ *     body:   rawBodyBuffer,
+ *   });
+ *   // → { ok: true, timestamp: 1700000000, scheme: "v1" }
+ */
+async function verify(input) {
+  if (!input || typeof input !== "object") {
+    throw new WebhookError("webhook/bad-opts",
+      "verify: input object required");
+  }
+  if (input.alg !== STRIPE_HMAC_ALG) {
+    throw new WebhookError("webhook/bad-alg",
+      "verify: alg must be '" + STRIPE_HMAC_ALG + "'");
+  }
+  var secretBytes = _coerceSecretBytes(input.secret);
+  if (secretBytes.length === 0) {
+    throw new WebhookError("webhook/bad-secret",
+      "verify: secret must be non-empty");
+  }
+  var bodyStr = _coerceBodyString(input.body);
+  var parsed = _parseStripeSignatureHeader(input.header);
+  var tolerance = input.toleranceMs;
+  if (tolerance === undefined) tolerance = STRIPE_DEFAULT_TOLERANCE_MS;
+  if (typeof tolerance !== "number" || !isFinite(tolerance) || tolerance < STRIPE_MIN_TOLERANCE_MS) {
+    throw new WebhookError("webhook/bad-tolerance",
+      "verify: toleranceMs must be a finite number >= " + STRIPE_MIN_TOLERANCE_MS);
+  }
+  var nowMs = (input._nowMs !== undefined && typeof input._nowMs === "number")
+    ? input._nowMs : Date.now();
+  var ageMs = nowMs - C.TIME.seconds(parsed.timestamp);
+  if (ageMs < 0) ageMs = -ageMs;
+  if (ageMs > tolerance) {
+    throw new WebhookError("webhook/stale-timestamp",
+      "verify: signature timestamp outside tolerance (" + ageMs + "ms > " + tolerance + "ms)");
+  }
+
+  var expectedHex = _hmacSha256Hex(secretBytes, parsed.timestamp + "." + bodyStr);
+  var matched = false;
+  for (var i = 0; i < parsed.v1.length; i += 1) {
+    if (_timingSafeHexEqual(parsed.v1[i], expectedHex)) {
+      matched = true;
+      break;
+    }
+  }
+  if (!matched) {
+    throw new WebhookError("webhook/bad-signature",
+      "verify: no v1 signature matched HMAC-SHA-256 of <t>.<body>");
+  }
+
+  // Optional replay defense — the nonceStore is operator-supplied
+  // (e.g. `b.kv` or a Redis-shaped { has, set, expire }) so the
+  // primitive doesn't own retention. `has` / `set` MAY return a
+  // Promise — we always `await` them so async backends (Redis, KV,
+  // DynamoDB) work without falsely flagging a Promise as truthy.
+  if (input.nonceStore) {
+    var ns = input.nonceStore;
+    if (typeof ns.has !== "function" || typeof ns.set !== "function") {
+      throw new WebhookError("webhook/bad-nonce-store",
+        "verify: nonceStore must expose { has(key), set(key, ttlMs) }");
+    }
+    var nonceKey = "stripe:" + parsed.timestamp + ":" + expectedHex;
+    var seen = await ns.has(nonceKey);
+    if (seen) {
+      throw new WebhookError("webhook/replay",
+        "verify: signature already seen within tolerance window (replay)");
+    }
+    await ns.set(nonceKey, tolerance);
+  }
+
+  return { ok: true, timestamp: parsed.timestamp, scheme: "v1" };
+}
+
+/**
+ * @primitive b.webhook.sign
+ * @signature b.webhook.sign(input)
+ * @since     0.11.25
+ * @status    stable
+ *
+ * Round-trip companion to `b.webhook.verify` for the
+ * `hmac-sha256-stripe` algorithm. Returns the `Stripe-Signature`
+ * header value `t=<unix>,v1=<hex>` for a given body + secret +
+ * (optional) timestamp. Operators emitting Stripe-shaped webhooks
+ * downstream — and the test surface — use this to produce the
+ * matching header.
+ *
+ * @example
+ *   var header = b.webhook.sign({
+ *     alg:    "hmac-sha256-stripe",
+ *     secret: "whsec_abc...",
+ *     body:   '{"id":"evt_1"}',
+ *   });
+ */
+function sign(input) {
+  if (!input || typeof input !== "object") {
+    throw new WebhookError("webhook/bad-opts",
+      "sign: input object required");
+  }
+  if (input.alg !== STRIPE_HMAC_ALG) {
+    throw new WebhookError("webhook/bad-alg",
+      "sign: alg must be '" + STRIPE_HMAC_ALG + "'");
+  }
+  var secretBytes = _coerceSecretBytes(input.secret);
+  if (secretBytes.length === 0) {
+    throw new WebhookError("webhook/bad-secret",
+      "sign: secret must be non-empty");
+  }
+  var bodyStr = _coerceBodyString(input.body);
+  var ts;
+  if (input.timestamp !== undefined) {
+    if (typeof input.timestamp !== "number" || !isFinite(input.timestamp) || input.timestamp < 0) {
+      throw new WebhookError("webhook/bad-timestamp",
+        "sign: timestamp must be a non-negative finite number (unix seconds)");
+    }
+    ts = Math.floor(input.timestamp);
+  } else {
+    ts = Math.floor(Date.now() / 1000);                                                                // allow:raw-time-literal — unix-seconds conversion, Stripe spec uses seconds-not-ms
+  }
+  var hex = _hmacSha256Hex(secretBytes, ts + "." + bodyStr);
+  return "t=" + ts + ",v1=" + hex;
+}
+
 // ---- Public surface ----
 
 module.exports = {
@@ -745,4 +971,7 @@ module.exports = {
   HEADER:         HEADER,
   DEFAULTS:       DEFAULTS,
   WebhookError:   WebhookError,
+  // v0.11.25 — Stripe-shaped inbound HMAC-SHA-256 verifier + signer.
+  verify:         verify,
+  sign:           sign,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.24",
+  "version": "0.11.25",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:f66cc3af-cd05-47b5-b147-bc1e05a046f1",
+  "serialNumber": "urn:uuid:6b814cb5-e99f-4bcb-a349-6b597ea780a6",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T03:43:16.022Z",
+    "timestamp": "2026-05-21T05:38:05.971Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.24",
+      "bom-ref": "@blamejs/core@0.11.25",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.24",
+      "version": "0.11.25",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.24",
+      "purl": "pkg:npm/%40blamejs/core@0.11.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.24",
+      "ref": "@blamejs/core@0.11.25",
       "dependsOn": []
     }
   ]