@blamejs/core 0.18.6 → 0.18.8

package/lib/request-helpers.js

@@ -289,9 +289,12 @@ function clientIp(req, opts) {
           // socket peer is not a trusted proxy — cannot forge the result: the
           // forgeable header is ignored and we fall through to the socket
           // address. This is the only form safe for an access-control decision.
-          if (socketAddr && trust(socketAddr)) {
+          // Require an EXACT boolean true from the operator predicate — an async
+          // (Promise) or truthy-non-boolean result must NOT trust a hop (it would
+          // otherwise fall through to the forgeable hops[0] for access control).
+          if (socketAddr && trust(socketAddr) === true) {
             for (var i = hops.length - 1; i >= 0; i--) {
-              if (!trust(hops[i])) return hops[i];
+              if (trust(hops[i]) !== true) return hops[i];
             }
             return hops[0];   // entire chain trusted — earliest claimed client
           }
@@ -394,6 +397,124 @@ function trustedClientIp(opts) {
   };
 }
 
+function _socketAddr(req) {
+  return (req.socket && typeof req.socket.remoteAddress === "string" && req.socket.remoteAddress) ? req.socket.remoteAddress
+    : (req.connection && typeof req.connection.remoteAddress === "string" && req.connection.remoteAddress) ? req.connection.remoteAddress
+    : null;
+}
+
+/**
+ * @primitive b.requestHelpers.trustedIdentityHeaders
+ * @signature b.requestHelpers.trustedIdentityHeaders(opts)
+ * @since     0.18.8
+ * @status    stable
+ * @related   b.requestHelpers.trustedClientIp, b.requestHelpers.clientIp
+ *
+ * Resolve an identity-injecting reverse proxy's headers under the SAME
+ * peer-gate as `trustedClientIp` — the mirror of the `X-Forwarded-For`
+ * discipline for identity-header families (Cloudflare Access `Cf-Access-*`,
+ * oauth2-proxy `X-Forwarded-User`, Tailscale Serve `Tailscale-User-*`). A
+ * configured header family is trusted ONLY when the immediate socket peer is a
+ * trusted proxy; from every OTHER peer the family is defensively stripped from
+ * `req.headers` so downstream code cannot read a forged value. A naive trust of
+ * these headers is a full impersonation bypass — so this reuses the
+ * `trustedProxies` gate rather than opening a second, looser trust path.
+ *
+ * Returns `{ resolve(req), middleware, headerNames, peerGated }`. `resolve(req)`
+ * → `{ trusted, identity }` (`identity` is `{}` unless the peer is trusted).
+ * `middleware(req, res, next)` sets `req[as]` to the identity when trusted and
+ * DELETES every family header from `req.headers` when not. With no
+ * `trustedProxies`/`peerTrust` the peer is never trusted (fail-closed: the
+ * family is always stripped and `peerGated` is false).
+ *
+ * Header VALUES are surfaced raw — RFC 2047 name decoding and capability-JSON
+ * parsing are the consumer's job, not the trust boundary's.
+ *
+ * @opts
+ *   headers:        object,                 // { field: "Header-Name", ... } — the family to trust (required)
+ *   trustedProxies: string | string[],      // CIDRs of the reverse proxies — peer-gate the family
+ *   peerTrust:      function(req): boolean,  // own the peer-trust decision entirely (instead of trustedProxies)
+ *   as:             string,                  // req property to set the identity on (default: "proxyIdentity")
+ *
+ * @example
+ *   var ident = b.requestHelpers.trustedIdentityHeaders({
+ *     trustedProxies: ["127.0.0.1/32"],
+ *     headers: { login: "Tailscale-User-Login", name: "Tailscale-User-Name" },
+ *   });
+ *   app.use(ident.middleware);
+ *   // req.proxyIdentity = { login, name } from the trusted sidecar; a forged
+ *   // Tailscale-User-Login from a direct client is stripped, never trusted.
+ */
+function trustedIdentityHeaders(opts) {
+  opts = opts || {};
+  if (!opts.headers || typeof opts.headers !== "object" || Array.isArray(opts.headers)) {
+    throw new TypeError("trustedIdentityHeaders: opts.headers must be an object mapping field → header name");
+  }
+  var fieldNames = Object.keys(opts.headers);
+  if (fieldNames.length === 0) {
+    throw new TypeError("trustedIdentityHeaders: opts.headers must map at least one field");
+  }
+  var map = {};          // field → lowercased header name
+  var headerNames = [];  // lowercased header names (the family to strip)
+  for (var i = 0; i < fieldNames.length; i++) {
+    var hn = opts.headers[fieldNames[i]];
+    if (typeof hn !== "string" || hn.length === 0) {
+      throw new TypeError("trustedIdentityHeaders: header name for field '" + fieldNames[i] + "' must be a non-empty string");
+    }
+    var lhn = hn.toLowerCase();
+    map[fieldNames[i]] = lhn;
+    headerNames.push(lhn);
+  }
+  var peerTrust = opts.peerTrust;
+  if (peerTrust != null && typeof peerTrust !== "function") {
+    throw new TypeError("trustedIdentityHeaders: peerTrust must be a function(req) => boolean");
+  }
+  var predicate = _trustedProxyPredicate(_normTrustedProxies(opts), "trustedIdentityHeaders");
+  var asProp = (typeof opts.as === "string" && opts.as.length) ? opts.as : "proxyIdentity";
+
+  function _peerTrusted(req) {
+    // Require an EXACT synchronous `true`. A `!!` would treat a Promise (an async
+    // predicate) — or any truthy non-boolean — as trusted, so an untrusted peer
+    // could be impersonated; a non-true / thenable result fails closed.
+    if (peerTrust) return peerTrust(req) === true;
+    if (!predicate) return false;   // no gate configured → never trust (fail-closed)
+    var addr = _socketAddr(req);
+    return !!(addr && predicate(addr));
+  }
+
+  function resolve(req) {
+    if (!req || !req.headers || !_peerTrusted(req)) return { trusted: false, identity: {} };
+    var identity = {};
+    for (var f = 0; f < fieldNames.length; f++) {
+      var v = req.headers[map[fieldNames[f]]];
+      if (typeof v === "string") identity[fieldNames[f]] = v;
+    }
+    return { trusted: true, identity: identity };
+  }
+
+  function middleware(req, res, next) {
+    var r = resolve(req);
+    if (r.trusted) {
+      req[asProp] = r.identity;
+    } else {
+      // Defensive strip — a non-trusted peer must not deliver a family header
+      // that downstream reads as trusted identity.
+      if (req && req.headers) {
+        for (var h = 0; h < headerNames.length; h++) delete req.headers[headerNames[h]];
+      }
+      if (req) req[asProp] = null;
+    }
+    if (typeof next === "function") next();
+  }
+
+  return {
+    resolve:     resolve,
+    middleware:  middleware,
+    headerNames: headerNames.slice(),
+    peerGated:   !!(peerTrust || predicate),
+  };
+}
+
 // IP-prefix masking constants — named so the bit-arithmetic stays readable.
 // /24 IPv4 is the original IP-geolocation bucket and matches the legacy
 // carrier-NAT pool stride; /64 IPv6 is the customer LAN every RIR allocates
@@ -682,7 +803,7 @@ function requestProtocol(req, opts) {
             (req.socket && typeof req.socket.remoteAddress === "string" && req.socket.remoteAddress) ? req.socket.remoteAddress
             : (req.connection && typeof req.connection.remoteAddress === "string" && req.connection.remoteAddress) ? req.connection.remoteAddress
             : null;
-          if (peer && trust(peer)) return hops[0];
+          if (peer && trust(peer) === true) return hops[0];   // require an exact boolean true (no async/truthy trust)
           // peer not a trusted proxy → ignore forgeable header, fall through
         } else {
           return hops[0];   // legacy true/number — spoofable, see docstring
@@ -772,7 +893,7 @@ function requestHost(req, opts) {
             (req.socket && typeof req.socket.remoteAddress === "string" && req.socket.remoteAddress) ? req.socket.remoteAddress
             : (req.connection && typeof req.connection.remoteAddress === "string" && req.connection.remoteAddress) ? req.connection.remoteAddress
             : null;
-          if (peer && trust(peer)) return hops[0];
+          if (peer && trust(peer) === true) return hops[0];   // require an exact boolean true (no async/truthy trust)
           // peer not a trusted proxy → ignore forgeable header, fall through
         } else {
           return hops[0];   // legacy true — spoofable, see docstring
@@ -1371,6 +1492,7 @@ module.exports = {
   // proxy-trust primitives (default refuses forwarded headers)
   clientIp:                  clientIp,
   trustedClientIp:           trustedClientIp,
+  trustedIdentityHeaders:    trustedIdentityHeaders,
   ipPrefix:                  ipPrefix,
   ipKey:                     ipKey,
   requestProtocol:           requestProtocol,

package/lib/webhook-hmac.js

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module b.webhookHmac
+ * @nav    HTTP
+ * @title  HMAC Webhooks
+ * @order  236
+ *
+ * @intro
+ *   Inbound verification for the timestamped-HMAC webhook scheme — a single
+ *   header carrying a Unix timestamp and one or more HMAC signatures:
+ *
+ *     <sig-header>: t=<unix-seconds>,v1=<hmac-sha256-hex>[,v1=<rotated>]
+ *
+ *   The signed payload is <code>&lt;timestamp&gt;.&lt;raw-body&gt;</code>, keyed on the
+ *   endpoint signing secret. This is the scheme Stripe and Tailscale (among
+ *   others) use. It is DISTINCT from the StandardWebhooks scheme that
+ *   <code>b.standardWebhooks</code> verifies, which uses three separate headers
+ *   and an <code>&lt;id&gt;.&lt;ts&gt;.&lt;body&gt;</code> payload.
+ *
+ *   Verification refuses a timestamp outside the tolerance window (replay
+ *   defense), checks EVERY signature value under the version field (so a
+ *   rotated secret verifies with no downtime), compares with
+ *   <code>b.crypto.timingSafeEqual</code>, and ignores signature versions it
+ *   does not understand. Always verify against the EXACT received bytes —
+ *   never a re-serialized JSON body.
+ *
+ * @card
+ *   Verify the Stripe-style <code>t=&lt;ts&gt;,v1=&lt;hmac&gt;</code> timestamped-HMAC webhook scheme (Stripe / Tailscale / …) — replay window, key-rotation multi-signature, constant-time compare.
+ */
+
+var bCrypto         = require("./crypto");
+var safeBuffer      = require("./safe-buffer");
+var numericBounds   = require("./numeric-bounds");
+var validateOpts    = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var WebhookHmacError = defineClass("WebhookHmacError", { alwaysPermanent: true });
+
+var DEFAULT_TOLERANCE_SEC = 300;          // 5 minutes — the Stripe/Tailscale default replay window
+var DEFAULT_TS_FIELD      = "t";
+var DEFAULT_SIG_FIELD     = "v1";
+var DEFAULT_ALG           = "hmac-sha256";
+
+// alg string → node HMAC name. SHA-2 only; SHA-1 is refused (collision-weak,
+// and no webhook provider using this scheme needs it).
+var ALG_MAP = {
+  "hmac-sha256": "sha256",
+  "hmac-sha512": "sha512",
+};
+
+// Named presets for providers using this exact single-header scheme. Explicit
+// opts always override a profile.
+var PROFILES = {
+  stripe:    { tsField: "t", sigField: "v1", alg: "hmac-sha256" },
+  tailscale: { tsField: "t", sigField: "v1", alg: "hmac-sha256" },
+};
+
+function _mkErr(code, message) { return new WebhookHmacError(code, message); }
+
+function _requireNonEmptyString(val, name) {
+  if (typeof val !== "string" || val.length === 0) {
+    throw new WebhookHmacError("webhook-hmac/bad-" + name,
+      "verify: opts." + name + " must be a non-empty string");
+  }
+  return val;
+}
+
+/**
+ * @primitive b.webhookHmac.verify
+ * @signature b.webhookHmac.verify(opts)
+ * @since     0.18.8
+ * @status    stable
+ * @related   b.standardWebhooks.verify, b.crypto.hmac, b.crypto.timingSafeEqual
+ *
+ * Verify an inbound webhook signed with the timestamped-HMAC scheme
+ * (<code>t=&lt;ts&gt;,v1=&lt;hmac&gt;</code>). Refuses on a missing/garbled header, a
+ * timestamp outside the tolerance window (replay), or an HMAC mismatch;
+ * returns <code>{ valid: true, timestamp }</code> when a signature matches.
+ *
+ * The signed payload is <code>&lt;timestamp&gt;.&lt;raw-body&gt;</code> — pass the EXACT
+ * bytes received, not a parsed-then-re-serialized JSON body, or the HMAC will
+ * not reproduce. Every value under the signature field is checked, so a
+ * rotated secret (two <code>v1=</code> values) verifies without downtime.
+ * Comparison is constant-time; unrecognized signature versions are ignored.
+ *
+ * @opts
+ *   header:       string,          // the raw signature header value ("t=...,v1=...")
+ *   rawBody:      Buffer | string, // the exact received body bytes
+ *   secret:       Buffer | string, // the endpoint signing secret
+ *   profile:      string,          // "stripe" | "tailscale" — sets tsField/sigField/alg
+ *   tsField:      string,          // default: "t"
+ *   sigField:     string,          // default: "v1"
+ *   alg:          string,          // default: "hmac-sha256" (also "hmac-sha512")
+ *   toleranceSec: number,          // default: 300 (5 minutes)
+ *
+ * @example
+ *   var v = b.webhookHmac.verify({
+ *     header:  req.headers["stripe-signature"],
+ *     rawBody: rawBody,
+ *     secret:  process.env.WHSEC,
+ *   });
+ *   // → { valid: true, timestamp: 1614556828 }
+ */
+function verify(opts) {
+  opts = validateOpts.requireObject(opts, "webhookHmac.verify",
+    WebhookHmacError, "webhook-hmac/bad-opts");
+  validateOpts(opts,
+    ["header", "rawBody", "secret", "profile", "tsField", "sigField", "alg", "toleranceSec"],
+    "webhookHmac.verify");
+
+  // Resolve profile → field/alg defaults; explicit opts win.
+  var prof = {};
+  if (opts.profile !== undefined) {
+    if (typeof opts.profile !== "string" || !Object.prototype.hasOwnProperty.call(PROFILES, opts.profile)) {
+      throw new WebhookHmacError("webhook-hmac/bad-profile",
+        "verify: unknown profile '" + opts.profile + "' (known: " + Object.keys(PROFILES).join(", ") + ")");
+    }
+    prof = PROFILES[opts.profile];
+  }
+  var tsField  = opts.tsField  !== undefined ? opts.tsField  : (prof.tsField  || DEFAULT_TS_FIELD);
+  var sigField = opts.sigField !== undefined ? opts.sigField : (prof.sigField || DEFAULT_SIG_FIELD);
+  var algName  = opts.alg      !== undefined ? opts.alg      : (prof.alg      || DEFAULT_ALG);
+  _requireNonEmptyString(tsField, "tsField");
+  _requireNonEmptyString(sigField, "sigField");
+  var nodeAlg = Object.prototype.hasOwnProperty.call(ALG_MAP, algName) ? ALG_MAP[algName] : null;
+  if (!nodeAlg) {
+    throw new WebhookHmacError("webhook-hmac/bad-alg",
+      "verify: unsupported alg '" + String(algName) + "' (supported: " + Object.keys(ALG_MAP).join(", ") + ")");
+  }
+
+  _requireNonEmptyString(opts.header, "header");
+  var bodyBuf = safeBuffer.toBuffer(opts.rawBody, { typeCode: "webhook-hmac/bad-body", errorFactory: _mkErr });
+  var secretBuf = safeBuffer.toBuffer(opts.secret, { typeCode: "webhook-hmac/bad-secret", errorFactory: _mkErr });
+  if (secretBuf.length === 0) {
+    throw new WebhookHmacError("webhook-hmac/bad-secret", "verify: opts.secret must be non-empty");
+  }
+
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.toleranceSec, "toleranceSec",
+    WebhookHmacError, "webhook-hmac/bad-tolerance");
+  var tolerance = typeof opts.toleranceSec === "number" ? opts.toleranceSec : DEFAULT_TOLERANCE_SEC;
+
+  // Parse "t=<ts>,v1=<sig>,v1=<rotated>" — comma-separated k=v. Collect the ts
+  // and EVERY sigField value; ignore any other version keys.
+  var tsRaw = null;
+  var sigs = [];
+  var items = opts.header.split(",");
+  for (var i = 0; i < items.length; i += 1) {
+    var eq = items[i].indexOf("=");
+    if (eq < 0) continue;
+    var k = items[i].slice(0, eq).trim();
+    var v = items[i].slice(eq + 1).trim();
+    if (k === tsField) { if (tsRaw === null) tsRaw = v; }
+    else if (k === sigField) { sigs.push(v); }
+  }
+  if (tsRaw === null) {
+    throw new WebhookHmacError("webhook-hmac/missing-timestamp",
+      "verify: no '" + tsField + "=' field in the signature header");
+  }
+  if (sigs.length === 0) {
+    throw new WebhookHmacError("webhook-hmac/missing-signature",
+      "verify: no '" + sigField + "=' field in the signature header");
+  }
+
+  // Strict-integer timestamp (reject "12.3", "0x1", leading zeros, whitespace).
+  var ts = parseInt(tsRaw, 10);
+  if (!isFinite(ts) || ts <= 0 || String(ts) !== tsRaw) {
+    throw new WebhookHmacError("webhook-hmac/bad-timestamp",
+      "verify: '" + tsField + "' is not a positive integer");
+  }
+  var nowSec = Math.floor(Date.now() / 1000);
+  var skew = Math.abs(nowSec - ts);
+  if (skew > tolerance) {
+    throw new WebhookHmacError("webhook-hmac/timestamp-skew",
+      "verify: timestamp skew " + skew + "s exceeds tolerance " + tolerance + "s (replay window)");
+  }
+
+  // Signed payload is the raw timestamp string + "." + the exact body bytes.
+  var signed = Buffer.concat([Buffer.from(tsRaw + ".", "utf8"), bodyBuf]);
+  var expected = bCrypto.hmac(secretBuf, signed, nodeAlg);
+  var expectedBuf = Buffer.from(expected, "utf8");
+  var matched = false;
+  for (var s = 0; s < sigs.length; s += 1) {
+    // timingSafeEqual requires equal-length inputs; a wrong-length candidate
+    // cannot be the digest (the hex length is fixed by the algorithm, and is
+    // not secret), so the length pre-check leaks nothing.
+    if (sigs[s].length === expected.length &&
+        bCrypto.timingSafeEqual(expectedBuf, Buffer.from(sigs[s], "utf8"))) {
+      matched = true;
+      break;
+    }
+  }
+  if (!matched) {
+    throw new WebhookHmacError("webhook-hmac/bad-signature",
+      "verify: no '" + sigField + "' signature matched");
+  }
+  return { valid: true, timestamp: ts };
+}
+
+module.exports = {
+  verify:                verify,
+  PROFILES:              PROFILES,
+  DEFAULT_TOLERANCE_SEC: DEFAULT_TOLERANCE_SEC,
+  WebhookHmacError:      WebhookHmacError,
+};

package/lib/webhook.js

@@ -236,12 +236,12 @@ function _composeSignedString(algo, kid, timestamp, id, body) {
 // ---- Sign / verify primitives ----
 
 function _hmacSign(key, data) {
-  return bCrypto.hmacSha3(key, data);    // hex string
+  return bCrypto.hmac(key, data);    // hex string
 }
 
 function _hmacVerify(key, data, expectedHex) {
   if (!safeBuffer.isHex(expectedHex)) return false;
-  var actualHex = bCrypto.hmacSha3(key, data);
+  var actualHex = bCrypto.hmac(key, data);
   return bCrypto.timingSafeEqual(actualHex, expectedHex);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.18.6",
+  "version": "0.18.8",
   "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:9df8167e-caa6-4201-86c2-8c81536955c7",
+  "serialNumber": "urn:uuid:58122d84-2312-4802-ade5-95a30059fda2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-02T01:38:37.297Z",
+    "timestamp": "2026-08-02T12:19:34.917Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.18.6",
+      "bom-ref": "@blamejs/core@0.18.8",
       "type": "application",
       "name": "blamejs",
-      "version": "0.18.6",
+      "version": "0.18.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.18.6",
+      "purl": "pkg:npm/%40blamejs/core@0.18.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.18.6",
+      "ref": "@blamejs/core@0.18.8",
       "dependsOn": []
     }
   ]