@cruxy/cli 0.26.0 → 0.27.0

package/dist/web/ssrf.js

@@ -1,5 +1,5 @@
-import { lookup } from "node:dns";
 import { Agent } from "undici";
+import { assertAllPublic, BlockedHostError, pinnedLookup, } from "../net/ip-guard.js";
 /**
  * SSRF guard (C.20). A URL the MODEL chose must not be able to reach the user's
  * internal network, cloud metadata service, or loopback interface. Three layers:
@@ -17,170 +17,14 @@ import { Agent } from "undici";
  *
  * The check runs BEFORE any request is dispatched, and again on every redirect hop
  * (see fetch.ts). A block is a security refusal, distinct from a network failure.
+ *
+ * The IP range math, the pin shim, and the error types now live in the shared
+ * {@link ../net/ip-guard ip-guard} module (JC-A) — the ONE owner of "is this IP
+ * allowed"; this file keeps only the web-specific policy (scheme + the
+ * `allowPrivateHosts` escape hatch) and the web one-shot dispatcher.
  */
-/** Default resolver: node's `dns.lookup` returning ALL addresses. */
-export const defaultResolveHost = (host) => new Promise((resolve, reject) => {
-    lookup(host, { all: true }, (err, addresses) => {
-        if (err)
-            reject(err);
-        else
-            resolve(addresses.map((a) => a.address));
-    });
-});
-/** Thrown when a URL is refused pre-dispatch; carries a human reason. */
-export class BlockedHostError extends Error {
-}
-/** Thrown when the host could not be resolved (a network failure, not a block). */
-export class HostUnresolvedError extends Error {
-}
-/** Parse a dotted-quad IPv4 string into its four octets, or null. */
-function parseIpv4(ip) {
-    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
-    if (!m)
-        return null;
-    const octets = m.slice(1, 5).map((s) => Number(s));
-    if (octets.some((o) => o > 255))
-        return null;
-    return octets;
-}
-/** True if an IPv4 address falls in a private/loopback/link-local/reserved range. */
-function isBlockedIpv4(ip) {
-    const octets = parseIpv4(ip);
-    if (!octets)
-        return false;
-    const [a, b] = octets;
-    if (a === 0)
-        return true; // 0.0.0.0/8 "this network" / unspecified
-    if (a === 10)
-        return true; // 10.0.0.0/8 private
-    if (a === 127)
-        return true; // 127.0.0.0/8 loopback
-    if (a === 169 && b === 254)
-        return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
-    if (a === 172 && b >= 16 && b <= 31)
-        return true; // 172.16.0.0/12 private
-    if (a === 192 && b === 168)
-        return true; // 192.168.0.0/16 private
-    if (a === 100 && b >= 64 && b <= 127)
-        return true; // 100.64.0.0/10 CGNAT
-    if (a === 198 && (b === 18 || b === 19))
-        return true; // 198.18.0.0/15 benchmarking
-    if (a === 255 && b === 255)
-        return true; // broadcast-ish
-    return false;
-}
-/**
- * Expand an IPv6 literal into its 8 sixteen-bit groups, or null if unparseable.
- * Handles `::` compression and an embedded IPv4 tail (`::ffff:127.0.0.1`).
- */
-function parseIpv6(input) {
-    let s = input;
-    const tail = [];
-    // Peel off a trailing dotted-quad (IPv4-mapped/-compatible forms).
-    const v4 = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(s);
-    if (v4) {
-        const o = parseIpv4(v4[1]);
-        if (!o)
-            return null;
-        tail.push((o[0] << 8) | o[1], (o[2] << 8) | o[3]);
-        s = s.slice(0, v4.index); // leaves a trailing ':' before the compression split
-    }
-    const halves = s.split("::");
-    if (halves.length > 2)
-        return null; // more than one "::" is illegal
-    const head = halves[0] ? halves[0].split(":").filter(Boolean) : [];
-    const rest = halves[1] ? halves[1].split(":").filter(Boolean) : [];
-    const toNums = (groups) => {
-        const out = [];
-        for (const g of groups) {
-            if (!/^[0-9a-f]{1,4}$/.test(g))
-                return null;
-            out.push(parseInt(g, 16));
-        }
-        return out;
-    };
-    const headNums = toNums(head);
-    const restNums = toNums(rest);
-    if (!headNums || !restNums)
-        return null;
-    let groups;
-    if (halves.length === 2) {
-        const fill = 8 - (headNums.length + restNums.length + tail.length);
-        if (fill < 0)
-            return null;
-        groups = [
-            ...headNums,
-            ...Array(fill).fill(0),
-            ...restNums,
-            ...tail,
-        ];
-    }
-    else {
-        groups = [...headNums, ...tail];
-    }
-    return groups.length === 8 ? groups : null;
-}
-/** True if an expanded IPv6 address is in a range `web_fetch` must never reach. */
-function isBlockedIpv6(g) {
-    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d): check the v4 part.
-    const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
-    const firstSixZero = firstFiveZero && g[5] === 0;
-    const embedded = `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
-    if (firstFiveZero && g[5] === 0xffff)
-        return isBlockedIpv4(embedded); // ::ffff:x
-    if (firstSixZero &&
-        !(g[6] === 0 && g[7] === 0) &&
-        !(g[6] === 0 && g[7] === 1))
-        return isBlockedIpv4(embedded); // ::x.y.z.w (IPv4-compatible, deprecated)
-    if (g.every((x) => x === 0))
-        return true; // :: unspecified
-    if (firstSixZero && g[6] === 0 && g[7] === 1)
-        return true; // ::1 loopback
-    if ((g[0] & 0xffc0) === 0xfe80)
-        return true; // fe80::/10 link-local (fe80–febf)
-    if ((g[0] & 0xfe00) === 0xfc00)
-        return true; // fc00::/7 unique-local (fc00–fdff)
-    if ((g[0] & 0xff00) === 0xff00)
-        return true; // ff00::/8 multicast
-    return false;
-}
-/** True if an address (v4 or v6) is in a range `web_fetch` must never reach. */
-export function isBlockedAddress(addr) {
-    // Strip IPv6 brackets and a scope/zone id (e.g. fe80::1%eth0).
-    const ip = addr
-        .trim()
-        .toLowerCase()
-        .replace(/^\[|\]$/g, "")
-        .split("%")[0];
-    if (ip.includes(":")) {
-        const groups = parseIpv6(ip);
-        if (!groups)
-            return true; // fail closed: an unparseable colon-address is refused
-        return isBlockedIpv6(groups);
-    }
-    return isBlockedIpv4(ip);
-}
-/**
- * A `dns.lookup`-compatible function that ignores the hostname and always hands
- * back one of the pre-validated `addresses`. This is what pins a connection to the
- * address the SSRF check already approved, defeating DNS rebinding: the socket can
- * only reach a validated IP, never a value re-resolved at connect time.
- */
-export function pinnedLookup(addresses) {
-    const resolved = addresses.map((address) => ({
-        address,
-        family: address.includes(":") ? 6 : 4,
-    }));
-    return (_hostname, options, callback) => {
-        const all = typeof options === "object" && options !== null && "all" in options
-            ? options.all
-            : false;
-        if (all)
-            callback(null, resolved);
-        else
-            callback(null, resolved[0].address, resolved[0].family);
-    };
-}
+// Re-export the shared surface so existing web importers/tests are unchanged.
+export { BlockedHostError, HostUnresolvedError, isBlockedAddress, defaultResolveHost, pinnedLookup, } from "../net/ip-guard.js";
 /** An undici dispatcher whose connections are pinned to `addresses`. */
 export function createPinnedDispatcher(addresses) {
     return new Agent({ connect: { lookup: pinnedLookup(addresses) } });
@@ -188,8 +32,8 @@ export function createPinnedDispatcher(addresses) {
 /**
  * Assert that `url` may be fetched and return the validated addresses to pin the
  * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
- * resolving into a blocked range, or {@link HostUnresolvedError} if the host cannot
- * be resolved.
+ * resolving into a blocked range, or `HostUnresolvedError` if the host cannot be
+ * resolved.
  *
  * The returned list is the exact set of addresses the caller must restrict the
  * connection to (via {@link createPinnedDispatcher}). An empty list means "do not
@@ -203,21 +47,5 @@ export async function assertFetchable(url, resolveHost, allowPrivate) {
     }
     if (allowPrivate)
         return [];
-    const host = url.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
-    let addresses;
-    try {
-        addresses = await resolveHost(host);
-    }
-    catch (err) {
-        throw new HostUnresolvedError(`could not resolve host "${host}": ${err.message}`);
-    }
-    if (addresses.length === 0) {
-        throw new HostUnresolvedError(`host "${host}" resolved to no addresses`);
-    }
-    for (const addr of addresses) {
-        if (isBlockedAddress(addr)) {
-            throw new BlockedHostError(`host "${host}" resolves to ${addr}, a private/loopback/link-local address`);
-        }
-    }
-    return addresses;
+    return assertAllPublic(url.hostname, resolveHost);
 }

package/dist/web/types.d.ts

@@ -1,3 +1,4 @@
+import type { HostResolver } from "../net/ip-guard.js";
 import type { WebConfig } from "../config/index.js";
 /**
  * Web subtool seams + shapes (C.20). Everything the `web_search`/`web_fetch`
@@ -44,9 +45,10 @@ export interface SearchProvider {
 /**
  * Resolve a hostname to its IP addresses. Injected so the SSRF guard can be tested
  * deterministically (a hostname that "resolves" to an internal IP) without real
- * DNS. Defaults to node's `dns.lookup` with `all: true`.
+ * DNS. Owned by the shared {@link ../net/ip-guard ip-guard} module (JC-A) and
+ * re-exported here for web importers.
  */
-export type HostResolver = (host: string) => Promise<string[]>;
+export type { HostResolver } from "../net/ip-guard.js";
 /**
  * Injectable dependencies for the web tools. Defaults wire the real `fetch` and
  * DNS; tests pass spies/fakes. No global is ever patched.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {