@blamejs/core 0.8.43 → 0.8.50

package/lib/ssrf-guard.js

@@ -1,43 +1,38 @@
 "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 validated IPs are returned in the result and `b.httpClient` pins
- * the actual TCP connect to those exact addresses (via a custom
- * `lookup` callback passed to https / http2 connect). A hostile DNS
- * server cannot rebind between guard-check and connect to redirect
- * traffic at a private / metadata address.
+ * @module b.ssrfGuard
+ * @nav    HTTP
+ * @title  SSRF Guard
+ *
+ * @intro
+ *   Outbound-URL Server-Side-Request-Forgery defense. Every URL the
+ *   framework dials on behalf of an operator (b.httpClient, webhook
+ *   delivery, OAuth discovery, OIDC JWKS fetch, image-by-URL upload)
+ *   routes through the gate. The gate refuses private (RFC 1918 +
+ *   RFC 4193 ULA), loopback (127/8 + ::1), link-local
+ *   (169.254/16 + fe80::/10), reserved / documentation / CGNAT,
+ *   IPv4-mapped / 6to4 / NAT64 / discard-prefix wrappers, and the
+ *   cloud-metadata IPs (169.254.169.254 AWS/GCP/Azure/OpenStack/DO,
+ *   169.254.170.2 AWS ECS task role, fd00:ec2::254 IPv6 IMDS).
+ *
+ *   DNS rebinding is closed by resolving the hostname once during
+ *   classification AND returning the validated IP set in the result.
+ *   b.httpClient pins the actual TCP connect to those exact addresses
+ *   via a custom `lookup` callback — a hostile DNS server cannot flip
+ *   the answer between guard-check and connect. Redirect chains are
+ *   re-validated end-to-end by b.httpClient (each Location header
+ *   passes through `checkUrl` before the next hop is dialed), and
+ *   `createAllowlist` builds operator-specific egress allowlists that
+ *   compose on top of the framework's hard-coded ban list.
+ *
+ *   Cloud-metadata IPs are blocked unconditionally — `allowInternal`
+ *   does NOT override this class because metadata endpoints leak
+ *   instance credentials. Operators with a legitimate need for the
+ *   metadata service do it through their cloud SDK with explicit IAM,
+ *   never through the framework's outbound HTTP.
+ *
+ * @card
+ *   Outbound-URL Server-Side-Request-Forgery defense.
  */
 
 var dns = require("node:dns").promises;
@@ -64,6 +59,30 @@ var IPV6_BYTES    = C.BYTES.bytes(16);     // 128 bits / 8 bits-per-byte
 var IPV6_GROUPS   = C.BYTES.bytes(8);      // hex groups
 var HEX_RADIX     = C.BYTES.bytes(16);     // parseInt / toString radix
 
+/**
+ * @primitive b.ssrfGuard.SsrfError
+ * @signature b.ssrfGuard.SsrfError
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.checkUrl, b.ssrfGuard.createAllowlist
+ *
+ * Error class thrown by every `b.ssrfGuard` primitive on a refused
+ * URL or refused address. Extends `FrameworkError`. Carries a stable
+ * `.code` (e.g. `ssrf-guard/blocked-cloud-metadata`,
+ * `ssrf-guard/blocked-private`, `ssrf-guard/not-on-allowlist`) plus
+ * the offending `.url` / `.ip` / `.category` for the audit log. Is
+ * marked `.permanent = true` so retry layers do not loop on it.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   try {
+ *     await b.ssrfGuard.checkUrl("http://169.254.169.254/latest/meta-data/");
+ *   } catch (e) {
+ *     e instanceof b.ssrfGuard.SsrfError;   // → true
+ *     e.code;                               // → "ssrf-guard/blocked-cloud-metadata"
+ *     e.category;                           // → "cloud-metadata"
+ *   }
+ */
 class SsrfError extends FrameworkError {
   constructor(message, code, ctx) {
     super(message, code);
@@ -261,6 +280,30 @@ function _ipv6PrefixMatch(prefixBytes, prefixLen, ipBytes) {
 
 // ---- Public classification API ----
 
+/**
+ * @primitive b.ssrfGuard.classify
+ * @signature b.ssrfGuard.classify(ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.checkUrl, b.ssrfGuard.cidrContains
+ *
+ * Synchronous IP-string classifier. Returns one of `"loopback"`,
+ * `"link-local"`, `"private"`, `"reserved"`, `"cloud-metadata"`, or
+ * `null` when the address is a routable public IP (or not a valid IP
+ * at all — non-string / malformed input returns `null` rather than
+ * throwing). Recognizes IPv4-mapped (`::ffff:a.b.c.d`), 6to4
+ * (`2002::/16`), and NAT64 (`64:ff9b::/96`) v6 wrappers and reclassifies
+ * the embedded v4 address — a 6to4-wrapped private IP returns
+ * `"private"`, never `null`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.classify("169.254.169.254");   // → "cloud-metadata"
+ *   b.ssrfGuard.classify("10.0.0.1");          // → "private"
+ *   b.ssrfGuard.classify("127.0.0.1");         // → "loopback"
+ *   b.ssrfGuard.classify("8.8.8.8");           // → null
+ *   b.ssrfGuard.classify("::ffff:10.0.0.1");   // → "private"
+ */
 function classify(ip) {
   if (typeof ip !== "string") return null;
   var family = net.isIP(ip);
@@ -313,6 +356,27 @@ function _bufEqual(a, b) {
   return Buffer.compare(a, b) === 0;
 }
 
+/**
+ * @primitive b.ssrfGuard.cidrContains
+ * @signature b.ssrfGuard.cidrContains(cidr, ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify, b.ssrfGuard.createAllowlist
+ *
+ * Returns `true` if `ip` falls inside the CIDR block `cidr`, else
+ * `false`. Both arguments must be the same address family (v4-in-v4
+ * or v6-in-v6 — mixed families return `false`). Used internally by
+ * `checkUrl` to evaluate the operator's `allowInternal` exception
+ * list and exposed publicly so operator code can drive the same
+ * range arithmetic for routing / allowlist UI.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.cidrContains("10.0.0.0/8",   "10.1.2.3");      // → true
+ *   b.ssrfGuard.cidrContains("10.0.0.0/8",   "11.0.0.1");      // → false
+ *   b.ssrfGuard.cidrContains("fd00::/8",     "fd12:3456::1");  // → true
+ *   b.ssrfGuard.cidrContains("10.0.0.0/8",   "::1");           // → false (mixed family)
+ */
 function cidrContains(cidr, ip) {
   if (typeof cidr !== "string" || typeof ip !== "string") return false;
   var slash = cidr.indexOf("/");
@@ -326,6 +390,63 @@ function cidrContains(cidr, ip) {
 
 // ---- URL check (DNS-resolving) ----
 
+/**
+ * @primitive b.ssrfGuard.checkUrl
+ * @signature b.ssrfGuard.checkUrl(url, opts?)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify, b.ssrfGuard.createAllowlist, b.httpClient.request
+ *
+ * Async DNS-resolving URL gate — the canonical pre-flight before
+ * any outbound fetch / webhook delivery / OAuth discovery. Resolves
+ * the hostname (via `b.network.dns` when available so DoH overrides
+ * apply, else native `dns.lookup`), classifies every returned address,
+ * and throws `SsrfError` on the first refused class. Cloud-metadata
+ * IPs throw unconditionally; other classes can be overridden by
+ * `allowInternal: true` (allow every private class) or
+ * `allowInternal: ["10.0.0.0/8", ...]` (allow specific CIDRs only).
+ *
+ * Returns `{ url, ips }` on success — `ips` is the resolved address
+ * list, suitable for passing to `https.request({ lookup })` so the
+ * subsequent TCP connect pins to the validated set and a hostile DNS
+ * server cannot rebind between guard-check and connect.
+ *
+ * @opts
+ *   allowInternal: boolean | string[],   // override private-range refusal
+ *                                        //   (cloud-metadata is NEVER overridable)
+ *   errorClass:    Function,             // subclass of SsrfError to throw
+ *   dnsLookup:     Function,             // override DNS resolver (testing / fixtures)
+ *
+ * @example
+ *   // assertSafe before fetch — refuse private / metadata / loopback
+ *   var b = require("blamejs");
+ *   var result = await b.ssrfGuard.checkUrl("https://api.partner.example.com/v1/x");
+ *   result.ips[0].address;   // → "203.0.113.42"
+ *
+ *   // Pin TCP connect to the validated IP set (defeats DNS rebinding):
+ *   var validatedIps = result.ips;
+ *   var lookup = function (host, opts, cb) { cb(null, validatedIps[0].address, validatedIps[0].family); };
+ *
+ * @example
+ *   // Allow an internal mesh CIDR for one specific call:
+ *   var b = require("blamejs");
+ *   await b.ssrfGuard.checkUrl("http://10.0.5.42:8080/health", {
+ *     allowInternal: ["10.0.0.0/8"],
+ *   });
+ *   // → { url: parsedUrl, ips: [{ address: "10.0.5.42", family: 4 }] }
+ *
+ * @example
+ *   // Cloud-metadata IPs are blocked unconditionally (allowInternal does NOT override):
+ *   var b = require("blamejs");
+ *   try {
+ *     await b.ssrfGuard.checkUrl("http://169.254.169.254/latest/meta-data/iam/", {
+ *       allowInternal: true,
+ *     });
+ *   } catch (e) {
+ *     e.code;       // → "ssrf-guard/blocked-cloud-metadata"
+ *     e.category;   // → "cloud-metadata"
+ *   }
+ */
 async function checkUrl(url, opts) {
   opts = opts || {};
   validateOpts(opts, ["allowInternal", "errorClass", "dnsLookup"], "ssrfGuard.checkUrl");
@@ -403,19 +524,54 @@ async function checkUrl(url, opts) {
   return { url: parsed, ips: ips };
 }
 
-// b.network.allowlist — contextual per-call egress allowlist composing
-// on ssrfGuard. Operators describe an allowed CIDR set + denylist;
-// the resulting `assert(url)` either resolves to the validated IP set
-// or throws SsrfError. Distinct from `ssrfGuard.checkUrl` (which uses
-// the framework's hard-coded private/cloud-metadata ban list) — this
-// is for cases where the operator's deployment has SPECIFIC outbound
-// targets and everything else should be refused.
-//
-//   var egress = b.network.allowlist.create({
-//     allow: ["api.partner.example.com", "192.0.2.0/24"],
-//     deny:  ["api.partner.example.com/admin"],
-//   });
-//   await egress.assert("https://api.partner.example.com/v1/x");
+/**
+ * @primitive b.ssrfGuard.createAllowlist
+ * @signature b.ssrfGuard.createAllowlist(opts)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.checkUrl, b.ssrfGuard.cidrContains
+ *
+ * Build a contextual per-call egress allowlist composing on top of
+ * `ssrfGuard`. Operators describe an allowed host / CIDR set plus an
+ * optional denylist; the returned `{ assert(url) }` either resolves
+ * to the validated IP set (delegating to `checkUrl` with
+ * `allowInternal: true` because the explicit allowlist supersedes
+ * the private-range refusal) or throws `SsrfError`. Distinct from
+ * `checkUrl`'s hard-coded ban list — use `createAllowlist` when the
+ * deployment has SPECIFIC outbound targets and everything else
+ * should be refused.
+ *
+ * Throws at construction time if `allow` is empty (an empty
+ * allowlist would refuse every URL — almost certainly a config typo).
+ *
+ * @opts
+ *   allow: string[],   // required; entries are exact hostnames OR CIDR blocks
+ *   deny:  string[],   // optional; checked AFTER allow — denylist wins
+ *
+ * @example
+ *   // Allow-list a single partner domain — refuse everything else:
+ *   var b = require("blamejs");
+ *   var egress = b.ssrfGuard.createAllowlist({
+ *     allow: ["api.partner.example.com", "203.0.113.0/24"],
+ *     deny:  ["evil.partner.example.com"],
+ *   });
+ *   await egress.assert("https://api.partner.example.com/v1/x");
+ *   // → { url: parsedUrl, ips: [{ address: "203.0.113.10", family: 4 }] }
+ *
+ * @example
+ *   // Custom blocklist for cloud-metadata IPs at the allowlist layer
+ *   // (defense-in-depth; checkUrl already refuses these unconditionally):
+ *   var b = require("blamejs");
+ *   var egress = b.ssrfGuard.createAllowlist({
+ *     allow: ["10.0.0.0/8"],
+ *     deny:  ["169.254.169.254", "169.254.170.2"],
+ *   });
+ *   try {
+ *     await egress.assert("http://169.254.169.254/latest/");
+ *   } catch (e) {
+ *     e.code;   // → "ssrf-guard/blocked-cloud-metadata"
+ *   }
+ */
 function createAllowlist(opts) {
   opts = opts || {};
   var allowList = Array.isArray(opts.allow) ? opts.allow.slice() : [];
@@ -457,15 +613,119 @@ function createAllowlist(opts) {
   return { assert: assertUrl };
 }
 
+/**
+ * @primitive b.ssrfGuard.isPrivate
+ * @signature b.ssrfGuard.isPrivate(ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify
+ *
+ * Returns `true` if `ip` is in an RFC 1918 IPv4 private range
+ * (10/8, 172.16/12, 192.168/16) or RFC 4193 IPv6 ULA (fc00::/7).
+ * Convenience wrapper over `classify(ip) === "private"`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.isPrivate("10.0.0.1");        // → true
+ *   b.ssrfGuard.isPrivate("8.8.8.8");         // → false
+ *   b.ssrfGuard.isPrivate("fd12:3456::1");    // → true
+ */
+function isPrivate(ip)       { return classify(ip) === "private"; }
+
+/**
+ * @primitive b.ssrfGuard.isLoopback
+ * @signature b.ssrfGuard.isLoopback(ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify
+ *
+ * Returns `true` if `ip` is in 127/8 (IPv4 loopback) or `::1`
+ * (IPv6 loopback). Convenience wrapper over
+ * `classify(ip) === "loopback"`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.isLoopback("127.0.0.1");   // → true
+ *   b.ssrfGuard.isLoopback("::1");         // → true
+ *   b.ssrfGuard.isLoopback("8.8.8.8");     // → false
+ */
+function isLoopback(ip)      { return classify(ip) === "loopback"; }
+
+/**
+ * @primitive b.ssrfGuard.isLinkLocal
+ * @signature b.ssrfGuard.isLinkLocal(ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify, b.ssrfGuard.isCloudMetadata
+ *
+ * Returns `true` if `ip` is in 169.254/16 (IPv4 link-local) or
+ * fe80::/10 (IPv6 link-local). Note that the cloud-metadata IPs
+ * (169.254.169.254 / 169.254.170.2) classify as `"cloud-metadata"`,
+ * NOT `"link-local"` — use `isCloudMetadata` if that distinction
+ * matters.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.isLinkLocal("169.254.0.1");        // → true
+ *   b.ssrfGuard.isLinkLocal("169.254.169.254");    // → false (it's cloud-metadata)
+ *   b.ssrfGuard.isLinkLocal("fe80::1");            // → true
+ */
+function isLinkLocal(ip)     { return classify(ip) === "link-local"; }
+
+/**
+ * @primitive b.ssrfGuard.isCloudMetadata
+ * @signature b.ssrfGuard.isCloudMetadata(ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify, b.ssrfGuard.checkUrl
+ *
+ * Returns `true` if `ip` is one of the cloud-metadata service
+ * addresses (169.254.169.254 AWS/GCP/Azure/OpenStack/DO,
+ * 169.254.170.2 AWS ECS task role, fd00:ec2::254 IPv6 IMDS).
+ * These IPs leak instance credentials and `checkUrl` refuses them
+ * unconditionally — `allowInternal` does NOT override.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.isCloudMetadata("169.254.169.254");   // → true
+ *   b.ssrfGuard.isCloudMetadata("169.254.170.2");     // → true
+ *   b.ssrfGuard.isCloudMetadata("fd00:ec2::254");     // → true
+ *   b.ssrfGuard.isCloudMetadata("169.254.0.1");       // → false (link-local but not metadata)
+ */
+function isCloudMetadata(ip) { return classify(ip) === "cloud-metadata"; }
+
+/**
+ * @primitive b.ssrfGuard.isReserved
+ * @signature b.ssrfGuard.isReserved(ip)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.ssrfGuard.classify
+ *
+ * Returns `true` if `ip` is in an IETF-reserved range — 0/8 ("this
+ * network"), 100.64/10 (CGNAT, RFC 6598), 192.0.0/24 (IETF protocol
+ * assignments), TEST-NET-1/2/3 (192.0.2/24, 198.51.100/24, 203.0.113/24),
+ * 198.18/15 (network benchmark), 224/4 (multicast), 240/4 (reserved +
+ * 255.255.255.255), 2001:db8::/32 (IPv6 documentation), ff00::/8 (IPv6
+ * multicast), or 100::/64 (IPv6 discard prefix).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.ssrfGuard.isReserved("192.0.2.1");      // → true (TEST-NET-1)
+ *   b.ssrfGuard.isReserved("100.64.0.1");     // → true (CGNAT)
+ *   b.ssrfGuard.isReserved("224.0.0.1");      // → true (multicast)
+ *   b.ssrfGuard.isReserved("8.8.8.8");        // → false
+ */
+function isReserved(ip)      { return classify(ip) === "reserved"; }
+
 module.exports = {
   classify:        classify,
   cidrContains:    cidrContains,
   checkUrl:        checkUrl,
   createAllowlist: createAllowlist,
-  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"; },
+  isPrivate:       isPrivate,
+  isLoopback:      isLoopback,
+  isLinkLocal:     isLinkLocal,
+  isCloudMetadata: isCloudMetadata,
+  isReserved:      isReserved,
   SsrfError:       SsrfError,
 };