@crewhaus/tool-navigate 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -11,6 +11,30 @@ export type DnsLookupFn = (hostname: string) => Promise<{
 }>;
 /** Test hook: override DNS resolution. Pass `undefined` to restore the default. */
 export declare function _setDnsLookup(fn: DnsLookupFn | undefined): void;
+/**
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
+ */
+export declare function normalizeIpv4(raw: string): string | null;
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export declare function parseIpv6(raw: string): ReadonlyArray<number> | null;
+/** Ranges that are never a public RPC endpoint. */
+export declare function isPrivateIp(address: string): boolean;
 /**
  * Reject anything that isn't a public http/https target before the browser
  * sees it. This guard blocks the direct vectors — non-http(s) schemes, IP

package/dist/index.js

@@ -47,121 +47,206 @@ let dnsLookupFn = nodeDnsLookup;
 export function _setDnsLookup(fn) {
     dnsLookupFn = fn ?? nodeDnsLookup;
 }
+// ---------------------------------------------------------------------------
+// BEGIN SYNCHRONISED BLOCK — private-address classifier
+//
+// This block is BYTE-IDENTICAL across every package that guards an outbound
+// request. Do not edit one copy: `apps/cli/src/tool-registry.test.ts` hashes
+// them all and fails if any differs, and it asserts how many it found, because
+// a copy-scanning guard that matches nothing reports green.
+//
+// It exists in copies rather than a shared package because these files are
+// otherwise independent per-package networking layers; a guard proving the
+// copies are identical is cheaper and safer than the import graph a shared
+// package would need across `crawler`, `computer-use-driver` and ten tools.
+//
+// WHY IT PARSES INSTEAD OF MATCHING TEXT. Six copies were confirmed
+// exploitable on 2026-09-18 because they compared address STRINGS. The WHATWG
+// URL parser rewrites `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, so a
+// text check never sees the spelling it was written for; and `64:ff9b::a9fe:a9fe`
+// IS 169.254.169.254 on any network running DNS64/NAT64. Parsing numerically and
+// recursing into the embedded IPv4 is the only form that holds.
+//
+// WHAT IT CANNOT DO. RFC 6052 lets an operator choose any Network-Specific
+// Prefix for NAT64, so an embedded IPv4 behind an arbitrary NSP is undecidable
+// from the address alone. That case is configuration, and the callers that need
+// it resolve the host and re-check the ANSWER before dialling.
+// ---------------------------------------------------------------------------
 /**
- * SSRF defenses below mirror `@crewhaus/tool-fetch` (`isPrivateIp` /
- * `normalizeIpv4`). They are duplicated rather than imported to avoid
- * coupling the browser bundle to tool-fetch's module-level config state —
- * keep the copies in sync. The IPv4-mapped IPv6 handling (`::ffff:…`, both
- * dotted and hex-compressed) is load-bearing: `new URL` normalizes
- * `http://[::ffff:127.0.0.1]/` to `[::ffff:7f00:1]`, which would otherwise
- * slip past a naive loopback check.
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
  */
-function normalizeIpv4(raw) {
+export function normalizeIpv4(raw) {
     const trimmed = raw.trim();
-    if (trimmed === "")
+    if (trimmed === "" || /[^0-9a-fA-FxX.]/.test(trimmed))
+        return null;
+    const parts = trimmed.split(".");
+    if (parts.length === 0 || parts.length > 4)
         return null;
-    const parseComponent = (s) => {
-        if (s === "")
+    const values = [];
+    for (const part of parts) {
+        if (part === "")
             return null;
         let value;
-        if (/^0[xX][0-9a-fA-F]+$/.test(s)) {
-            value = Number.parseInt(s.slice(2), 16);
-        }
-        else if (/^0[0-7]+$/.test(s)) {
-            value = Number.parseInt(s, 8);
-        }
-        else if (/^[0-9]+$/.test(s)) {
-            value = Number.parseInt(s, 10);
-        }
-        else {
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            value = Number.parseInt(part.slice(2), 16);
+        else if (/^0[0-7]+$/.test(part))
+            value = Number.parseInt(part.slice(1), 8);
+        else if (/^\d+$/.test(part))
+            value = Number.parseInt(part, 10);
+        else
             return null;
-        }
-        return Number.isNaN(value) ? null : value;
-    };
-    const segments = trimmed.split(".");
-    if (segments.length > 4)
-        return null;
-    const components = [];
-    for (const seg of segments) {
-        const value = parseComponent(seg);
-        if (value === null || value < 0)
+        if (!Number.isFinite(value) || value < 0)
             return null;
-        components.push(value);
+        values.push(value);
     }
-    const n = components.length;
-    const octets = [0, 0, 0, 0];
-    for (let i = 0; i < n - 1; i++) {
-        const c = components[i];
-        if (c > 255)
+    // The short forms pack the remaining octets into the last part: `127.1` is
+    // 127.0.0.1, not 127.1.0.0. Getting this backwards is how a bypass survives.
+    const last = values[values.length - 1];
+    const leading = values.slice(0, -1);
+    if (leading.some((v) => v > 255))
+        return null;
+    const remaining = 4 - leading.length;
+    if (last >= 2 ** (8 * remaining))
+        return null;
+    const octets = [...leading];
+    for (let i = remaining - 1; i >= 0; i--)
+        octets.push((last >>> (8 * i)) & 0xff);
+    return octets.join(".");
+}
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export function parseIpv6(raw) {
+    let text = raw.trim().toLowerCase();
+    if (text.startsWith("["))
+        text = text.slice(1);
+    if (text.endsWith("]"))
+        text = text.slice(0, -1);
+    const zone = text.indexOf("%"); // fe80::1%eth0
+    if (zone !== -1)
+        text = text.slice(0, zone);
+    if (!text.includes(":"))
+        return null;
+    // A trailing dotted quad is the last two groups written in IPv4. Require all
+    // three dots: without that, `::1` parses as a one-part inet_aton address and
+    // takes a path that has nothing to do with what was written.
+    const dotted = /^(.*:)(\d+(?:\.\d+){3})$/.exec(text);
+    if (dotted !== null) {
+        const quad = normalizeIpv4(dotted[2]);
+        if (quad === null)
             return null;
-        octets[i] = c;
+        const o = quad.split(".").map((n) => Number.parseInt(n, 10));
+        const hi = (o[0] << 8) | o[1];
+        const lo = (o[2] << 8) | o[3];
+        text = `${dotted[1]}${hi.toString(16)}:${lo.toString(16)}`;
     }
-    const last = components[n - 1];
-    const maxLast = 2 ** (8 * (4 - (n - 1)));
-    if (last >= maxLast)
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const pieces = (part) => (part === "" ? [] : part.split(":"));
+    const head = pieces(halves[0]);
+    const tail = halves.length === 2 ? pieces(halves[1]) : [];
+    if (halves.length === 1 && head.length !== 8)
         return null;
-    let rest = last;
-    for (let i = 3; i >= n - 1; i--) {
-        octets[i] = rest & 0xff;
-        rest = Math.floor(rest / 256);
+    if (head.length + tail.length > 8)
+        return null;
+    const groups = [];
+    for (const piece of head) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
     }
-    return octets.join(".");
+    for (let i = head.length + tail.length; i < 8; i++)
+        groups.push(0);
+    for (const piece of tail) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    return groups.length === 8 ? groups : null;
 }
-function isPrivateIp(addr) {
-    const ip = addr.replace(/^\[/, "").replace(/\]$/, "");
-    const lowerIp = ip.toLowerCase();
-    // IPv6 unspecified / loopback / link-local / unique-local
-    if (lowerIp === "::" || lowerIp === "::1")
-        return true;
-    if (lowerIp.startsWith("fe80:"))
-        return true;
-    if (lowerIp.startsWith("fc") || lowerIp.startsWith("fd"))
-        return true;
-    // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1 / ::ffff:7f00:1) — classify by
-    // the embedded IPv4 address so a mapped literal can't smuggle past.
-    const mapped = lowerIp.match(/^::ffff:(.+)$/);
-    if (mapped) {
-        const tail = mapped[1];
-        if (tail.includes(".")) {
-            return isPrivateIp(tail);
-        }
-        const hexGroups = tail.split(":");
-        if (hexGroups.length === 2 && hexGroups.every((g) => /^[0-9a-f]{1,4}$/.test(g))) {
-            const hi = Number.parseInt(hexGroups[0], 16);
-            const lo = Number.parseInt(hexGroups[1], 16);
-            return isPrivateIp([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff].join("."));
-        }
-        return false;
+/**
+ * The IPv4 address an IPv6 address carries, when it carries one.
+ *
+ * Every transition mechanism embeds a v4 address somewhere, and every one of
+ * them is a way to reach a v4 destination while wearing a v6 spelling that no
+ * v4 range check looks at. The NAT64 well-known prefix is the sharpest: a
+ * DNS64 resolver answers an IPv4-only name with `64:ff9b::<the v4>`, so
+ * `64:ff9b::a9fe:a9fe` IS the metadata service on any network that runs one.
+ */
+function embeddedIpv4(g) {
+    const quad = (hi, lo) => `${(hi >>> 8) & 0xff}.${hi & 0xff}.${(lo >>> 8) & 0xff}.${lo & 0xff}`;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const last = quad(g[6], g[7]);
+    if (zeros(0, 5) && g[5] === 0xffff)
+        return last; // ::ffff:0:0/96, IPv4-mapped
+    if (zeros(0, 4) && g[4] === 0xffff && g[5] === 0)
+        return last; // ::ffff:0:0:0/96, translated
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return last; // 64:ff9b::/96 and 64:ff9b:1::/48, NAT64
+    if (g[0] === 0x2002)
+        return quad(g[1], g[2]); // 2002::/16, 6to4
+    // ::a.b.c.d, IPv4-compatible: deprecated, still routed by some stacks, and
+    // not to be confused with `::` or `::1`, which are handled before this.
+    if (zeros(0, 6))
+        return last;
+    return null;
+}
+/** Ranges that are never a public RPC endpoint. */
+export function isPrivateIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null) {
+        const [a = 0, b = 0, c = 0, d = 0] = v4.split(".").map((n) => Number.parseInt(n, 10));
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local, and the metadata service
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 192 && b === 0 && c === 0)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // carrier-grade NAT
+        if (a === 198 && (b === 18 || b === 19))
+            return true; // benchmarking
+        if (a >= 224)
+            return true; // multicast, reserved, broadcast
+        return a === 255 && b === 255 && c === 255 && d === 255;
     }
-    // IPv4 — normalise octal/hex/integer literals to dotted-decimal first.
-    const normalized = normalizeIpv4(ip);
-    if (normalized === null)
-        return false;
-    const parts = normalized.split(".").map((p) => Number.parseInt(p, 10));
-    if (parts.length !== 4 || parts.some((nn) => Number.isNaN(nn) || nn < 0 || nn > 255)) {
+    const groups = parseIpv6(address);
+    if (groups === null)
         return false;
-    }
-    const [a, b] = parts;
-    if (a === 127)
-        return true; // 127.0.0.0/8 loopback
-    if (a === 10)
-        return true; // 10.0.0.0/8 RFC1918
-    if (a === 169 && b === 254)
-        return true; // 169.254.0.0/16 link-local + AWS metadata
-    if (a === 172 && b >= 16 && b <= 31)
-        return true; // 172.16.0.0/12 RFC1918
-    if (a === 192 && b === 168)
-        return true; // 192.168.0.0/16 RFC1918
-    if (a === 100 && b >= 64 && b <= 127)
-        return true; // 100.64.0.0/10 CGNAT (RFC6598)
-    if (a === 192 && b === 0 && parts[2] === 0)
-        return true; // 192.0.0.0/24 (RFC6890)
-    if (a === 198 && (b === 18 || b === 19))
-        return true; // 198.18.0.0/15 (RFC2544)
-    if (a === 0)
-        return true; // 0.0.0.0/8
-    return false;
+    if (groups.every((g) => g === 0))
+        return true; // ::, the unspecified address
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    const carried = embeddedIpv4(groups);
+    if (carried !== null)
+        return isPrivateIp(carried);
+    const head = groups[0];
+    if ((head & 0xfe00) === 0xfc00)
+        return true; // fc00::/7, unique-local
+    if ((head & 0xffc0) === 0xfe80)
+        return true; // fe80::/10, link-local
+    return (head & 0xff00) === 0xff00; // ff00::/8, multicast
 }
+// END SYNCHRONISED BLOCK
 /**
  * Reject anything that isn't a public http/https target before the browser
  * sees it. This guard blocks the direct vectors — non-http(s) schemes, IP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-navigate",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Navigate tool — drives driver.goto(url) for the BROW agent (Section 25 BROW)",
   "main": "dist/index.js",
@@ -15,10 +15,10 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/computer-use-driver": "0.6.0",
-    "@crewhaus/errors": "0.6.0",
-    "@crewhaus/tool-builder": "0.6.0",
-    "@crewhaus/tool-catalog": "0.6.0",
+    "@crewhaus/computer-use-driver": "0.7.0",
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
     "zod": "^3.23.8"
   },
   "license": "Apache-2.0",