@blamejs/core 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -6,6 +6,12 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.4.x
+
+- **0.4.2** (2026-04-30) — npm keywords
+- **0.4.1** (2026-04-29) — wiki bot-guard skips /healthz so the post-publish smoke check passes
+- **0.4.0** (2026-04-29) — bench suite + drops the deprecated b.logger.createLogger
+
 ## v0.3.x
 
 - **0.3.39** (2026-04-29) — MIGRATING.md generator scans deprecate() calls in lib/

package/index.js

@@ -85,6 +85,7 @@ var httpClient = require("./lib/http-client");
 httpClient.encrypted = require("./lib/middleware/api-encrypt").httpClient;
 var websocket = require("./lib/websocket");
 var safeUrl = require("./lib/safe-url");
+var ssrfGuard = require("./lib/ssrf-guard");
 var authHeader = require("./lib/auth-header");
 var auth = {
   password: require("./lib/auth/password"),
@@ -191,6 +192,7 @@ module.exports = {
   httpClient:       httpClient,
   websocket:        websocket,
   safeUrl:          safeUrl,
+  ssrfGuard:        ssrfGuard,
   authHeader:       authHeader,
   auth:             auth,
   template:         template,

package/lib/auth/oauth.js

@@ -268,7 +268,8 @@ function create(opts) {
                            ? opts.discoveryCacheMs : DEFAULT_DISCOVERY_CACHE_MS;
   var acceptedAlgorithms = Array.isArray(opts.acceptedAlgorithms) && opts.acceptedAlgorithms.length > 0
                              ? opts.acceptedAlgorithms.slice() : DEFAULT_ACCEPTED_ALGS.slice();
-  var allowHttp        = !!opts.allowHttp;          // localhost dev opt-in
+  var allowHttp        = !!opts.allowHttp;          // localhost dev opt-in (scheme)
+  var allowInternal    = opts.allowInternal != null ? opts.allowInternal : null; // localhost dev opt-in (SSRF gate)
   var httpClientOpts   = opts.httpClient || {};
   var responseMode     = opts.responseMode || null;
 
@@ -341,6 +342,7 @@ function create(opts) {
       method: "GET",
     }, fetchOpts);
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
     if (res.statusCode < 200 || res.statusCode >= 300) {
@@ -505,6 +507,7 @@ function create(opts) {
       body:    Buffer.from(body.toString(), "utf8"),
     };
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
     // RFC 7009: 200 even if the token was already revoked / unknown.
@@ -526,6 +529,7 @@ function create(opts) {
       body:    Buffer.from(body.toString(), "utf8"),
     };
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
     var text = res.body ? res.body.toString("utf8") : "";

package/lib/http-client.js

@@ -70,6 +70,7 @@ var pqcAgent = require("./pqc-agent");
 var safeAsync = require("./safe-async");
 var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
+var ssrfGuard = require("./ssrf-guard");
 var { FrameworkError } = require("./framework-error");
 
 // Per-origin transport cache. Entry is either the resolved transport
@@ -310,18 +311,26 @@ function request(opts) {
     return Promise.reject(e);
   }
 
-  // Caller-supplied agent bypasses transport cache (h1 only).
-  if (opts.agent) {
-    return _requestH1({
-      kind: "h1",
-      lib:  u.protocol === "https:" ? https : http,
-      agent: opts.agent,
-    }, u, 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).
+  return ssrfGuard.checkUrl(u, {
+    allowInternal: opts.allowInternal,
+    errorClass:    opts.errorClass,
+  }).then(function () {
+    // Caller-supplied agent bypasses transport cache (h1 only).
+    if (opts.agent) {
+      return _requestH1({
+        kind: "h1",
+        lib:  u.protocol === "https:" ? https : http,
+        agent: opts.agent,
+      }, u, opts);
+    }
 
-  return _getTransport(u, opts).then(function (transport) {
-    if (transport.kind === "h2") return _requestH2(transport, u, opts);
-    return _requestH1(transport, u, opts);
+    return _getTransport(u, opts).then(function (transport) {
+      if (transport.kind === "h2") return _requestH2(transport, u, opts);
+      return _requestH1(transport, u, opts);
+    });
   });
 }
 

package/lib/log-stream-webhook.js

@@ -60,7 +60,7 @@ function _authHeaders(config) {
   return authHeader.fromConfig(config);
 }
 
-function _post(url, body, headers, timeoutMs, allowedProtocols) {
+function _post(url, body, headers, timeoutMs, allowedProtocols, allowInternal) {
   return httpClient.request({
     method:           "POST",
     url:              url,
@@ -70,6 +70,7 @@ function _post(url, body, headers, timeoutMs, allowedProtocols) {
     maxResponseBytes: MAX_RESPONSE_BYTES,
     errorClass:       LogStreamError,
     allowedProtocols: allowedProtocols,
+    allowInternal:    allowInternal,
   });
 }
 
@@ -118,7 +119,7 @@ function create(config) {
         var body = _serializeBatch(batch, cfg.bodyShape);
         try {
           await retryHelper.withRetry(function () {
-            return _post(cfg.url, body, headers, cfg.timeoutMs, cfg.allowedProtocols);
+            return _post(cfg.url, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
           }, cfg.retry);
         } catch {
           // Batch permanently rejected — surface via the dropped counter.

package/lib/mail.js

@@ -468,6 +468,7 @@ function httpTransport(opts) {
   var baseHeaders      = opts.headers || {};
   var timeoutMs        = opts.timeoutMs || 15000;
   var allowedProtocols = opts.allowedProtocols || null;
+  var allowInternal    = opts.allowInternal != null ? opts.allowInternal : null;
   var interpret        = typeof opts.interpret === "function" ? opts.interpret : null;
   var serialize        = opts.serialize;
   var codePrefix       = "mail/" + name;
@@ -505,6 +506,7 @@ function httpTransport(opts) {
         errorClass: MailError, // http-client constructs (code, message, permanent, statusCode)
       };
       if (allowedProtocols) reqOpts.allowedProtocols = allowedProtocols;
+      if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
       var res;
       try {
@@ -568,6 +570,7 @@ function resendTransport(opts) {
     method:           "POST",
     timeoutMs:        opts.timeoutMs || 15000,
     allowedProtocols: opts.allowedProtocols || null,
+    allowInternal:    opts.allowInternal != null ? opts.allowInternal : null,
     headers: {
       "Authorization": "Bearer " + opts.apiKey,
       "Content-Type":  "application/json",

package/lib/middleware/api-encrypt.js

@@ -512,7 +512,7 @@ function httpClientEncrypted(opts) {
     headers["Content-Type"] = "application/json";
 
     var passThrough = {};
-    var passable = ["allowedProtocols", "idleTimeoutMs", "maxResponseBytes",
+    var passable = ["allowedProtocols", "allowInternal", "idleTimeoutMs", "maxResponseBytes",
                     "agent", "errorClass"];
     for (var i = 0; i < passable.length; i++) {
       if (reqOpts[passable[i]] !== undefined) passThrough[passable[i]] = reqOpts[passable[i]];

package/lib/notify.js

@@ -187,6 +187,7 @@ function httpJson(opts) {
     throw _err("BAD_OPT", "notify.transports.httpJson: url is required");
   }
   var allowedProtocols = opts.allowHttp ? safeUrl.ALLOW_HTTP_ALL : safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal = opts.allowInternal != null ? opts.allowInternal : null;
   // Validate URL at create time so bad URLs surface at boot, not at first send.
   safeUrl.parse(opts.url, { allowedProtocols: allowedProtocols, errorClass: NotifyError });
 
@@ -238,6 +239,7 @@ function httpJson(opts) {
         headers:          headers,
         body:             body,
         allowedProtocols: allowedProtocols,
+        allowInternal:    allowInternal,
         errorClass:       NotifyError,
       });
       var status = (res && (res.statusCode || res.status)) || 0;

package/lib/object-store/azure-blob.js

@@ -73,6 +73,7 @@ function _httpRequest(method, urlObj, headers, body, opts) {
     maxResponseBytes: opts && opts.maxResponseBytes,
     errorClass:       ObjectStoreError,
     allowedProtocols: opts && opts.allowedProtocols,
+  ...((opts && opts.allowInternal !== undefined) ? { allowInternal: opts.allowInternal } : {}),
   });
 }
 
@@ -193,8 +194,10 @@ function create(config) {
   // HTTPS-only by default — real Azure is always HTTPS. Operators with
   // an Azurite emulator endpoint opt in via config.allowedProtocols.
   var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal    = config.allowInternal != null ? config.allowInternal : null;
   safeUrl.parse(endpoint, { allowedProtocols: allowedProtocols, errorClass: ObjectStoreError });
   var reqOpts = { timeoutMs: timeoutMs, allowedProtocols: allowedProtocols };
+  if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
   function _blobUrl(key, params) {
     var u = new URL(endpoint + "/" + config.container + "/" + key);

package/lib/object-store/gcs.js

@@ -81,6 +81,7 @@ function _httpRequest(method, urlObj, headers, body, opts) {
     maxResponseBytes: opts && opts.maxResponseBytes,
     errorClass:       ObjectStoreError,
     allowedProtocols: opts && opts.allowedProtocols,
+  ...((opts && opts.allowInternal !== undefined) ? { allowInternal: opts.allowInternal } : {}),
   });
 }
 
@@ -143,9 +144,11 @@ function create(config) {
   // HTTPS-only by default — google APIs are always HTTPS. Operators with
   // an emulator / private fake-GCS endpoint opt in via config.allowedProtocols.
   var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal    = config.allowInternal != null ? config.allowInternal : null;
   safeUrl.parse(endpoint,      { allowedProtocols: allowedProtocols, errorClass: ObjectStoreError });
   safeUrl.parse(tokenEndpoint, { allowedProtocols: allowedProtocols, errorClass: ObjectStoreError });
   var reqOpts = { timeoutMs: timeoutMs, allowedProtocols: allowedProtocols };
+  if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
   // ---- Token cache ----
   var cachedToken = null;       // { accessToken, expiresAt }

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

@@ -44,6 +44,7 @@ function _request(method, url, body, headers, opts) {
     idleTimeoutMs:    opts && opts.timeoutMs,
     errorClass:       ObjectStoreError,
     allowedProtocols: opts && opts.allowedProtocols,
+  ...((opts && opts.allowInternal !== undefined) ? { allowInternal: opts.allowInternal } : {}),
   });
 }
 
@@ -67,6 +68,7 @@ function create(config) {
   // at first put(). HTTPS-only by default; cleartext appliances opt in
   // via config.allowedProtocols (safeUrl.ALLOW_HTTP_ALL).
   var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal    = config.allowInternal != null ? config.allowInternal : null;
   safeUrl.parse(baseUrl, {
     allowedProtocols: allowedProtocols,
     errorClass:       ObjectStoreError,
@@ -74,6 +76,7 @@ function create(config) {
   var headers = _authHeaders(config);
   var timeoutMs = config.timeoutMs;
   var reqOpts = { timeoutMs: timeoutMs, allowedProtocols: allowedProtocols };
+  if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
   function put(key, body, _opts) {
     var url = _keyToUrl(baseUrl, key);

package/lib/object-store/sigv4.js

@@ -204,6 +204,7 @@ function _request(method, url, headers, body, opts) {
     maxResponseBytes: opts && opts.maxResponseBytes,
     errorClass:       ObjectStoreError,
     allowedProtocols: opts && opts.allowedProtocols,
+  ...((opts && opts.allowInternal !== undefined) ? { allowInternal: opts.allowInternal } : {}),
   });
 }
 
@@ -223,11 +224,13 @@ function create(config) {
   // an internal cleartext S3-compatible endpoint (test fixtures, local
   // dev MinIO) opt in via config.allowedProtocols.
   var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal    = config.allowInternal != null ? config.allowInternal : null;
   safeUrl.parse(endpoint, {
     allowedProtocols: allowedProtocols,
     errorClass:       ObjectStoreError,
   });
   var reqOpts = { timeoutMs: config.timeoutMs, allowedProtocols: allowedProtocols };
+  if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
   function _keyToUrl(key) {
     if (key.indexOf("\0") !== -1) throw _err("INVALID_KEY", "null byte in key", true);

package/lib/ssrf-guard.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * ssrf-guard — outbound URL gate against private / loopback / link-local /
+ * cloud-metadata / reserved IP ranges.
+ *
+ * Wired as default-on in b.httpClient.request. Operators with internal
+ * mesh calls opt out per call:
+ *
+ *   b.httpClient.request({ url: "http://internal.svc", allowInternal: true });
+ *   b.httpClient.request({ url: "http://10.0.5.1",     allowInternal: ["10.0.0.0/8"] });
+ *
+ * Standalone use:
+ *
+ *   var ssrf = b.ssrfGuard;
+ *   await ssrf.checkUrl("https://example.com");          // throws SsrfError on hit
+ *   ssrf.classify("169.254.169.254");                    // → "cloud-metadata"
+ *   ssrf.cidrContains("10.0.0.0/8", "10.1.2.3");        // → true
+ *
+ * What's blocked by default:
+ *   - IPv4 private  (RFC 1918): 10/8, 172.16/12, 192.168/16
+ *   - IPv4 loopback:            127/8
+ *   - IPv4 link-local:          169.254/16
+ *   - IPv4 reserved/broadcast:  0/8, 100.64/10 (CGNAT), 224/4 (multicast),
+ *                               240/4, 255.255.255.255
+ *   - IPv4 documentation/test:  192.0.2/24, 198.51.100/24, 203.0.113/24, 198.18/15
+ *   - IPv6 loopback:            ::1
+ *   - IPv6 ULA (private):       fc00::/7
+ *   - IPv6 link-local:          fe80::/10
+ *   - Cloud metadata IPs:       169.254.169.254 (AWS/GCP/Azure),
+ *                               169.254.170.2 (AWS ECS task role),
+ *                               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).
+ */
+
+var dns = require("node:dns").promises;
+var net = require("node:net");
+
+var safeUrl = require("./safe-url");
+var validateOpts = require("./validate-opts");
+
+var { FrameworkError } = require("./framework-error");
+
+class SsrfError extends FrameworkError {
+  constructor(message, code, ctx) {
+    super(message, code);
+    this.name = "SsrfError";
+    this.permanent = true;
+    this.isSsrfError = true;
+    if (ctx) {
+      this.url = ctx.url || null;
+      this.ip = ctx.ip || null;
+      this.category = ctx.category || null;
+    }
+  }
+}
+
+// ---- IPv4 ranges (as numeric prefix tables for fast match) ----
+// Each entry: [networkInt, prefixLen]
+var IPV4_PRIVATE = [
+  [_ipv4ToInt("10.0.0.0"),     8],
+  [_ipv4ToInt("172.16.0.0"),  12],
+  [_ipv4ToInt("192.168.0.0"), 16],
+];
+var IPV4_LOOPBACK = [
+  [_ipv4ToInt("127.0.0.0"), 8],
+];
+var IPV4_LINK_LOCAL = [
+  [_ipv4ToInt("169.254.0.0"), 16],
+];
+var IPV4_RESERVED = [
+  [_ipv4ToInt("0.0.0.0"),         8],   // "this network"
+  [_ipv4ToInt("100.64.0.0"),     10],   // CGNAT (RFC 6598)
+  [_ipv4ToInt("192.0.0.0"),      24],   // IETF protocol assignments
+  [_ipv4ToInt("192.0.2.0"),      24],   // TEST-NET-1
+  [_ipv4ToInt("198.18.0.0"),     15],   // network benchmark
+  [_ipv4ToInt("198.51.100.0"),   24],   // TEST-NET-2
+  [_ipv4ToInt("203.0.113.0"),    24],   // TEST-NET-3
+  [_ipv4ToInt("224.0.0.0"),       4],   // multicast
+  [_ipv4ToInt("240.0.0.0"),       4],   // reserved + 255.255.255.255
+];
+
+// ---- IPv6 ranges (as 16-byte prefix tables) ----
+var IPV6_LOOPBACK_BYTES   = _ipv6ToBytes("::1");
+var IPV6_UNSPECIFIED_BYTES = _ipv6ToBytes("::");
+var IPV6_PRIVATE_PREFIX   = _ipv6ToBytes("fc00::");
+var IPV6_LINK_LOCAL_PREFIX = _ipv6ToBytes("fe80::");
+var IPV6_DOC_PREFIX       = _ipv6ToBytes("2001:db8::");      // documentation
+var IPV6_V4_MAPPED_PREFIX = _ipv6ToBytes("::ffff:0:0");      // IPv4-mapped (::ffff:0:0/96)
+
+// ---- Cloud metadata addresses (string-equality, exact match) ----
+var CLOUD_METADATA_IPS = [
+  "169.254.169.254",       // AWS, GCP, Azure, OpenStack, DO
+  "169.254.170.2",         // AWS ECS task role
+  "fd00:ec2::254",         // AWS IMDS over IPv6
+];
+
+// ---- Helpers ----
+
+function _ipv4ToInt(ip) {
+  var parts = ip.split(".");
+  return ((parts[0] | 0) << 24 >>> 0) +
+         ((parts[1] | 0) << 16) +
+         ((parts[2] | 0) << 8) +
+          (parts[3] | 0);
+}
+
+function _ipv6ToBytes(ip) {
+  // Node's net.isIPv6 returns 6 for valid IPv6; we then expand
+  // shorthand via manual parsing. node:net doesn't export an
+  // ipv6-to-bytes helper, but the URL constructor + Buffer dance
+  // is reliable for canonicalizing.
+  var groups = _expandIpv6(ip);
+  var out = Buffer.alloc(16);
+  for (var i = 0; i < 8; i++) {
+    var v = parseInt(groups[i], 16) || 0;
+    out[i * 2] = (v >> 8) & 0xff;
+    out[i * 2 + 1] = v & 0xff;
+  }
+  return out;
+}
+
+function _expandIpv6(ip) {
+  // Handle "::" zero-elision + IPv4-mapped suffix ("::ffff:1.2.3.4").
+  var lower = ip.toLowerCase();
+  // IPv4-mapped: convert trailing dotted-quad to two hex groups
+  var dot = lower.lastIndexOf(":");
+  if (dot !== -1 && lower.indexOf(".", dot) !== -1) {
+    var v4 = lower.slice(dot + 1);
+    var ipv4Int = _ipv4ToInt(v4);
+    var hi = (ipv4Int >>> 16) & 0xffff;
+    var lo = ipv4Int & 0xffff;
+    lower = lower.slice(0, dot + 1) + hi.toString(16) + ":" + lo.toString(16);
+  }
+  var doubleColon = lower.indexOf("::");
+  var leftStr, rightStr;
+  if (doubleColon === -1) {
+    leftStr  = lower;
+    rightStr = "";
+  } else {
+    leftStr  = lower.slice(0, doubleColon);
+    rightStr = lower.slice(doubleColon + 2);
+  }
+  var left  = leftStr.length  ? leftStr.split(":")  : [];
+  var right = rightStr.length ? rightStr.split(":") : [];
+  var missing = 8 - left.length - right.length;
+  var fill = [];
+  for (var i = 0; i < missing; i++) fill.push("0");
+  return left.concat(fill).concat(right);
+}
+
+function _cidrIpv4Match(cidr, ip) {
+  var slash = cidr.indexOf("/");
+  if (slash === -1) return false;
+  var network = _ipv4ToInt(cidr.slice(0, slash));
+  var prefix = parseInt(cidr.slice(slash + 1), 10);
+  if (!Number.isFinite(prefix) || prefix < 0 || prefix > 32) return false;
+  var ipInt = _ipv4ToInt(ip);
+  if (prefix === 0) return true;
+  var mask = (0xffffffff << (32 - prefix)) >>> 0;
+  return (ipInt & mask) === (network & mask);
+}
+
+function _cidrIpv6Match(cidr, ip) {
+  var slash = cidr.indexOf("/");
+  if (slash === -1) return false;
+  var network = _ipv6ToBytes(cidr.slice(0, slash));
+  var prefix = parseInt(cidr.slice(slash + 1), 10);
+  if (!Number.isFinite(prefix) || prefix < 0 || prefix > 128) return false;
+  var bytes = _ipv6ToBytes(ip);
+  var fullBytes = Math.floor(prefix / 8);
+  var remainingBits = prefix % 8;
+  for (var i = 0; i < fullBytes; i++) {
+    if (bytes[i] !== network[i]) return false;
+  }
+  if (remainingBits > 0) {
+    var mask = (0xff << (8 - remainingBits)) & 0xff;
+    if ((bytes[fullBytes] & mask) !== (network[fullBytes] & mask)) return false;
+  }
+  return true;
+}
+
+function _ipv4PrefixMatch(prefixTable, ipInt) {
+  for (var i = 0; i < prefixTable.length; i++) {
+    var net4 = prefixTable[i][0];
+    var prefix = prefixTable[i][1];
+    var mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    if ((ipInt & mask) === (net4 & mask)) return true;
+  }
+  return false;
+}
+
+function _ipv6PrefixMatch(prefixBytes, prefixLen, ipBytes) {
+  var fullBytes = Math.floor(prefixLen / 8);
+  var remainingBits = prefixLen % 8;
+  for (var i = 0; i < fullBytes; i++) {
+    if (ipBytes[i] !== prefixBytes[i]) return false;
+  }
+  if (remainingBits > 0) {
+    var mask = (0xff << (8 - remainingBits)) & 0xff;
+    if ((ipBytes[fullBytes] & mask) !== (prefixBytes[fullBytes] & mask)) return false;
+  }
+  return true;
+}
+
+// ---- Public classification API ----
+
+function classify(ip) {
+  if (typeof ip !== "string") return null;
+  var family = net.isIP(ip);
+  if (family === 0) return null;
+
+  if (CLOUD_METADATA_IPS.indexOf(ip) !== -1) return "cloud-metadata";
+
+  if (family === 4) {
+    var ipInt = _ipv4ToInt(ip);
+    if (_ipv4PrefixMatch(IPV4_LOOPBACK,    ipInt)) return "loopback";
+    if (_ipv4PrefixMatch(IPV4_LINK_LOCAL,  ipInt)) return "link-local";
+    if (_ipv4PrefixMatch(IPV4_PRIVATE,     ipInt)) return "private";
+    if (_ipv4PrefixMatch(IPV4_RESERVED,    ipInt)) return "reserved";
+    return null;
+  }
+
+  // IPv6
+  var bytes = _ipv6ToBytes(ip);
+  if (_bufEqual(bytes, IPV6_LOOPBACK_BYTES))      return "loopback";
+  if (_bufEqual(bytes, IPV6_UNSPECIFIED_BYTES))   return "reserved";
+  if (_ipv6PrefixMatch(IPV6_LINK_LOCAL_PREFIX, 10, bytes))  return "link-local";
+  if (_ipv6PrefixMatch(IPV6_PRIVATE_PREFIX,     7, bytes))  return "private";
+  if (_ipv6PrefixMatch(IPV6_DOC_PREFIX,        32, bytes))  return "reserved";
+  // IPv4-mapped addresses (::ffff:a.b.c.d/96): re-classify the v4 portion.
+  if (_ipv6PrefixMatch(IPV6_V4_MAPPED_PREFIX, 96, bytes)) {
+    var mappedV4 = bytes[12] + "." + bytes[13] + "." + bytes[14] + "." + bytes[15];
+    return classify(mappedV4);
+  }
+  return null;
+}
+
+function _bufEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (var i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+function cidrContains(cidr, ip) {
+  if (typeof cidr !== "string" || typeof ip !== "string") return false;
+  var slash = cidr.indexOf("/");
+  if (slash === -1) return false;
+  var network = cidr.slice(0, slash);
+  var nFamily = net.isIP(network);
+  var iFamily = net.isIP(ip);
+  if (nFamily === 0 || iFamily === 0 || nFamily !== iFamily) return false;
+  return nFamily === 4 ? _cidrIpv4Match(cidr, ip) : _cidrIpv6Match(cidr, ip);
+}
+
+// ---- URL check (DNS-resolving) ----
+
+async function checkUrl(url, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["allowInternal", "errorClass", "dnsLookup"], "ssrfGuard.checkUrl");
+
+  var ErrorClass = opts.errorClass || SsrfError;
+  var allowInternal = opts.allowInternal === true ? true :
+                      Array.isArray(opts.allowInternal) ? opts.allowInternal :
+                      false;
+
+  var parsed = url instanceof URL ? url : safeUrl.parse(String(url), {
+    allowedProtocols: safeUrl.ALLOW_HTTP_ALL,
+    errorClass: ErrorClass,
+  });
+  if (!parsed.hostname) {
+    throw new ErrorClass("URL '" + parsed.toString() + "' has no hostname",
+      "ssrf-guard/no-hostname", { url: parsed.toString() });
+  }
+
+  // Strip IPv6 brackets — net.isIP doesn't accept "[::1]" form, only "::1"
+  var hostForCheck = parsed.hostname.replace(/^\[|\]$/g, "");
+
+  var ips;
+  if (net.isIP(hostForCheck)) {
+    ips = [{ address: hostForCheck, family: net.isIP(hostForCheck) }];
+  } else {
+    var lookup = opts.dnsLookup || function (host) {
+      return dns.lookup(host, { all: true });
+    };
+    ips = await lookup(hostForCheck);
+    if (!Array.isArray(ips)) ips = [ips];
+  }
+
+  for (var i = 0; i < ips.length; i++) {
+    var addr = ips[i].address;
+    var category = classify(addr);
+    if (!category) continue;
+
+    if (allowInternal === true) continue;
+    if (Array.isArray(allowInternal) && allowInternal.some(function (cidr) {
+      return cidrContains(cidr, addr);
+    })) continue;
+
+    throw new ErrorClass(
+      "URL '" + parsed.toString() + "' resolves to " + addr +
+      " in the " + category + " range — pass allowInternal:true to override",
+      "ssrf-guard/blocked-" + category,
+      { url: parsed.toString(), ip: addr, category: category }
+    );
+  }
+  return { url: parsed, ips: ips };
+}
+
+module.exports = {
+  classify:        classify,
+  cidrContains:    cidrContains,
+  checkUrl:        checkUrl,
+  isPrivate:       function (ip) { return classify(ip) === "private"; },
+  isLoopback:      function (ip) { return classify(ip) === "loopback"; },
+  isLinkLocal:     function (ip) { return classify(ip) === "link-local"; },
+  isCloudMetadata: function (ip) { return classify(ip) === "cloud-metadata"; },
+  isReserved:      function (ip) { return classify(ip) === "reserved"; },
+  SsrfError:       SsrfError,
+};

package/package.json

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