@blamejs/core 0.6.13 → 0.6.20

package/lib/file-type.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * file-type — magic-byte content detection.
+ *
+ * MIME on a multipart upload comes from the CLIENT — a malicious
+ * uploader can label a polyglot HTML payload as "image/png" and the
+ * Content-Type header alone won't catch it. This primitive inspects
+ * the leading bytes of a buffer against a hardcoded magic-byte
+ * registry and returns the actual format independently of the
+ * advertised MIME.
+ *
+ *   var detected = b.fileType.detect(buffer);
+ *   // → { mime: "image/png", extension: "png", category: "image" }
+ *   //   OR null when no signature matches
+ *
+ *   var ok = b.fileType.assertOneOf(buffer, ["image/png", "image/jpeg", "application/pdf"]);
+ *   // → throws FileTypeError if the actual format isn't in the allowlist
+ *
+ * Coverage targets the formats most likely to flow through a typical
+ * web app's upload boundary: images (PNG/JPEG/GIF/WEBP/AVIF/HEIC),
+ * documents (PDF/DOCX/XLSX/PPTX), archives (ZIP/RAR/7Z/TAR/GZ),
+ * audio/video (MP3/MP4/WEBM), and a small set of executable formats
+ * to deny on upload (PE/ELF/Mach-O). Operators with format coverage
+ * outside this list either pass an `extra` registry to extend, or
+ * fall back to libmagic via an external sandbox process.
+ *
+ * Validation policy:
+ *   - detect(buffer) → returns null on bad input rather than throwing
+ *     (saved-for-later analysis often runs against partial reads)
+ *   - assertOneOf(buffer, allowlist[, opts]) throws on mismatch.
+ *     Operator opt: `allowEmpty: true` to permit zero-length buffers
+ *     (default false — empty multipart parts are usually a mistake).
+ *
+ * Out of scope (operator brings their own):
+ *   - Content disarm (CDR — strip Office macros, PDF JS, etc.).
+ *     CDR is genuinely hard and format-specific; operators with that
+ *     requirement reach for a sandbox like dangerzone or vmray.
+ *   - Polyglot file detection (a single file that is BOTH valid PDF
+ *     AND valid HTML). detect() returns the first signature match;
+ *     true polyglot defense needs structural validation per format.
+ *   - Filename-extension validation. The framework's view is:
+ *     extensions are operator-controlled metadata, magic bytes are
+ *     the wire truth.
+ */
+var { defineClass } = require("./framework-error");
+
+var FileTypeError = defineClass("FileTypeError", { alwaysPermanent: true });
+var _err = FileTypeError.factory;
+
+// Signature registry. Each entry: { name, mime, extension, category,
+// offset, magic: Buffer | [Buffer, ...], extra?: function(buffer)→bool }.
+// Order matters — earlier entries win on ambiguous matches (e.g. ZIP
+// shape catches OOXML, so OOXML-specific entries come FIRST).
+var SIGNATURES = [
+  // ---- Office Open XML (DOCX/XLSX/PPTX) ----
+  // OOXML files are ZIP archives whose central directory contains
+  // [Content_Types].xml. The cheap shape-check is the ZIP local-file
+  // header (0x50 0x4B 0x03 0x04) PLUS the filename "[Content_Types].xml"
+  // appearing within the first 256 bytes — present for every
+  // well-formed OOXML produced by Office / LibreOffice / etc.
+  { name: "docx", mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    extension: "docx", category: "document",
+    offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
+    extra: function (buf) {
+      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      return head.indexOf("word/") !== -1 || head.indexOf("[Content_Types].xml") !== -1 && head.indexOf("word") !== -1;
+    } },
+  { name: "xlsx", mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    extension: "xlsx", category: "document",
+    offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
+    extra: function (buf) {
+      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      return head.indexOf("xl/") !== -1;
+    } },
+  { name: "pptx", mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    extension: "pptx", category: "document",
+    offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
+    extra: function (buf) {
+      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      return head.indexOf("ppt/") !== -1;
+    } },
+  // ---- Plain ZIP (after OOXML so OOXML wins) ----
+  { name: "zip", mime: "application/zip", extension: "zip", category: "archive",
+    offset: 0, magic: [
+      Buffer.from([0x50, 0x4B, 0x03, 0x04]),     // standard local file header
+      Buffer.from([0x50, 0x4B, 0x05, 0x06]),     // empty archive
+      Buffer.from([0x50, 0x4B, 0x07, 0x08]),     // spanned archive
+    ] },
+
+  // ---- Images ----
+  { name: "png",  mime: "image/png",  extension: "png", category: "image",
+    offset: 0, magic: Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]) },
+  { name: "jpeg", mime: "image/jpeg", extension: "jpg", category: "image",
+    offset: 0, magic: Buffer.from([0xFF, 0xD8, 0xFF]) },
+  { name: "gif",  mime: "image/gif",  extension: "gif", category: "image",
+    offset: 0, magic: [Buffer.from("GIF87a", "ascii"), Buffer.from("GIF89a", "ascii")] },
+  { name: "webp", mime: "image/webp", extension: "webp", category: "image",
+    offset: 0, magic: Buffer.from("RIFF", "ascii"),
+    extra: function (buf) {
+      return buf.length >= 12 && buf.subarray(8, 12).toString("ascii") === "WEBP";
+    } },
+  { name: "bmp",  mime: "image/bmp",  extension: "bmp", category: "image",
+    offset: 0, magic: Buffer.from([0x42, 0x4D]) },
+  { name: "tiff", mime: "image/tiff", extension: "tiff", category: "image",
+    offset: 0, magic: [
+      Buffer.from([0x49, 0x49, 0x2A, 0x00]),     // little-endian
+      Buffer.from([0x4D, 0x4D, 0x00, 0x2A]),     // big-endian
+    ] },
+  { name: "avif", mime: "image/avif", extension: "avif", category: "image",
+    offset: 4, magic: Buffer.from("ftypavif", "ascii") },
+  { name: "heic", mime: "image/heic", extension: "heic", category: "image",
+    offset: 4, magic: [
+      Buffer.from("ftypheic", "ascii"),
+      Buffer.from("ftypheix", "ascii"),
+      Buffer.from("ftypmif1", "ascii"),
+      Buffer.from("ftypmsf1", "ascii"),
+    ] },
+
+  // ---- Documents (non-OOXML) ----
+  { name: "pdf",  mime: "application/pdf", extension: "pdf", category: "document",
+    offset: 0, magic: Buffer.from("%PDF-", "ascii") },
+  { name: "rtf",  mime: "application/rtf", extension: "rtf", category: "document",
+    offset: 0, magic: Buffer.from("{\\rtf", "ascii") },
+  // CFB (Compound File Binary) — old Office (.doc/.xls/.ppt before 2007),
+  // also MSI installers.
+  { name: "cfb",  mime: "application/x-cfb", extension: "doc", category: "document",
+    offset: 0, magic: Buffer.from([0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1]) },
+
+  // ---- Archives ----
+  { name: "rar",  mime: "application/vnd.rar", extension: "rar", category: "archive",
+    offset: 0, magic: [
+      Buffer.from([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00]),       // RAR 1.5
+      Buffer.from([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00]), // RAR 5
+    ] },
+  { name: "7z",   mime: "application/x-7z-compressed", extension: "7z", category: "archive",
+    offset: 0, magic: Buffer.from([0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C]) },
+  { name: "gz",   mime: "application/gzip", extension: "gz", category: "archive",
+    offset: 0, magic: Buffer.from([0x1F, 0x8B]) },
+  { name: "bz2",  mime: "application/x-bzip2", extension: "bz2", category: "archive",
+    offset: 0, magic: Buffer.from("BZh", "ascii") },
+  { name: "xz",   mime: "application/x-xz", extension: "xz", category: "archive",
+    offset: 0, magic: Buffer.from([0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00]) },
+  { name: "tar",  mime: "application/x-tar", extension: "tar", category: "archive",
+    offset: 257, magic: Buffer.from("ustar", "ascii") },
+
+  // ---- Audio / video ----
+  { name: "mp3",  mime: "audio/mpeg", extension: "mp3", category: "audio",
+    offset: 0, magic: [
+      Buffer.from([0x49, 0x44, 0x33]),  // ID3v2 tag
+      Buffer.from([0xFF, 0xFB]),        // MPEG audio frame (no ID3)
+      Buffer.from([0xFF, 0xF3]),
+      Buffer.from([0xFF, 0xF2]),
+    ] },
+  { name: "mp4",  mime: "video/mp4", extension: "mp4", category: "video",
+    offset: 4, magic: [
+      Buffer.from("ftypisom", "ascii"),
+      Buffer.from("ftypiso2", "ascii"),
+      Buffer.from("ftypmp42", "ascii"),
+      Buffer.from("ftypM4V ", "ascii"),
+    ] },
+  { name: "webm", mime: "video/webm", extension: "webm", category: "video",
+    offset: 0, magic: Buffer.from([0x1A, 0x45, 0xDF, 0xA3]) },
+
+  // ---- Executables (operators usually DENY these on upload) ----
+  { name: "pe",     mime: "application/x-msdownload", extension: "exe", category: "executable",
+    offset: 0, magic: Buffer.from([0x4D, 0x5A]) },
+  { name: "elf",    mime: "application/x-executable", extension: "elf", category: "executable",
+    offset: 0, magic: Buffer.from([0x7F, 0x45, 0x4C, 0x46]) },
+  { name: "macho",  mime: "application/x-mach-binary", extension: "macho", category: "executable",
+    offset: 0, magic: [
+      Buffer.from([0xFE, 0xED, 0xFA, 0xCE]),     // 32-bit BE
+      Buffer.from([0xFE, 0xED, 0xFA, 0xCF]),     // 64-bit BE
+      Buffer.from([0xCE, 0xFA, 0xED, 0xFE]),     // 32-bit LE
+      Buffer.from([0xCF, 0xFA, 0xED, 0xFE]),     // 64-bit LE
+      Buffer.from([0xCA, 0xFE, 0xBA, 0xBE]),     // universal binary (also Java .class)
+    ] },
+];
+
+function _matchesAt(buf, offset, magic) {
+  if (buf.length < offset + magic.length) return false;
+  for (var i = 0; i < magic.length; i++) {
+    if (buf[offset + i] !== magic[i]) return false;
+  }
+  return true;
+}
+
+function _entryMatches(entry, buf) {
+  var magics = Array.isArray(entry.magic) ? entry.magic : [entry.magic];
+  var matched = false;
+  for (var i = 0; i < magics.length; i++) {
+    if (_matchesAt(buf, entry.offset || 0, magics[i])) { matched = true; break; }
+  }
+  if (!matched) return false;
+  if (typeof entry.extra === "function") {
+    try { return !!entry.extra(buf); }
+    catch (_e) { return false; }
+  }
+  return true;
+}
+
+function detect(buf, opts) {
+  if (!Buffer.isBuffer(buf)) {
+    if (buf instanceof Uint8Array) buf = Buffer.from(buf);
+    else return null;
+  }
+  if (buf.length === 0) return null;
+  var registry = SIGNATURES;
+  if (opts && Array.isArray(opts.extra) && opts.extra.length > 0) {
+    // Operator-extended registry: extras come FIRST so an operator can
+    // override a built-in (e.g. tighten OOXML check) without forking.
+    registry = opts.extra.concat(SIGNATURES);
+  }
+  for (var i = 0; i < registry.length; i++) {
+    var entry = registry[i];
+    if (_entryMatches(entry, buf)) {
+      return { mime: entry.mime, extension: entry.extension, category: entry.category, name: entry.name };
+    }
+  }
+  return null;
+}
+
+function assertOneOf(buf, allowlist, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(buf) && !(buf instanceof Uint8Array)) {
+    throw _err("BAD_INPUT", "fileType.assertOneOf: input must be a Buffer or Uint8Array, got " + typeof buf);
+  }
+  if (Buffer.isBuffer(buf) === false) buf = Buffer.from(buf);
+  if (buf.length === 0) {
+    if (opts.allowEmpty === true) return null;
+    throw _err("EMPTY", "fileType.assertOneOf: input is zero bytes");
+  }
+  if (!Array.isArray(allowlist) || allowlist.length === 0) {
+    throw _err("BAD_OPT", "fileType.assertOneOf: allowlist must be a non-empty array");
+  }
+  var detected = detect(buf, opts);
+  if (!detected) {
+    throw _err("UNKNOWN_TYPE",
+      "fileType.assertOneOf: no signature matched the leading bytes (advertised MIME cannot be trusted alone)");
+  }
+  // allowlist entries match against `mime` OR `name` OR `category` —
+  // operators can pin "image/png" specifically OR "image" for the
+  // whole image bucket.
+  var allowed = false;
+  for (var i = 0; i < allowlist.length; i++) {
+    if (allowlist[i] === detected.mime ||
+        allowlist[i] === detected.name ||
+        allowlist[i] === detected.category) {
+      allowed = true; break;
+    }
+  }
+  if (!allowed) {
+    throw _err("DISALLOWED_TYPE",
+      "fileType.assertOneOf: detected '" + detected.mime + "' (" + detected.name +
+      ", category=" + detected.category + ") not in allowlist " + JSON.stringify(allowlist));
+  }
+  return detected;
+}
+
+module.exports = {
+  detect:        detect,
+  assertOneOf:   assertOneOf,
+  FileTypeError: FileTypeError,
+  // Internal — exposed so tests can introspect the registry shape.
+  _SIGNATURES:   SIGNATURES,
+};

package/lib/http-client.js

@@ -73,6 +73,7 @@ var safeAsync = require("./safe-async");
 var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
 var ssrfGuard = require("./ssrf-guard");
+var networkProxy = require("./network-proxy");
 var { FrameworkError } = require("./framework-error");
 
 // Per-origin transport cache. Entry is either the resolved transport
@@ -670,6 +671,71 @@ function _requestSingle(opts) {
     return Promise.reject(e);
   }
 
+  // Optional outbound destination allowlist. When opts.allowedHosts
+  // is set, only URLs whose hostname is on the list are permitted.
+  // Layer above safeUrl (scheme/userinfo gate) and above ssrfGuard
+  // (IP-class gate) — operators with strict egress policies pin the
+  // outbound destinations the app is allowed to talk to so a
+  // compromised process can't reach arbitrary upstreams.
+  //
+  // Entry forms (each entry is a string OR an object):
+  //   "api.partner.com"            — exact host match
+  //   ".partner.com"               — suffix match: "api.partner.com" yes,
+  //                                  "evilpartner.com" no
+  //   "*.partner.com"              — same as ".partner.com" (DNS-glob shape
+  //                                  operators expect from firewall configs)
+  //   { host: "api.x.com", methods: ["GET","HEAD"] }
+  //                                — method-restricted entry; methods omitted
+  //                                  = any method
+  //
+  // A disallowed call rejects with HOST_DISALLOWED AND emits an
+  // audit event when opts.audit is wired (operator gets a structured
+  // signal that the application tried to reach somewhere it shouldn't).
+  if (Array.isArray(opts.allowedHosts) && opts.allowedHosts.length > 0) {
+    var host = u.hostname.toLowerCase();
+    var method = (opts.method || "GET").toUpperCase();
+    var ok = false;
+    for (var ai = 0; ai < opts.allowedHosts.length; ai++) {
+      var entry = opts.allowedHosts[ai];
+      var allow, allowedMethods = null;
+      if (typeof entry === "object" && entry !== null) {
+        allow = String(entry.host || "").toLowerCase();
+        if (Array.isArray(entry.methods) && entry.methods.length > 0) {
+          allowedMethods = entry.methods.map(function (m) { return String(m).toUpperCase(); });
+        }
+      } else {
+        allow = String(entry || "").toLowerCase();
+      }
+      if (allow.length === 0) continue;
+      // Normalise "*.x.com" to ".x.com" for the suffix match path.
+      if (allow.charAt(0) === "*" && allow.charAt(1) === ".") allow = allow.slice(1);
+      var matched = false;
+      if (allow.charAt(0) === ".") {
+        if (host === allow.slice(1) || host.endsWith(allow)) matched = true;
+      } else if (host === allow) {
+        matched = true;
+      }
+      if (!matched) continue;
+      if (allowedMethods !== null && allowedMethods.indexOf(method) === -1) continue;
+      ok = true;
+      break;
+    }
+    if (!ok) {
+      if (opts.audit && typeof opts.audit.safeEmit === "function") {
+        try {
+          opts.audit.safeEmit({
+            action:   "system.httpclient.host_denied",
+            outcome:  "denied",
+            resource: { kind: "outbound.http", id: host },
+            metadata: { method: method, url: opts.url, allowedHostsCount: opts.allowedHosts.length },
+          });
+        } catch (_e) { /* audit best-effort */ }
+      }
+      return Promise.reject(_makeError(opts.errorClass, "HOST_DISALLOWED",
+        "host '" + host + "' not in allowedHosts (method=" + method + ")", true));
+    }
+  }
+
   // Attach jar-derived Cookie header BEFORE the request fires; record
   // Set-Cookie response headers AFTER. Both halves run when opts.jar
   // is set; redirect-following naturally re-runs both paths per hop
@@ -702,6 +768,17 @@ function _requestSingle(opts) {
       }, u, opts);
     }
 
+    var proxyAgent = null;
+    try { proxyAgent = networkProxy.agentFor(u); } catch (_e) { proxyAgent = null; }
+    if (proxyAgent) {
+      return _requestH1({
+        kind:   "h1",
+        lib:    u.protocol === "https:" ? https : http,
+        agent:  proxyAgent,
+        lookup: undefined,
+      }, u, opts);
+    }
+
     return _getTransport(u, opts, ips).then(function (transport) {
       if (transport.kind === "h2") return _requestH2(transport, u, opts);
       return _requestH1(transport, u, opts);

package/lib/internal-sha1-hibp.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * internal-sha1-hibp — SHA-1 hex digest, RESTRICTED to the
+ * HaveIBeenPwned k-anonymity API caller (lib/auth/password.js policy).
+ *
+ * SHA-1 is broken for collision-resistance and trivially extendable;
+ * the framework MUST NOT use it for storage, signing, message
+ * authentication, key derivation, fingerprinting, or any other
+ * security-relevant path. The HIBP API mandates SHA-1 for backwards
+ * compatibility with leaked-password corpora; that's the only reason
+ * this exists.
+ *
+ * Why not export from b.crypto:
+ *   - Public exports invite cargo-cult use. A future contributor
+ *     would search `b.crypto.sha1*` and slot it into "I just need
+ *     a quick hash" code — re-introducing SHA-1 into a crypto-
+ *     relevant path the framework spent every other primitive
+ *     keeping out.
+ *   - The single legitimate caller (auth/password.js) requires it
+ *     for HIBP interop only. Restricting it to that module via a
+ *     filename + comment-block gate keeps the surface honest.
+ *
+ * If a SECOND legitimate use case for SHA-1 ever emerges (operator
+ * needs to interop with another SHA-1-mandated API), this module
+ * stays internal — the new caller imports it directly. Public
+ * `b.crypto.sha1*` is permanently off the table.
+ */
+var nodeCrypto = require("node:crypto");
+
+function sha1Hex(data) {
+  return nodeCrypto.createHash("sha1").update(data).digest("hex");
+}
+
+module.exports = { sha1Hex: sha1Hex };

package/lib/middleware/csp-nonce.js

@@ -248,10 +248,13 @@ function create(opts) {
   var property = (typeof opts.property === "string" && opts.property.length > 0) ? opts.property : "cspNonce";
   var always = !!opts.always;
 
-  // Placeholder for the cacheable-render pattern. Per-instance random
-  // by default — multiple cspNonce instances in the same process get
-  // different placeholders, and the literal string never appears in
-  // source so operator content can't accidentally collide.
+  // Token string used by the cacheable-render pattern: templates render
+  // with `cspNonce: nonceMw.PLACEHOLDER`, the rendered HTML is cached,
+  // then nonceMw.substitute(html, req) swaps in the per-request nonce
+  // at serve time. Per-instance random by default — multiple cspNonce
+  // instances in the same process get different placeholders, and the
+  // literal string never appears in source so operator content can't
+  // accidentally collide.
   //
   // Operators with caches that persist across process restarts (Redis,
   // cluster backend) pass `opts.placeholder` to pin a stable token —

package/lib/middleware/index.js

@@ -34,6 +34,7 @@ module.exports = {
   requestLog:      require("./request-log").create,
   apiEncrypt:      require("./api-encrypt"),
   dbRoleFor:       require("./db-role-for").create,
+  networkAllowlist: require("./network-allowlist").create,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {
@@ -54,5 +55,6 @@ module.exports = {
     requestLog:      require("./request-log"),
     apiEncrypt:      require("./api-encrypt"),
     dbRoleFor:       require("./db-role-for"),
+    networkAllowlist: require("./network-allowlist"),
   },
 };

package/lib/middleware/network-allowlist.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * network-allowlist — restrict an opt-named set of paths to operator-
+ * approved CIDR ranges.
+ *
+ * Path-based admin gates (perms.require, requireAuth) prevent UNAUTHORIZED
+ * users from reaching sensitive routes. They do NOT prevent the route
+ * from being REACHABLE from the public internet — a credential leak +
+ * a path-only gate is full compromise. Operators with a clear admin/
+ * non-admin network split want a network-layer fence on top of the
+ * application-layer gate.
+ *
+ * The cleanest place for that fence is the reverse proxy / NACL. This
+ * middleware is the in-process equivalent for operators who don't have
+ * separate infrastructure for it (small deploys, single-process apps,
+ * the wiki example default).
+ *
+ *   var fence = b.middleware.networkAllowlist({
+ *     paths:        ["/admin", "/admin/", "/healthz/internal"],
+ *     allowedCidrs: ["10.0.0.0/8", "192.168.0.0/16", "::1/128"],
+ *     trustProxy:   true,         // honour x-forwarded-for; default false
+ *     denyStatus:   404,          // default — reveal nothing about the gate
+ *     denyBody:     "Not Found",  // default
+ *     audit:        b.audit,      // default: null — emits network.gate.denied
+ *   });
+ *
+ *   router.use(fence);
+ *
+ * Behaviour:
+ *   - The middleware is path-scoped: requests whose pathname doesn't
+ *     start with any of `paths` pass through unchanged. Hot-path-cheap.
+ *   - Requests on a gated path get their client IP resolved through
+ *     b.requestHelpers.clientIp(req, { trustProxy }) — same trust
+ *     model as every other middleware that reads client IP.
+ *   - The IP is checked against the CIDR allowlist using
+ *     b.ssrfGuard.cidrContains. A miss returns denyStatus + denyBody
+ *     and audits the rejection. Default 404 hides the gate's
+ *     existence from probes.
+ *
+ * Validation policy:
+ *   - opts: throw at create() time on bad shape (not-array paths /
+ *     allowedCidrs, non-CIDR strings, denyStatus outside 4xx/5xx).
+ *   - Per-request: a request that looks malformed (no socket, no
+ *     headers) gets denied — fail closed.
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var ssrfGuard = require("../ssrf-guard");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var NetworkAllowlistError = defineClass("NetworkAllowlistError", { alwaysPermanent: true });
+var _err = NetworkAllowlistError.factory;
+
+function _validateCidr(cidr) {
+  // ssrfGuard.cidrContains tolerates any string at runtime (returns
+  // false on garbage), but the operator means business at config time
+  // — a typo'd CIDR silently disables that allow entry. Verify the
+  // shape now: <ipv4-or-ipv6>/<prefix-length>.
+  if (typeof cidr !== "string" || cidr.length === 0) return false;
+  var slash = cidr.indexOf("/");
+  if (slash < 1 || slash >= cidr.length - 1) return false;
+  var prefix = parseInt(cidr.slice(slash + 1), 10);
+  if (!isFinite(prefix) || prefix < 0) return false;
+  // Smoke-test the implementation against a known value — if it
+  // throws, the cidr is malformed.
+  try { ssrfGuard.cidrContains(cidr, "127.0.0.1"); return true; }
+  catch (_e) { return false; }
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "paths", "allowedCidrs", "deniedCidrs", "trustProxy",
+    "denyStatus", "denyBody", "audit",
+  ], "middleware.networkAllowlist");
+
+  if (!Array.isArray(opts.paths) || opts.paths.length === 0) {
+    throw _err("BAD_OPT", "paths must be a non-empty array of pathname prefixes");
+  }
+  for (var pi = 0; pi < opts.paths.length; pi++) {
+    if (typeof opts.paths[pi] !== "string" || opts.paths[pi].charAt(0) !== "/") {
+      throw _err("BAD_OPT",
+        "paths[" + pi + "] must be a string starting with '/', got " + JSON.stringify(opts.paths[pi]));
+    }
+  }
+  if (!Array.isArray(opts.allowedCidrs) || opts.allowedCidrs.length === 0) {
+    throw _err("BAD_OPT", "allowedCidrs must be a non-empty array of CIDR strings");
+  }
+  for (var ci = 0; ci < opts.allowedCidrs.length; ci++) {
+    if (!_validateCidr(opts.allowedCidrs[ci])) {
+      throw _err("BAD_OPT",
+        "allowedCidrs[" + ci + "] is not a valid CIDR, got " + JSON.stringify(opts.allowedCidrs[ci]));
+    }
+  }
+  // deniedCidrs takes precedence over allowedCidrs (deny-then-allow)
+  // — useful when an operator wants "10.0.0.0/8 except 10.0.99.0/24".
+  // Default empty (no deny rules).
+  var deniedCidrs = Array.isArray(opts.deniedCidrs) ? opts.deniedCidrs.slice() : [];
+  for (var di = 0; di < deniedCidrs.length; di++) {
+    if (!_validateCidr(deniedCidrs[di])) {
+      throw _err("BAD_OPT",
+        "deniedCidrs[" + di + "] is not a valid CIDR, got " + JSON.stringify(deniedCidrs[di]));
+    }
+  }
+
+  var paths        = opts.paths.slice();
+  var allowedCidrs = opts.allowedCidrs.slice();
+  var trustProxy   = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var denyStatus   = typeof opts.denyStatus === "number" ? opts.denyStatus : 404;
+  if (denyStatus < 400 || denyStatus >= 600 || Math.floor(denyStatus) !== denyStatus) {
+    throw _err("BAD_OPT", "denyStatus must be a 4xx or 5xx integer, got " + denyStatus);
+  }
+  var denyBody     = typeof opts.denyBody === "string" ? opts.denyBody : "Not Found";
+  var auditOn      = opts.audit !== false && opts.audit != null;
+  var auditInstance = opts.audit === true ? null : opts.audit;  // null → use lazy-required default
+
+  function _emitDeny(req, ip, route) {
+    if (!auditOn) return;
+    var sink = auditInstance || audit();
+    try {
+      sink.safeEmit({
+        action:   "network.gate.denied",
+        outcome:  "denied",
+        actor:    requestHelpers.extractActorContext(req),
+        resource: { kind: "http.path", id: route },
+        reason:   "ip-not-in-allowlist",
+        metadata: { clientIp: ip, allowedCidrs: allowedCidrs },
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  function _matchesPath(pathname) {
+    for (var i = 0; i < paths.length; i++) {
+      var prefix = paths[i];
+      if (pathname === prefix) return true;
+      // Boundary-aware: "/admin" matches "/admin" + "/admin/..." but
+      // not "/administer" — prevents accidental shadowing of
+      // similarly-named public routes.
+      if (pathname.length > prefix.length &&
+          pathname.indexOf(prefix) === 0 &&
+          (prefix.charAt(prefix.length - 1) === "/" || pathname.charAt(prefix.length) === "/")) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  return function networkAllowlist(req, res, next) {
+    var pathname = req.pathname || (req.url || "").split("?")[0];
+    if (!_matchesPath(pathname)) return next();
+
+    var ip = requestHelpers.clientIp(req, { trustProxy: trustProxy });
+    if (!ip) {
+      // Fail closed: a request we can't even derive an IP for shouldn't
+      // bypass the gate.
+      _emitDeny(req, "<unknown>", pathname);
+      res.writeHead(denyStatus, { "Content-Type": "text/plain" });
+      res.end(denyBody);
+      return;
+    }
+
+    // Deny-then-allow precedence: an explicit deny entry beats any
+    // allow entry that would otherwise match. Operators use this for
+    // "10.0.0.0/8 EXCEPT 10.0.99.0/24" patterns.
+    for (var dii = 0; dii < deniedCidrs.length; dii++) {
+      try {
+        if (ssrfGuard.cidrContains(deniedCidrs[dii], ip)) {
+          _emitDeny(req, ip, pathname);
+          res.writeHead(denyStatus, { "Content-Type": "text/plain" });
+          res.end(denyBody);
+          return;
+        }
+      } catch (_e) { /* skip malformed at runtime — caught at config */ }
+    }
+    var allowed = false;
+    for (var i = 0; i < allowedCidrs.length; i++) {
+      try {
+        if (ssrfGuard.cidrContains(allowedCidrs[i], ip)) { allowed = true; break; }
+      } catch (_e) { /* skip malformed at runtime — caught at config */ }
+    }
+    if (!allowed) {
+      _emitDeny(req, ip, pathname);
+      res.writeHead(denyStatus, { "Content-Type": "text/plain" });
+      res.end(denyBody);
+      return;
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create:                 create,
+  NetworkAllowlistError:  NetworkAllowlistError,
+};