@blamejs/core 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **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/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/package.json

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