@blamejs/core 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.4** (2026-04-30) — close SSRF DNS-rebinding window with pinned outbound DNS
+- **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/middleware/security-headers.js

@@ -46,10 +46,16 @@ var DEFAULT_PERMISSIONS = [
   "screen-wake-lock=()", "sync-xhr=()", "usb=()", "web-share=()", "xr-spatial-tracking=()",
 ];
 
+// Strict CSP — no 'unsafe-inline' on script-src OR style-src. Operators
+// with inline styles / scripts wire `b.middleware.cspNonce()` and use
+// `{{ cspNonce }}` in their views (or req.cspNonce in handlers); the
+// nonce hooks into the policy via the `csp` opt or a custom value.
+// Operators in transitional environments who genuinely need inline
+// styles set `csp` explicitly to the loose form.
 var DEFAULT_CSP =
   "default-src 'self'; " +
   "script-src 'self'; " +
-  "style-src 'self' 'unsafe-inline'; " +
+  "style-src 'self'; " +
   "img-src 'self' data:; " +
   "font-src 'self'; " +
   "connect-src 'self'; " +

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;
@@ -91,6 +94,23 @@ var IPV6_PRIVATE_PREFIX   = _ipv6ToBytes("fc00::");
 var IPV6_LINK_LOCAL_PREFIX = _ipv6ToBytes("fe80::");
 var IPV6_DOC_PREFIX       = _ipv6ToBytes("2001:db8::");      // documentation
 var IPV6_V4_MAPPED_PREFIX = _ipv6ToBytes("::ffff:0:0");      // IPv4-mapped (::ffff:0:0/96)
+// Multicast ff00::/8 — RFC 4291 §2.7. Refused for outbound HTTP same as
+// IPv4 multicast 224/4 — there's no legitimate fetch from a multicast
+// destination on a production gateway.
+var IPV6_MULTICAST_PREFIX = _ipv6ToBytes("ff00::");
+// NAT64 well-known prefix 64:ff9b::/96 — RFC 6052. Translates to IPv4
+// embedded in the lower 32 bits; the framework refuses since the
+// underlying v4 address is what gets contacted and might be private.
+// (Operators with NAT64 deployments flip allowInternal.)
+var IPV6_NAT64_PREFIX     = _ipv6ToBytes("64:ff9b::");
+// 6to4 2002::/16 — RFC 3056. Carries an embedded IPv4 in bytes 2-5;
+// hostile use is to tunnel through to a v4 destination the v4 guard
+// would have refused. Refused.
+var IPV6_6TO4_PREFIX      = _ipv6ToBytes("2002::");
+// Discard prefix 100::/64 — RFC 6666. Dropped by routers; fetching
+// from it is operationally meaningless and a likely sign of mis-config
+// or attempted exfil to a sinkhole.
+var IPV6_DISCARD_PREFIX   = _ipv6ToBytes("100::");
 
 // ---- Cloud metadata addresses (string-equality, exact match) ----
 var CLOUD_METADATA_IPS = [
@@ -232,6 +252,20 @@ function classify(ip) {
   if (_ipv6PrefixMatch(IPV6_LINK_LOCAL_PREFIX, 10, bytes))  return "link-local";
   if (_ipv6PrefixMatch(IPV6_PRIVATE_PREFIX,     7, bytes))  return "private";
   if (_ipv6PrefixMatch(IPV6_DOC_PREFIX,        32, bytes))  return "reserved";
+  if (_ipv6PrefixMatch(IPV6_MULTICAST_PREFIX,   8, bytes))  return "reserved";
+  if (_ipv6PrefixMatch(IPV6_DISCARD_PREFIX,    64, bytes))  return "reserved";
+  // 6to4 (2002::/16) embeds a v4 address in bytes 2–5; classify the
+  // embedded v4 so a 6to4-wrapped private/metadata address is refused
+  // for the same reason its v4 form would be.
+  if (_ipv6PrefixMatch(IPV6_6TO4_PREFIX, 16, bytes)) {
+    var v4From6to4 = bytes[2] + "." + bytes[3] + "." + bytes[4] + "." + bytes[5];
+    return classify(v4From6to4) || "reserved";
+  }
+  // NAT64 well-known prefix (64:ff9b::/96) embeds v4 in bytes 12–15.
+  if (_ipv6PrefixMatch(IPV6_NAT64_PREFIX, 96, bytes)) {
+    var v4FromNat64 = bytes[12] + "." + bytes[13] + "." + bytes[14] + "." + bytes[15];
+    return classify(v4FromNat64) || "reserved";
+  }
   // IPv4-mapped addresses (::ffff:a.b.c.d/96): re-classify the v4 portion.
   if (_ipv6PrefixMatch(IPV6_V4_MAPPED_PREFIX, 96, bytes)) {
     var mappedV4 = bytes[12] + "." + bytes[13] + "." + bytes[14] + "." + bytes[15];

package/package.json

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