@blamejs/core 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.3** (2026-04-30) — security cleanup: trustProxy primitive + Vary merge + HSTS gate
 - **0.5.2** (2026-04-30) — b.breakGlass: passkey factor + service-account bypass + admin tools
 - **0.5.1** (2026-04-30) — b.breakGlass: per-cell encryption + context binding + migrate
 - **0.5.0** (2026-04-30) — b.breakGlass: column-policy / row-enforcement step-up auth

package/lib/http-client.js

@@ -151,7 +151,7 @@ function _originKey(u) {
     (u.port || (u.protocol === "https:" ? 443 : 80));
 }
 
-function _makeH1Transport(u) {
+function _makeH1Transport(u, ips) {
   var lib = u.protocol === "https:" ? https : http;
   // HTTPS path goes through pqcAgent.create so the framework's PQC-only
   // posture is enforced via the single primitive. Cleartext HTTP stays
@@ -159,14 +159,38 @@ function _makeH1Transport(u) {
   var agent = u.protocol === "https:"
     ? pqcAgent.create(HTTP_CLIENT_AGENT_OPTS)
     : new lib.Agent(HTTP_CLIENT_AGENT_OPTS);
-  return { kind: "h1", lib: lib, agent: agent };
+  return { kind: "h1", lib: lib, agent: agent, lookup: _pinnedLookupFor(ips) };
+}
+
+// Build a `lookup` callback that pins outbound connections to IPs the
+// SSRF guard already validated. Closes the TOCTOU window between
+// SSRF resolution and the kernel's connect — without this, a hostile
+// (or compromised) DNS could rotate the answer between guard-check
+// and connect-time and route the request to a private / metadata IP
+// that bypassed the gate. ips comes from `ssrfGuard.checkUrl` — its
+// classification ran on these exact addresses.
+function _pinnedLookupFor(ips) {
+  if (!Array.isArray(ips) || ips.length === 0) return undefined;
+  var families = ips.map(function (i) { return { address: i.address, family: i.family || 4 }; });
+  return function pinnedLookup(hostname, options, callback) {
+    if (typeof options === "function") { callback = options; options = {}; }
+    options = options || {};
+    if (options.all) {
+      callback(null, families);
+    } else {
+      callback(null, families[0].address, families[0].family);
+    }
+  };
 }
 
 // Connect an h2 session to an HTTPS origin via ALPN. If the server picks
 // http/1.1, fall back to an h1 transport for that origin.
-function _connectHttpsWithAlpn(u) {
+function _connectHttpsWithAlpn(u, ips) {
   return new Promise(function (resolve, reject) {
-    var session = http2.connect(u.protocol + "//" + u.host, DEFAULT_H2_TLS_OPTS);
+    var connectOpts = Object.assign({}, DEFAULT_H2_TLS_OPTS);
+    var pinned = _pinnedLookupFor(ips);
+    if (pinned) connectOpts.lookup = pinned;
+    var session = http2.connect(u.protocol + "//" + u.host, connectOpts);
     var settled = false;
     function _done(t)   { if (!settled) { settled = true; resolve(t); } }
     function _fail(err) { if (!settled) { settled = true; reject(err); } }
@@ -180,7 +204,7 @@ function _connectHttpsWithAlpn(u) {
       }
       // Server picked http/1.1 — close the h2 session, return h1 transport.
       try { session.close(); } catch (_e) {}
-      _done(_makeH1Transport(u));
+      _done(_makeH1Transport(u, ips));
     });
     session.once("error", function (err) {
       try { session.close(); } catch (_e) {}
@@ -191,9 +215,12 @@ function _connectHttpsWithAlpn(u) {
 
 // Connect an h2c session (cleartext h2). No ALPN, no fallback — caller
 // has attested via preferH2 that the server speaks h2c.
-function _connectH2c(u) {
+function _connectH2c(u, ips) {
   return new Promise(function (resolve, reject) {
-    var session = http2.connect(u.protocol + "//" + u.host);
+    var connectOpts = {};
+    var pinned = _pinnedLookupFor(ips);
+    if (pinned) connectOpts.lookup = pinned;
+    var session = http2.connect(u.protocol + "//" + u.host, connectOpts);
     session.once("connect", function () {
       _wireH2Session(session, _originKey(u));
       resolve({ kind: "h2", session: session });
@@ -218,23 +245,29 @@ function _wireH2Session(session, key) {
   });
 }
 
-// Async transport selection. Returns Promise<transport>.
-function _getTransport(u, opts) {
+// Async transport selection. Returns Promise<transport>. `ips` is the
+// validated address list returned by `ssrfGuard.checkUrl`; the transport
+// uses it to pin connections so a hostile DNS rebind can't redirect
+// the actual TCP connect to a private / metadata IP.
+function _getTransport(u, opts, ips) {
   var key = _originKey(u);
   var cached = _transports.get(key);
   if (cached) {
-    // Could be a resolved transport OR a pending Promise.
+    // Could be a resolved transport OR a pending Promise. Cached
+    // transports keep whatever IP pinning was set when they were
+    // first created — subsequent SSRF checks still gate the request,
+    // and the transport's TCP socket is bound to its original IP.
     return Promise.resolve(cached);
   }
 
   var promise;
   if (u.protocol === "https:") {
-    promise = _connectHttpsWithAlpn(u);
+    promise = _connectHttpsWithAlpn(u, ips);
   } else if (opts && opts.preferH2) {
-    promise = _connectH2c(u);
+    promise = _connectH2c(u, ips);
   } else {
     // HTTP without preferH2 → h1 only.
-    promise = Promise.resolve(_makeH1Transport(u));
+    promise = Promise.resolve(_makeH1Transport(u, ips));
   }
 
   // Cache the in-flight Promise immediately so concurrent calls
@@ -600,22 +633,27 @@ function _requestSingle(opts) {
   }
 
   // SSRF gate — refuse private / loopback / link-local / cloud-metadata
-  // / reserved IP destinations by default. Operators on internal mesh
-  // pass `allowInternal: true` (or a CIDR list for narrower bypass).
+  // / reserved IP destinations by default. The returned `ips` are
+  // threaded into transport creation so the actual TCP connect pins
+  // to those exact addresses, closing the DNS-rebinding TOCTOU window.
   return ssrfGuard.checkUrl(u, {
     allowInternal: opts.allowInternal,
     errorClass:    opts.errorClass,
-  }).then(function () {
-    // Caller-supplied agent bypasses transport cache (h1 only).
+  }).then(function (ssrfResult) {
+    var ips = ssrfResult && ssrfResult.ips;
+    // Caller-supplied agent bypasses transport cache (h1 only). The
+    // operator owns the agent's connection pool — we still pass the
+    // pinned lookup through per-request so the SSRF check's IPs win.
     if (opts.agent) {
       return _requestH1({
-        kind: "h1",
-        lib:  u.protocol === "https:" ? https : http,
-        agent: opts.agent,
+        kind:   "h1",
+        lib:    u.protocol === "https:" ? https : http,
+        agent:  opts.agent,
+        lookup: _pinnedLookupFor(ips),
       }, u, opts);
     }
 
-    return _getTransport(u, opts).then(function (transport) {
+    return _getTransport(u, opts, ips).then(function (transport) {
       if (transport.kind === "h2") return _requestH2(transport, u, opts);
       return _requestH1(transport, u, opts);
     });
@@ -655,6 +693,9 @@ function _requestH1(transport, u, opts) {
       agent:    transport.agent,
       timeout:  typeof opts.idleTimeoutMs === "number" ? opts.idleTimeoutMs : DEFAULT_IDLE_TIMEOUT_MS,
     };
+    // Pin DNS to the IPs the SSRF guard validated. Closes the
+    // rebinding TOCTOU between guard-check and actual TCP connect.
+    if (transport.lookup) reqOpts.lookup = transport.lookup;
 
     if (observer) observer("request:start", { method: method, url: String(opts.url), protocol: "h1" });
 
@@ -990,4 +1031,8 @@ module.exports = {
   _resetForTest:              _resetForTest,
   _getCachedTransportCount:   _getCachedTransportCount,
   _getCachedTransportKind:    _getCachedTransportKind,
+  // Test-only — exposes the SSRF-pinned DNS lookup builder so unit
+  // tests can confirm the callback shape matches Node's documented
+  // `lookup(hostname, options, callback)` contract.
+  _pinnedLookupForTest:       _pinnedLookupFor,
 };

package/lib/ssrf-guard.js

@@ -31,10 +31,13 @@
  *                               fd00:ec2::254
  *
  * Hostnames are resolved via dns.lookup before classification, so a
- * malicious hostname pointing at a private IP fails the guard. The
- * resolved IP is the one used for the actual connection — DNS rebinding
- * between this check and the connect is out of scope (operators with
- * that threat model pin to IP literals or use a sealed internal DNS).
+ * malicious hostname pointing at a private IP fails the guard.
+ *
+ * The validated IPs are returned in the result and `b.httpClient` pins
+ * the actual TCP connect to those exact addresses (via a custom
+ * `lookup` callback passed to https / http2 connect). A hostile DNS
+ * server cannot rebind between guard-check and connect to redirect
+ * traffic at a private / metadata address.
  */
 
 var dns = require("node:dns").promises;

package/package.json

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