@blamejs/core 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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/middleware/bot-guard.js

@@ -50,20 +50,25 @@ var validateOpts = require("../validate-opts");
 var audit = lazyRequire(function () { return require("../audit"); });
 
 // Bot-guard's "trust the proxy header" semantics for actor.ip — the
-// audit event records the apparent source even when behind a CDN.
-// extractActorContext defaults to socket.remoteAddress; we override.
-function _xffIp(req) {
-  var xff = req.headers && req.headers["x-forwarded-for"];
-  if (xff) return String(xff).split(",")[0].trim();
-  return (req.socket && req.socket.remoteAddress) || null;
+// audit event records the apparent source even when behind a CDN, but
+// only when the operator opts in to trustProxy. Without the opt, we
+// stick to socket.remoteAddress so an attacker-forged XFF can't
+// pollute audit attribution.
+function _xffIpFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.clientIp(req, { trustProxy: trustProxy });
+  };
 }
 
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "mode", "onlyForHtml", "allowedAgents", "blockedAgents",
-    "skipPaths", "statusOnBlock", "bodyOnBlock",
+    "skipPaths", "statusOnBlock", "bodyOnBlock", "trustProxy",
   ], "middleware.botGuard");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _xffIp = _xffIpFor(trustProxy);
   var mode = opts.mode || "block";
   var onlyForHtml = opts.onlyForHtml !== false;
   var allowedAgents = (opts.allowedAgents || []).map(function (r) { return r instanceof RegExp ? r : new RegExp(r); });

package/lib/middleware/cors.js

@@ -49,13 +49,13 @@ var safeUrl = require("../safe-url");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
-// CORS audit events trust the proxy header for actor.ip — same
-// semantics as bot-guard (the apparent origin is what matters when
-// blocking cross-origin attempts behind a CDN).
-function _xffIp(req) {
-  var xff = req.headers && req.headers["x-forwarded-for"];
-  if (xff) return String(xff).split(",")[0].trim();
-  return (req.socket && req.socket.remoteAddress) || null;
+// CORS audit events use the proxy-aware client IP only when the
+// operator opts in via `trustProxy`. Default refuses forwarded
+// headers — same boundary as the rest of the v0.5.3 trustProxy sweep.
+function _xffIpFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.clientIp(req, { trustProxy: trustProxy });
+  };
 }
 
 var CorsError = defineClass("CorsError", { alwaysPermanent: true });
@@ -94,26 +94,17 @@ function _canonicalOrigin(input) {
 // supplied. Works for direct deployments (no proxy); operators behind
 // a TLS-terminating proxy that doesn't forward correct Host should set
 // opts.siteOrigin explicitly.
-function _inferRequestOrigin(req) {
+function _inferRequestOrigin(req, trustProxy) {
   if (!req || !req.headers) return null;
   var host = req.headers.host;
   if (!host) return null;
-  // X-Forwarded-Proto wins when present (operator behind a TLS-
-  // terminator, intermediate set the header). Otherwise infer from
-  // the socket — req.socket.encrypted is set by node:tls.
-  var fwdProto = req.headers["x-forwarded-proto"];
-  var proto;
-  if (typeof fwdProto === "string" && fwdProto.length > 0) {
-    proto = fwdProto.split(",")[0].trim().toLowerCase();
-  } else if (req.socket && req.socket.encrypted) {
-    proto = "https";
-  } else {
-    proto = "http";
-  }
+  // Protocol resolution honors the operator's trustProxy opt — without
+  // it, X-Forwarded-Proto is ignored as attacker-forgeable.
+  var proto = requestHelpers.requestProtocol(req, { trustProxy: trustProxy });
   return _canonicalOrigin(proto + "://" + host);
 }
 
-function _isSameOrigin(req, originHeader, configuredSiteOrigins) {
+function _isSameOrigin(req, originHeader, configuredSiteOrigins, trustProxy) {
   // Origin: null + Sec-Fetch-Site: same-origin|none — browser opaqued
   // the Origin (typically because of Referrer-Policy: no-referrer on the
   // page) but is also explicitly telling us the request is same-origin.
@@ -133,8 +124,10 @@ function _isSameOrigin(req, originHeader, configuredSiteOrigins) {
     }
     return false;
   }
-  // Fall back to inferring from the request itself.
-  var reqOrigin = _inferRequestOrigin(req);
+  // Fall back to inferring from the request itself. trustProxy threads
+  // through so operators behind a TLS terminator with X-Forwarded-Proto
+  // can opt in to consult the header.
+  var reqOrigin = _inferRequestOrigin(req, trustProxy);
   return reqOrigin !== null && reqOrigin === canonOrigin;
 }
 
@@ -143,8 +136,11 @@ function create(opts) {
 
   validateOpts(opts, [
     "origins", "siteOrigin", "methods", "headers", "exposeHeaders",
-    "credentials", "maxAgeSeconds", "refuseUnknown",
+    "credentials", "maxAgeSeconds", "refuseUnknown", "trustProxy",
   ], "middleware.cors");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _xffIp = _xffIpFor(trustProxy);
 
   var origins = opts.origins || [];
 
@@ -191,7 +187,7 @@ function create(opts) {
     // Same-origin POST/PUT/etc. carry an Origin header per the Fetch
     // spec but should not be subject to CORS allow-listing — they're
     // the operator's own site talking to itself.
-    if (_isSameOrigin(req, origin, siteOrigins)) return next();
+    if (_isSameOrigin(req, origin, siteOrigins, trustProxy)) return next();
 
     var matched = _matchOrigin(origin, origins);
     if (!matched) {
@@ -217,13 +213,36 @@ function create(opts) {
 
     if (typeof res.setHeader === "function") {
       res.setHeader("Access-Control-Allow-Origin", matched);
-      res.setHeader("Vary", "Origin");
+      // Append "Origin" to Vary instead of overwriting — compression /
+      // auth helpers may have set their own Vary tokens that the cache
+      // layer needs to keep.
+      requestHelpers.appendVary(res, "Origin");
       if (credentials) res.setHeader("Access-Control-Allow-Credentials", "true");
       res.setHeader("Access-Control-Expose-Headers", exposeHeaders);
     }
 
     if (req.method === "OPTIONS" && req.headers["access-control-request-method"]) {
-      // Preflight
+      // Preflight. In refuseUnknown mode, validate the requested
+      // headers against the configured allow-list — refuse with 403
+      // if the client asks for a header we don't allow. Spec says
+      // browsers enforce, but server-side enforcement keeps the
+      // framework's strict-by-default posture consistent.
+      if (refuseUnknown) {
+        var requestedHdrs = req.headers["access-control-request-headers"];
+        if (requestedHdrs) {
+          var allowedSet = headers.toLowerCase().split(",").map(function (s) { return s.trim(); });
+          var asked = String(requestedHdrs).toLowerCase().split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+          for (var ah = 0; ah < asked.length; ah++) {
+            if (allowedSet.indexOf(asked[ah]) === -1) {
+              if (typeof res.writeHead === "function") {
+                res.writeHead(403, { "Content-Type": "text/plain" });
+                res.end("CORS: requested header '" + asked[ah] + "' not in allow-list");
+              }
+              return;
+            }
+          }
+        }
+      }
       if (typeof res.setHeader === "function") {
         res.setHeader("Access-Control-Allow-Methods", methods);
         res.setHeader("Access-Control-Allow-Headers", headers);

package/lib/middleware/csrf-protect.js

@@ -98,13 +98,15 @@ function _parseCookieHeader(header) {
   return out;
 }
 
-function _isHttps(req) {
-  if (req && req.socket && req.socket.encrypted) return true;
-  var fwd = req && req.headers && req.headers["x-forwarded-proto"];
-  if (typeof fwd === "string" && fwd.length > 0) {
-    return fwd.split(",")[0].trim().toLowerCase() === "https";
-  }
-  return false;
+// `_isHttps` defers to `requestHelpers.requestProtocol` so the
+// per-middleware `trustProxy` opt gates whether X-Forwarded-Proto is
+// consulted. Without trustProxy, an attacker could otherwise forge
+// the header to force the Secure cookie attribute (and inversely,
+// suppress it) on direct-to-server connections.
+function _isHttpsFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https";
+  };
 }
 
 function _formatSetCookie(name, value, opts) {
@@ -159,7 +161,11 @@ function create(opts) {
 
   validateOpts(opts, [
     "cookie", "tokenLookup", "fieldName", "headerName", "methods", "audit",
+    "trustProxy",
   ], "middleware.csrfProtect");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _isHttps = _isHttpsFor(trustProxy);
 
   // Tier A — exactly one issuance source.
   var hasCookie = opts.cookie != null && opts.cookie !== false;

package/lib/middleware/rate-limit.js

@@ -52,10 +52,15 @@ var clusterStorage = require("../cluster-storage");
 var audit  = lazyRequire(function () { return require("../audit"); });
 var logger = lazyRequire(function () { return require("../log").boot("rate-limit"); });
 
-function _clientIp(req) {
-  var fwd = req.headers && req.headers["x-forwarded-for"];
-  if (fwd) return String(fwd).split(",")[0].trim();
-  return (req.socket && req.socket.remoteAddress) || "unknown";
+// `_clientIp` defers to `requestHelpers.clientIp`, threading the
+// per-middleware `trustProxy` opt. Default refuses forwarded headers
+// (returning the socket address only) — operators behind a sanitizing
+// reverse proxy opt in via `trustProxy: true` (or a hop count).
+function _clientIpFor(trustProxy) {
+  return function (req) {
+    var ip = requestHelpers.clientIp(req, { trustProxy: trustProxy });
+    return ip || "unknown";
+  };
 }
 
 // ---- Memory backend (token bucket) ----
@@ -221,12 +226,15 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "keyFn", "statusOnLimit", "bodyOnLimit", "header", "skipPaths", "scope",
-    "backend",
+    "backend", "trustProxy",
     // memory backend
     "burst", "refillPerSecond",
     // cluster backend
     "limit", "windowMs", "pruneIntervalMs",
   ], "middleware.rateLimit");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _clientIp = _clientIpFor(trustProxy);
   var keyFn = opts.keyFn || _clientIp;
   var statusOnLimit = opts.statusOnLimit || 429;
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";

package/lib/middleware/security-headers.js

@@ -35,6 +35,7 @@
  *   }
  */
 
+var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
 
 var DEFAULT_PERMISSIONS = [
@@ -62,8 +63,10 @@ function create(opts) {
   validateOpts(opts, [
     "hsts", "contentTypeOptions", "frameOptions", "referrerPolicy",
     "permissionsPolicy", "coop", "coep", "corp",
-    "originAgentCluster", "dnsPrefetchControl", "csp",
+    "originAgentCluster", "dnsPrefetchControl", "csp", "trustProxy",
   ], "middleware.securityHeaders");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
   var hsts = opts.hsts === undefined ? "max-age=63072000; includeSubDomains; preload" : opts.hsts;
   var ctOpts = opts.contentTypeOptions === undefined ? "nosniff" : opts.contentTypeOptions;
   var frameOpts = opts.frameOptions === undefined ? "DENY" : opts.frameOptions;
@@ -78,7 +81,14 @@ function create(opts) {
 
   return function securityHeaders(req, res, next) {
     if (typeof res.setHeader !== "function") return next();
-    if (hsts)       res.setHeader("Strict-Transport-Security", hsts);
+    // RFC 6797 §7.2: HSTS over plain HTTP is meaningless (UAs ignore
+    // it). Skip the header on non-TLS requests so dev-over-HTTP doesn't
+    // surface confusing "Strict-Transport-Security on http://" lines.
+    // requestProtocol respects trustProxy — operators behind a TLS
+    // terminator opt in to read X-Forwarded-Proto.
+    if (hsts && requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https") {
+      res.setHeader("Strict-Transport-Security", hsts);
+    }
     if (ctOpts)     res.setHeader("X-Content-Type-Options", ctOpts);
     if (frameOpts)  res.setHeader("X-Frame-Options", frameOpts);
     if (refPolicy)  res.setHeader("Referrer-Policy", refPolicy);

package/lib/object-store/http-put.js

@@ -56,7 +56,13 @@ function _keyToUrl(baseUrl, key) {
   }
   var b = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   var k = key.startsWith("/") ? key.slice(1) : key;
-  return b + "/" + k;
+  // URL-encode each path segment so reserved characters (?, #, %, space,
+  // unicode, etc.) round-trip safely and don't cross-pollute keys
+  // (e.g. `a%2Fb` and `a/b` would otherwise collide on the wire).
+  // Slashes between segments stay literal (operators use them as a
+  // namespace separator, matching S3 / GCS / Azure conventions).
+  var encoded = k.split("/").map(encodeURIComponent).join("/");
+  return b + "/" + encoded;
 }
 
 function create(config) {

package/lib/request-helpers.js

@@ -112,6 +112,71 @@ function resolveActorWithOverride(callerOpts, baseOverride) {
   return extractActorContext(callerOpts && callerOpts.req, override);
 }
 
+// ---- Proxy-trust primitives (v0.5.3) ----
+//
+// `X-Forwarded-For` and `X-Forwarded-Proto` are operator-trust headers —
+// behind a sanitizing reverse proxy they carry the apparent origin /
+// scheme; without one they're attacker-forgeable. Default is to NOT
+// trust them; operators behind a proxy set `trustProxy: true` (or a
+// hop count for multi-hop chains) per-middleware to opt in.
+//
+//   clientIp(req, { trustProxy }) →  string | null
+//
+//     trustProxy false (default):  socket.remoteAddress only
+//     trustProxy true:             leftmost x-forwarded-for hop, else socket
+//     trustProxy <integer N>:      Nth-from-rightmost xff hop (skip-N-trusted-hops)
+//
+// Middleware accepts `trustProxy` as an opt and threads it through;
+// the framework refuses to silently pick up forwarded headers without
+// the operator's explicit acknowledgement.
+
+function clientIp(req, opts) {
+  if (!req) return null;
+  var trust = opts && opts.trustProxy;
+  if (trust && req.headers) {
+    var xff = req.headers["x-forwarded-for"];
+    if (xff) {
+      var hops = String(xff).split(",").map(function (s) { return s.trim(); });
+      if (trust === true) return hops[0];
+      if (typeof trust === "number" && trust >= 1 && hops.length >= trust) {
+        return hops[hops.length - trust];
+      }
+    }
+  }
+  if (req.socket && typeof req.socket.remoteAddress === "string") return req.socket.remoteAddress;
+  if (req.connection && typeof req.connection.remoteAddress === "string") return req.connection.remoteAddress;
+  return null;
+}
+
+function requestProtocol(req, opts) {
+  if (!req) return "http";
+  var trust = opts && opts.trustProxy;
+  if (trust && req.headers) {
+    var fwd = req.headers["x-forwarded-proto"];
+    if (typeof fwd === "string" && fwd.length > 0) {
+      return String(fwd).split(",")[0].trim().toLowerCase();
+    }
+  }
+  if (req.socket && req.socket.encrypted) return "https";
+  if (req.connection && req.connection.encrypted) return "https";
+  return "http";
+}
+
+// Append a token to a `Vary` response header without dropping prior
+// values (compression middleware sets `Vary: Accept-Encoding`, an
+// auth helper might set `Vary: Authorization`, etc.). Idempotent —
+// re-adding an existing token is a no-op.
+function appendVary(res, value) {
+  if (!res || typeof res.getHeader !== "function" || typeof res.setHeader !== "function") return;
+  var existing = res.getHeader("Vary");
+  if (existing == null || existing === "") { res.setHeader("Vary", value); return; }
+  var tokens = String(existing).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+  var lower = value.toLowerCase();
+  for (var i = 0; i < tokens.length; i++) if (tokens[i].toLowerCase() === lower) return;
+  tokens.push(value);
+  res.setHeader("Vary", tokens.join(", "));
+}
+
 function resolveRoute(req) {
   if (req && typeof req.routePattern === "string" && req.routePattern.length > 0) {
     return req.routePattern;
@@ -201,4 +266,8 @@ module.exports = {
   extractActorContext:       extractActorContext,
   resolveActorWithOverride:  resolveActorWithOverride,
   parseQualityList:          parseQualityList,
+  // v0.5.3 — proxy-trust primitives (default refuses forwarded headers)
+  clientIp:                  clientIp,
+  requestProtocol:           requestProtocol,
+  appendVary:                appendVary,
 };

package/lib/session.js

@@ -128,7 +128,23 @@ async function verify(token) {
   var unsealed = cryptoField.unsealRow("_blamejs_sessions", row);
   var data = null;
   if (unsealed.data) {
-    try { data = safeJson.parse(unsealed.data); } catch (_e) { data = null; }
+    try { data = safeJson.parse(unsealed.data); }
+    catch (e) {
+      // Decrypt-then-parse failure is rare but operationally important —
+      // it usually signals key-rotation skew, DB corruption, or
+      // tampering. Emit an audit event so ops can spot it before the
+      // operator notices empty-`data` flows. data stays null so the
+      // session remains usable for non-data flows.
+      data = null;
+      try {
+        audit.safeEmit({
+          action:   "auth.session.data_unparseable",
+          outcome:  "failure",
+          reason:   (e && e.message) || String(e),
+          metadata: { hasUserId: !!unsealed.userId },
+        });
+      } catch (_ignored) { /* audit best-effort */ }
+    }
   }
   return {
     userId:       unsealed.userId,

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.2",
+  "version": "0.5.4",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",