@blamejs/core 0.15.12 → 0.15.14

package/lib/redact.js

@@ -37,6 +37,7 @@
  */
 
 var C = require("./constants");
+var safeBuffer = require("./safe-buffer");
 var lazyRequire = require("./lazy-require");
 var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
@@ -149,7 +150,7 @@ var VALUE_DETECTORS = [
     name:        "connection-string",
     test:        function (v) {
       if (typeof v !== "string" || v.length < C.BYTES.bytes(8)) return false; // bound BEFORE regex test
-      if (v.length > C.BYTES.kib(8)) return false;
+      if (safeBuffer.byteLengthOf(v) > C.BYTES.kib(8)) return false;
       // user may be empty (e.g. redis://:password@host); password
       // segment is required to flag this as a credentialed URI.
       return /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s:/?#]*:[^\s@/?#]+@/.test(v);
@@ -277,12 +278,16 @@ function redact(value, opts) {
 function _redact(value, depth, maxDepth, marker, parentKey) {
   if (depth > maxDepth) return marker;
   if (value === null || value === undefined) return value;
+  // A sensitive parent key collapses the ENTIRE value — scalar OR composite —
+  // to the marker. Checking before the type branches is what stops a secret
+  // under e.g. `authorization: ["Bearer …"]` / `password: {…}` from slipping
+  // through the array/object branches (which recurse with parentKey=null), the
+  // way a scalar already does (CWE-532 telemetry egress).
+  if (parentKey && _isSensitiveFieldName(parentKey)) return marker;
   if (typeof value === "string") {
-    if (parentKey && _isSensitiveFieldName(parentKey)) return marker;
     return _redactValue(value);
   }
   if (typeof value === "number" || typeof value === "boolean") {
-    if (parentKey && _isSensitiveFieldName(parentKey)) return marker;
     return value;
   }
   if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
@@ -512,7 +517,7 @@ function classifyDefaults(opts) {
         "redact.classifyDefaults: patterns[" + p + "] must be a string, got " +
         typeof patterns[p]);
     }
-    if (!CLASSIFIER_PATTERNS[patterns[p]] &&
+    if (!Object.prototype.hasOwnProperty.call(CLASSIFIER_PATTERNS, patterns[p]) &&
         !(opts.extra && opts.extra[patterns[p]])) {
       throw new DlpError("redact-dlp/unknown-pattern",
         "redact.classifyDefaults: unknown pattern '" + patterns[p] +

package/lib/render.js

@@ -28,6 +28,8 @@
  *   Server-side HTML / JSON / XML response helpers.
  */
 
+var validateOpts = require("./validate-opts");
+
 var DEFAULT_CHARSET = "utf-8";
 
 function _alreadyDone(res) {
@@ -53,8 +55,8 @@ function _writeResponse(res, status, headers, body) {
 function _mergedHeaders(base, extra) {
   if (!extra) return base;
   var out = {};
-  for (var k in base)  { if (Object.prototype.hasOwnProperty.call(base,  k)) out[k] = base[k]; }
-  for (var j in extra) { if (Object.prototype.hasOwnProperty.call(extra, j)) out[j] = extra[j]; }
+  validateOpts.assignOwnEnumerable(out, base);
+  validateOpts.assignOwnEnumerable(out, extra);
   return out;
 }
 

package/lib/request-helpers.js

@@ -42,6 +42,13 @@
 // every consumer reads HTTP_STATUS.<NAME> rather than the underlying
 // integer, so the hex form is purely an internal storage detail.
 var structuredFields = require("./structured-fields");
+var pick = require("./pick");
+var codepointClass = require("./codepoint-class");
+var lazyRequire = require("./lazy-require");
+// Lazy — ssrf-guard pulls in the network/DNS stack, and request-helpers is
+// required very early in the boot graph. Only touched at middleware-construction
+// time by trustedClientIp(), never on the hot path.
+var _ssrfGuard = lazyRequire(function () { return require("./ssrf-guard"); });
 
 var HTTP_STATUS = Object.freeze({
   OK:                            0xC8,
@@ -212,15 +219,24 @@ function resolveActorWithOverride(callerOpts, baseOverride) {
  *
  * Resolve the originating client IP from a request. Default reads
  * only `req.socket.remoteAddress` — `X-Forwarded-For` is ignored
- * because without a sanitizing reverse proxy it's
- * attacker-forgeable. Behind a trusted proxy, operators opt in via
- * `trustProxy: true` (use the leftmost XFF hop) or
- * `trustProxy: <N>` (skip N trusted hops from the right and return
- * the Nth-from-rightmost). Returns `null` when no address can be
- * read — never throws.
+ * because without a sanitizing reverse proxy it's attacker-forgeable.
+ *
+ * For an access-control decision (allowlist, rate-limit key, IP-bound
+ * grant), pass `trustProxy` as a PREDICATE `function(addr) => boolean`
+ * naming your trusted reverse proxies. The header is then honored only
+ * when the immediate TCP peer is itself a trusted proxy, and the client
+ * is the first untrusted address walking the chain right-to-left. A
+ * direct attacker cannot forge it — this is the only peer-gated form.
+ *
+ * The legacy `trustProxy: true` (leftmost XFF hop) and `trustProxy: <N>`
+ * (Nth-from-rightmost) forms do NOT verify the peer: a client connecting
+ * directly can forge any value. They are safe only when an upstream you
+ * control terminates and rewrites X-Forwarded-For on every request — never
+ * for a security decision on an internet-facing listener. Prefer the
+ * predicate form. Returns `null` when no address can be read — never throws.
  *
  * @opts
- *   trustProxy: boolean | number   // false (default) | true | hop count
+ *   trustProxy: boolean | number | function   // false (default) | predicate (peer-gated) | legacy true/hop-count
  *
  * @example
  *   var req = {
@@ -230,30 +246,55 @@ function resolveActorWithOverride(callerOpts, baseOverride) {
  *   b.requestHelpers.clientIp(req);
  *   // → "10.0.0.1"   (forwarded headers ignored by default)
  *
- *   b.requestHelpers.clientIp(req, { trustProxy: true });
- *   // → "203.0.113.7"   (leftmost XFF hop)
+ *   var fromTrusted = function (a) { return a.indexOf("10.") === 0; };
+ *   b.requestHelpers.clientIp(req, { trustProxy: fromTrusted });
+ *   // → "203.0.113.7"   (peer 10.0.0.1 trusted; first untrusted hop)
  *
- *   b.requestHelpers.clientIp(req, { trustProxy: 1 });
- *   // → "10.0.0.5"   (1 trusted hop from the right)
+ *   var forged = { socket: { remoteAddress: "198.51.100.66" },
+ *                  headers: { "x-forwarded-for": "203.0.113.7" } };
+ *   b.requestHelpers.clientIp(forged, { trustProxy: fromTrusted });
+ *   // → "198.51.100.66"   (peer untrusted → forged header ignored)
  *
  *   b.requestHelpers.clientIp(undefined);
  *   // → null
  */
 function clientIp(req, opts) {
   if (!req) return null;
+  var socketAddr =
+    (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;
   var trust = opts && opts.trustProxy;
   if (trust && req.headers) {
     var xff = req.headers["x-forwarded-for"];
     if (xff) {
       var hops = parseListHeader(xff);
-      if (trust === true) return hops[0];
-      if (typeof trust === "number" && trust >= 1 && hops.length >= trust) {
-        return hops[hops.length - trust];
+      if (hops.length) {
+        if (typeof trust === "function") {
+          // Peer-gated resolution: `trust(addr)` names the trusted reverse
+          // proxies. X-Forwarded-For is honored ONLY when the immediate TCP
+          // peer is itself a trusted proxy; the real client is then the first
+          // untrusted address walking the chain right-to-left (each hop is
+          // appended by the proxy that observed it). A direct attacker — whose
+          // 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)) {
+            for (var i = hops.length - 1; i >= 0; i--) {
+              if (!trust(hops[i])) return hops[i];
+            }
+            return hops[0];   // entire chain trusted — earliest claimed client
+          }
+          // peer is not a trusted proxy → ignore forgeable XFF, fall through
+        } else if (trust === true) {
+          return hops[0];
+        } else 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;
+  if (socketAddr) return socketAddr;
   // Express-shaped requests expose the resolved client address as `req.ip`
   // (Express derives it from the socket, honoring its own trust-proxy
   // setting) without a `socket.remoteAddress` surface. Fall back to it so a
@@ -264,6 +305,125 @@ function clientIp(req, opts) {
   return null;
 }
 
+/**
+ * @primitive b.requestHelpers.trustedClientIp
+ * @signature b.requestHelpers.trustedClientIp(opts?)
+ * @since     0.15.14
+ * @related   b.requestHelpers.clientIp
+ *
+ * Build a peer-gated client-IP resolver for an access-control decision
+ * (allowlist, rate-limit key, IP-bound grant). The bare `trustProxy`
+ * forms of `clientIp` are forgeable; this is the shape every gate shares
+ * so the trust model is identical across them. Returns
+ * `{ resolve(req), peerGated }`: `resolve` reads the client IP, `peerGated`
+ * is true when `trustedProxies` or `clientIpResolver` was supplied — a
+ * gate uses it to refuse a bare `trustProxy` at construction (fail closed).
+ *
+ * With `clientIpResolver(req)` the operator owns resolution entirely. With
+ * `trustedProxies` (CIDRs of the reverse proxies), `X-Forwarded-For` is
+ * honored only when the immediate peer is one of them. With neither, only
+ * the socket address is used and forwarded headers are ignored.
+ *
+ * @opts
+ *   trustedProxies:   string | string[],          // CIDRs — peer-gate X-Forwarded-For
+ *   clientIpResolver: function(req): string|null,  // own resolution entirely
+ *
+ * @example
+ *   var tip = b.requestHelpers.trustedClientIp({ trustedProxies: ["10.0.0.0/8"] });
+ *   var ip  = tip.resolve(req);   // peer-gated; forged XFF from a direct caller ignored
+ */
+// Build the trusted-proxy predicate shared by trustedClientIp / trustedProtocol.
+// Validates each CIDR (a CIDR is valid iff it contains its own network address,
+// reusing the same matcher the predicate uses so format rules can't diverge) and
+// returns fn(addr)=>boolean, or null when no trustedProxies were given. `where`
+// names the calling helper for the error message.
+function _trustedProxyPredicate(trustedProxies, where) {
+  if (!trustedProxies || !trustedProxies.length) return null;
+  var ssrfGuard = _ssrfGuard();
+  for (var i = 0; i < trustedProxies.length; i++) {
+    var cidr = trustedProxies[i];
+    var slash = typeof cidr === "string" ? cidr.indexOf("/") : -1;
+    if (slash === -1 || !ssrfGuard.cidrContains(cidr, cidr.slice(0, slash))) {
+      throw new TypeError(where + ": trustedProxies[" + i + "] is not a valid CIDR, got " + JSON.stringify(cidr));
+    }
+  }
+  return function (addr) {
+    // Fold an IPv4-mapped IPv6 peer (::ffff:a.b.c.d, common on a dual-stack
+    // listener) to its dotted IPv4 form so it matches an IPv4 trustedProxies
+    // CIDR — cidrContains rejects a cross-family compare, so without this a
+    // mapped proxy peer reads as untrusted and X-Forwarded-* is ignored. Only
+    // the ::ffff:0:0/96 block folds (canonicalizeHost leaves NAT64 / 6to4 as
+    // IPv6), so this can't widen the trusted set.
+    var canon = ssrfGuard.canonicalizeHost(addr);
+    for (var j = 0; j < trustedProxies.length; j++) {
+      if (ssrfGuard.cidrContains(trustedProxies[j], canon)) return true;
+    }
+    return false;
+  };
+}
+
+function _normTrustedProxies(opts) {
+  return Array.isArray(opts.trustedProxies) ? opts.trustedProxies.slice()
+    : (typeof opts.trustedProxies === "string" && opts.trustedProxies.length ? [opts.trustedProxies] : []);
+}
+
+function trustedClientIp(opts) {
+  opts = opts || {};
+  var resolver = opts.clientIpResolver;
+  if (resolver != null && typeof resolver !== "function") {
+    throw new TypeError("trustedClientIp: clientIpResolver must be a function(req) => ip|null");
+  }
+  var predicate = _trustedProxyPredicate(_normTrustedProxies(opts), "trustedClientIp");
+  return {
+    peerGated: !!(resolver || predicate),
+    resolve: function (req) {
+      if (resolver) return resolver(req);
+      if (predicate) return clientIp(req, { trustProxy: predicate });
+      return clientIp(req, { trustProxy: false });
+    },
+  };
+}
+
+/**
+ * @primitive b.requestHelpers.trustedProtocol
+ * @signature b.requestHelpers.trustedProtocol(opts?)
+ * @since     0.15.14
+ * @related   b.requestHelpers.requestProtocol, b.requestHelpers.trustedClientIp
+ *
+ * Peer-gated companion to trustedClientIp for the request scheme. The
+ * Secure-cookie / HSTS / secure-context decisions hinge on whether a request
+ * arrived over HTTPS; behind a TLS-terminating proxy that comes from
+ * X-Forwarded-Proto, which is forgeable unless the immediate peer is a trusted
+ * proxy. Returns `{ resolve(req)=>"http"|"https", peerGated }`. With
+ * `trustedProxies` (CIDRs) the header is honored only from a trusted peer; with
+ * `protocolResolver(req)` the operator owns the decision; with neither only the
+ * real TLS socket is consulted (forwarded headers ignored).
+ *
+ * @opts
+ *   trustedProxies:   string | string[],
+ *   protocolResolver: function(req): "http"|"https",
+ *
+ * @example
+ *   var tp = b.requestHelpers.trustedProtocol({ trustedProxies: ["10.0.0.0/8"] });
+ *   tp.resolve(req);   // "https" only when X-Forwarded-Proto came via a trusted peer
+ */
+function trustedProtocol(opts) {
+  opts = opts || {};
+  var resolver = opts.protocolResolver;
+  if (resolver != null && typeof resolver !== "function") {
+    throw new TypeError("trustedProtocol: protocolResolver must be a function(req) => 'http'|'https'");
+  }
+  var predicate = _trustedProxyPredicate(_normTrustedProxies(opts), "trustedProtocol");
+  return {
+    peerGated: !!(resolver || predicate),
+    resolve: function (req) {
+      if (resolver) return resolver(req);
+      if (predicate) return requestProtocol(req, { trustProxy: predicate });
+      return requestProtocol(req, { trustProxy: false });
+    },
+  };
+}
+
 /**
  * @primitive b.requestHelpers.requestProtocol
  * @signature b.requestHelpers.requestProtocol(req, opts?)
@@ -272,14 +432,17 @@ function clientIp(req, opts) {
  *
  * Resolve the inbound transport scheme. Default returns `"https"`
  * when `req.socket.encrypted` is set, otherwise `"http"`. Behind a
- * trusted reverse proxy that terminates TLS, set `trustProxy: true`
- * to read the leftmost `X-Forwarded-Proto` hop instead — without
- * the explicit opt-in the framework refuses to pick up the
- * attacker-forgeable header. Always returns a string; on bad input
- * falls back to `"http"`.
+ * trusted reverse proxy that terminates TLS, pass `trustProxy` as a
+ * PREDICATE `function(addr)=>boolean` naming your proxies:
+ * `X-Forwarded-Proto` is then honored only when the immediate peer is
+ * a trusted proxy, so a direct caller can't forge it (use
+ * `b.requestHelpers.trustedProtocol` to build this). The legacy
+ * `trustProxy: true` reads the leftmost hop without checking the peer —
+ * forgeable, safe only behind an edge that rewrites the header. Always
+ * returns a string; on bad input falls back to `"http"`.
  *
  * @opts
- *   trustProxy: boolean   // false (default) | true
+ *   trustProxy: boolean | function   // false (default) | predicate (peer-gated) | legacy true
  *
  * @example
  *   var req = { socket: { encrypted: true } };
@@ -303,7 +466,22 @@ function requestProtocol(req, opts) {
     var fwd = req.headers["x-forwarded-proto"];
     if (typeof fwd === "string" && fwd.length > 0) {
       var hops = parseListHeader(fwd, { lowercase: true });
-      if (hops.length > 0) return hops[0];
+      if (hops.length > 0) {
+        if (typeof trust === "function") {
+          // Peer-gated: honor X-Forwarded-Proto only when the immediate TCP
+          // peer is a trusted proxy. A direct caller's forged header is
+          // ignored — fall through to the real TLS socket. The only form safe
+          // for a Secure-cookie / HSTS / secure-context decision.
+          var peer =
+            (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];
+          // peer not a trusted proxy → ignore forgeable header, fall through
+        } else {
+          return hops[0];   // legacy true/number — spoofable, see docstring
+        }
+      }
     }
   }
   if (req.socket && req.socket.encrypted) return "https";
@@ -468,6 +646,91 @@ function resolveRoute(req) {
   return qIdx === -1 ? url : url.slice(0, qIdx);
 }
 
+/**
+ * @primitive  b.requestHelpers.makeSkipMatcher
+ * @signature  b.requestHelpers.makeSkipMatcher(opts, label)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.requestHelpers.resolveRoute
+ *
+ * Build a `(req) => boolean` path-match predicate shared by the state-change
+ * guards (`csrfProtect` / `fetchMetadata` / `botGuard` / `rateLimit`) AND the
+ * route-exemption / mount checks in `auth.accessLock`, `middleware.ageGate`,
+ * `middleware.botDisclose`, and `middleware.dailyByteQuota` — so a single route
+ * can be exempted (or a middleware mounted on a path subset) without each caller
+ * re-rolling the loop. `opts.skipPaths` entries are validated at build time —
+ * each must be a string or a RegExp — so an operator typo dies at boot, not on
+ * the first request; the optional `opts.skip(req)` predicate is validated the
+ * same way.
+ *
+ * A STRING entry matches on a SEGMENT BOUNDARY, not a raw prefix: `"/api"`
+ * matches `/api` and `/api/x` but NOT `/apixyz` — a raw `startsWith` would skip
+ * the guard on an unintended sibling path (a guard-bypass class). An entry that
+ * already ends in `/` is itself a segment prefix. Pass `exact: true` to require
+ * a whole-path match (no descendant). A RegExp entry uses `.test(path)`. The
+ * tested path is `req.pathname || req.url || req.originalUrl || "/"` with the
+ * query string stripped (matching is on the path, never the query). A `skip`
+ * predicate that throws is treated as "do not skip", so a buggy exemption can
+ * only keep the guard ON, never silently bypass it.
+ *
+ * @opts
+ *   skipPaths:  Array<string|RegExp>,   // string = segment-boundary match; RegExp = .test(path)
+ *   exact:      boolean,                // string entries match whole-path only (no descendant). default false
+ *   skip:       function,               // (req) => boolean, optional route-aware predicate
+ *
+ * @example
+ *   var shouldSkip = b.requestHelpers.makeSkipMatcher(
+ *     { skipPaths: ["/healthz", /^\/webhooks\//] }, "middleware.csrfProtect");
+ *   if (shouldSkip(req)) return next();
+ */
+// _skipStrMatch — does the request path match a single STRING skip entry?
+// SEGMENT-BOUNDARY semantics, NOT a raw `startsWith`: entry "/api" matches
+// "/api" and "/api/x" but NOT "/apixyz" (a raw prefix would wrongly skip the
+// guard on the sibling path — a guard-bypass class). An entry that already
+// ends in "/" is itself a segment prefix ("/webhooks/" matches "/webhooks/x").
+// `exact` restricts to a whole-path equality (no descendant match).
+function _skipStrMatch(path, entry, exact) {
+  if (exact) return path === entry;
+  if (entry.charAt(entry.length - 1) === "/") return path.indexOf(entry) === 0;
+  return path === entry || path.indexOf(entry + "/") === 0;
+}
+
+function makeSkipMatcher(opts, label) {
+  opts = opts || {};
+  label = label || "makeSkipMatcher";
+  var skipPaths = opts.skipPaths || [];
+  if (!Array.isArray(skipPaths)) {
+    throw new TypeError(label + ": skipPaths must be an array of string prefixes or RegExp");
+  }
+  for (var i = 0; i < skipPaths.length; i++) {
+    if (typeof skipPaths[i] !== "string" && !(skipPaths[i] instanceof RegExp)) {
+      throw new TypeError(label + ": skipPaths[" + i + "] must be a string prefix or RegExp, got " +
+        typeof skipPaths[i]);
+    }
+  }
+  var skipFn = opts.skip;
+  if (skipFn !== undefined && skipFn !== null && typeof skipFn !== "function") {
+    throw new TypeError(label + ": skip must be a function (req) => boolean");
+  }
+  var exact = opts.exact === true;
+  return function _shouldSkip(req) {
+    var path = (req && (req.pathname || req.url || req.originalUrl)) || "/";
+    var qpos = path.indexOf("?");
+    if (qpos !== -1) path = path.slice(0, qpos);   // match on the path, never the query string
+    for (var j = 0; j < skipPaths.length; j++) {
+      var entry = skipPaths[j];
+      if (typeof entry === "string" ? _skipStrMatch(path, entry, exact) : entry.test(path)) {
+        return true;
+      }
+    }
+    if (skipFn) {
+      try { return skipFn(req) === true; }
+      catch (_e) { return false; }
+    }
+    return false;
+  };
+}
+
 /**
  * @primitive b.requestHelpers.captureResponseStatus
  * @signature b.requestHelpers.captureResponseStatus(res, onEnd)
@@ -667,11 +930,8 @@ function extractBearer(req) {
   if (raw.indexOf(",") !== -1) return null;
   // Reject ASCII control characters BEFORE prefix-matching so a header
   // like "Bearer\rinjected" never reaches consumers.
-  for (var ci = 0; ci < raw.length; ci += 1) {
-    var cc = raw.charCodeAt(ci);
-    if (cc === 0x00 || cc === 0x0A || cc === 0x0D || cc === 0x09 || cc < 0x20 || cc === 0x7F) {
-      return null;
-    }
+  if (codepointClass.firstControlCharOffset(raw, { forbidTab: true }) !== -1) {
+    return null;
   }
   // RFC 6750 §2.1 — auth-scheme is case-insensitive. The "Bearer "
   // prefix + at least one token byte must be present; the literal
@@ -747,15 +1007,58 @@ function safeHeadersDistinct(req) {
     // skip __proto__ / constructor / prototype as keys — they are the
     // exact strings that triggered the upstream getter throw, and we
     // refuse to surface them as accessible header names.
-    if (lower === "__proto__" || lower === "constructor" || lower === "prototype") continue;
+    if (pick.isPoisonedKey(lower)) continue;
     if (out[lower]) out[lower].push(value);
     else out[lower] = [value];
   }
   return out;
 }
 
+/**
+ * @primitive  b.requestHelpers.makeResourceAuditEmitter
+ * @signature  b.requestHelpers.makeResourceAuditEmitter(sink, resourceKind, idFor?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.requestHelpers.extractActorContext
+ *
+ * Build a drop-silent audit emitter `(action, key, outcome, metadata, req)` for
+ * a request-scoped resource. The emitter is disabled when `sink` is falsy (the
+ * operator supplied no audit instance), so a primitive can wire it
+ * unconditionally and let the operator opt in by passing `opts.audit`. Each
+ * event carries `resource: { kind, id }` and, when a request is passed, the
+ * actor extracted from it (`extractActorContext`); a throwing sink is swallowed
+ * so audit emission can never break the request the event describes.
+ *
+ * The auth lockout / bot-challenge and session device-binding primitives emit
+ * this exact shape, varying only in the resource kind and how the id derives
+ * from the per-call key. `idFor(key)` maps the per-call key to the resource id
+ * (default: the key verbatim); pass it when the id needs a prefix or transform.
+ *
+ * @example
+ *   var emitAudit = b.requestHelpers.makeResourceAuditEmitter(
+ *     opts.audit, "auth.lockout", function (key) { return ns + ":" + key; });
+ *   emitAudit("locked", key, "denied", { attempts: n }, req);
+ */
+function makeResourceAuditEmitter(sink, resourceKind, idFor) {
+  return function (action, key, outcome, metadata, req) {
+    if (!sink) return;
+    try {
+      var event = {
+        action:   action,
+        outcome:  outcome,
+        resource: { kind: resourceKind, id: idFor ? idFor(key) : key },
+        metadata: metadata || {},
+      };
+      if (req) event.actor = extractActorContext(req);
+      sink.safeEmit(event);
+    } catch (_e) { /* audit best-effort — never let a sink throw escape */ }
+  };
+}
+
 module.exports = {
   resolveRoute:              resolveRoute,
+  makeResourceAuditEmitter:  makeResourceAuditEmitter,
+  makeSkipMatcher:           makeSkipMatcher,
   captureResponseStatus:     captureResponseStatus,
   extractActorContext:       extractActorContext,
   resolveActorWithOverride:  resolveActorWithOverride,
@@ -763,7 +1066,9 @@ module.exports = {
   parseListHeader:           parseListHeader,
   // proxy-trust primitives (default refuses forwarded headers)
   clientIp:                  clientIp,
+  trustedClientIp:           trustedClientIp,
   requestProtocol:           requestProtocol,
+  trustedProtocol:           trustedProtocol,
   appendVary:                appendVary,
   // CVE-2026-21710 wrap — safe alternative to req.headersDistinct
   safeHeadersDistinct:       safeHeadersDistinct,

package/lib/resource-access-lock.js

@@ -49,7 +49,7 @@ function create(opts) {
   validateOpts.requireNonEmptyString(opts.resource, "resource",
     ResourceAccessLockError, "resource-access-lock/no-resource");
   var startMode = opts.startMode || "open";
-  if (!VALID_MODES[startMode]) {
+  if (!Object.prototype.hasOwnProperty.call(VALID_MODES, startMode)) {
     throw new ResourceAccessLockError(
       "resource-access-lock/bad-start-mode",
       "startMode must be one of: " + Object.keys(VALID_MODES).join(" / "));
@@ -71,12 +71,12 @@ function create(opts) {
   function permits(action) {
     if (mode === "open") return true;
     if (mode === "locked") return false;
-    return !!READ_ACTIONS[action];
+    return !!Object.prototype.hasOwnProperty.call(READ_ACTIONS, action);
   }
 
   function set(newMode, ctx) {
     ctx = ctx || {};
-    if (!VALID_MODES[newMode]) {
+    if (!Object.prototype.hasOwnProperty.call(VALID_MODES, newMode)) {
       throw new ResourceAccessLockError(
         "resource-access-lock/bad-mode",
         "set: mode must be one of: " + Object.keys(VALID_MODES).join(" / "));

package/lib/restore-bundle.js

@@ -48,6 +48,7 @@
 var nodeFs = require("node:fs");
 var nodePath = require("node:path");
 var atomicFile = require("./atomic-file");
+var C = require("./constants");
 var backupCrypto = require("./backup/crypto");
 var backupManifest = require("./backup/manifest");
 var validateOpts = require("./validate-opts");
@@ -146,13 +147,21 @@ async function extract(opts) {
   // 1. Read + parse + validate manifest
   _emit(progress, { phase: "read_manifest" });
   var manifestPath = nodePath.join(bundleDir, "manifest.json");
-  if (!nodeFs.existsSync(manifestPath)) {
-    throw new RestoreBundleError("restore-bundle/missing-manifest",
-      "extract: bundleDir has no manifest.json — bundle is incomplete or not a blamejs backup");
-  }
+  // Capped fd-bound read OUTSIDE the parse try/catch, so a missing / oversized
+  // bundle manifest surfaces the precise restore-bundle code (not a generic
+  // parse error). A backup manifest is small JSON; 4 MiB bounds a hostile one
+  // before backupManifest.parse materializes it.
+  var manifestRaw = atomicFile.fdSafeReadSync(manifestPath, {
+    maxBytes: C.BYTES.mib(4), encoding: "utf8",
+    errorFor: function (kind, detail) {
+      if (kind === "enoent") return new RestoreBundleError("restore-bundle/missing-manifest", "extract: bundleDir has no manifest.json — bundle is incomplete or not a blamejs backup");
+      if (kind === "too-large") return new RestoreBundleError("restore-bundle/bad-manifest", "extract: manifest.json exceeds " + detail.max + " bytes");
+      return new RestoreBundleError("restore-bundle/bad-manifest", "extract: manifest unreadable: " + kind);
+    },
+  });
   var manifest;
   try {
-    manifest = backupManifest.parse(nodeFs.readFileSync(manifestPath, "utf8"));
+    manifest = backupManifest.parse(manifestRaw);
   } catch (e) {
     if (e && e.isBackupManifestError) throw e;
     throw new RestoreBundleError("restore-bundle/bad-manifest",
@@ -216,12 +225,20 @@ async function extract(opts) {
       }
 
       var blobPath = nodePath.join(bundleDir, entry.encryptedPath);
-      if (!nodeFs.existsSync(blobPath)) {
-        throw new RestoreBundleError("restore-bundle/missing-blob",
-          "extract: manifest references '" + entry.encryptedPath +
-          "' but the bundle has no such file");
-      }
-      var blob = nodeFs.readFileSync(blobPath);
+      // Cap the read to the manifest's declared encryptedSize so an oversize-on-
+      // disk blob is refused BEFORE it is read into memory (was: read fully, then
+      // compare → an OOM window for a huge swapped blob). A valid blob is exactly
+      // encryptedSize; the post-read compare still catches the under-size case.
+      var blobCap = (typeof entry.encryptedSize === "number" && entry.encryptedSize > 0)
+        ? entry.encryptedSize : C.BYTES.gib(8);
+      var blob = atomicFile.fdSafeReadSync(blobPath, {
+        maxBytes: blobCap,
+        errorFor: function (kind, detail) {
+          if (kind === "enoent") return new RestoreBundleError("restore-bundle/missing-blob", "extract: manifest references '" + entry.encryptedPath + "' but the bundle has no such file");
+          if (kind === "too-large") return new RestoreBundleError("restore-bundle/size-mismatch", "extract: blob '" + entry.encryptedPath + "' has size " + detail.size + " but manifest expected " + entry.encryptedSize);
+          return new RestoreBundleError("restore-bundle/missing-blob", "extract: blob '" + entry.encryptedPath + "' unreadable: " + kind);
+        },
+      });
       if (blob.length !== entry.encryptedSize) {
         throw new RestoreBundleError("restore-bundle/size-mismatch",
           "extract: blob '" + entry.encryptedPath + "' has size " + blob.length +
@@ -235,12 +252,18 @@ async function extract(opts) {
 
       var plaintext;
       try {
-        plaintext = await backupCrypto.decryptWithPassphrase(blob, passphrase, entry.salt);
+        // Bundles written with manifest.aadBound sealed each blob with its
+        // relativePath as AEAD associated data — pass the SAME path so a blob
+        // remapped to a different manifest entry fails the tag here (the
+        // blob-remap / restore-corruption defense). Legacy bundles without
+        // the flag decrypt with no AAD (backward compatible).
+        var blobAad = manifest.aadBound === true ? Buffer.from(entry.relativePath, "utf8") : undefined;
+        plaintext = await backupCrypto.decryptWithPassphrase(blob, passphrase, entry.salt, blobAad);
       } catch (e) {
         if (e && e.isBackupCryptoError && e.code === "backup-crypto/decrypt-failed") {
           throw new RestoreBundleError("restore-bundle/decrypt-failed",
             "extract: blob '" + entry.encryptedPath + "' did not decrypt — " +
-            "passphrase rejected or ciphertext tampered");
+            "passphrase rejected, ciphertext tampered, or blob remapped to a different path");
         }
         throw e;
       }
@@ -326,11 +349,16 @@ function inspect(opts) {
       "inspect: opts.bundleDir is required and must exist");
   }
   var manifestPath = nodePath.join(opts.bundleDir, "manifest.json");
-  if (!nodeFs.existsSync(manifestPath)) {
-    throw new RestoreBundleError("restore-bundle/missing-manifest",
-      "inspect: bundleDir has no manifest.json");
-  }
-  return backupManifest.parse(nodeFs.readFileSync(manifestPath, "utf8"));
+  // Capped fd-bound read (no-passphrase preview path, reachable with only read
+  // access to the bundle): bound a hostile manifest before parse.
+  return backupManifest.parse(atomicFile.fdSafeReadSync(manifestPath, {
+    maxBytes: C.BYTES.mib(4), encoding: "utf8",
+    errorFor: function (kind) {
+      if (kind === "enoent") return new RestoreBundleError("restore-bundle/missing-manifest", "inspect: bundleDir has no manifest.json");
+      if (kind === "too-large") return new RestoreBundleError("restore-bundle/bad-manifest", "inspect: manifest.json too large");
+      return new RestoreBundleError("restore-bundle/missing-manifest", "inspect: manifest unreadable: " + kind);
+    },
+  }));
 }
 
 module.exports = {