@crewhaus/computer-use-driver 0.6.0 → 0.7.0

package/dist/ssrf-proxy.d.ts

@@ -15,12 +15,27 @@ export type StartSsrfPinningProxyOptions = {
     readonly _isIpBlocked?: (ip: string) => boolean;
 };
 /**
- * Normalise an IPv4 literal to canonical dotted-decimal. Browsers and many
- * HTTP stacks accept octal (`0177.0.0.1`), hex (`0x7f.0.0.1` / `0x7f000001`),
- * and 32-bit integer (`2130706433`) forms — all of which resolve to the same
- * address as `127.0.0.1`. Canonicalising first means `isPrivateIp` classifies
- * them. Returns dotted-decimal, or `null` if `raw` is not an IPv4 literal.
+ * 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;
-export declare function isPrivateIp(addr: string): boolean;
+/**
+ * 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;
 export declare function startSsrfPinningProxy(opts?: StartSsrfPinningProxyOptions): Promise<SsrfPinningProxy>;

package/dist/ssrf-proxy.js

@@ -27,138 +27,244 @@
  * attacker page fetch http://127.0.0.1:… directly. `<-loopback>` removes that
  * implicit bypass so loopback targets also route here — and get blocked.
  *
- * The IP-validation helpers mirror tool-fetch's `assertNotSsrf` family —
- * duplicated (like tool-navigate and crawler) rather than extracted to a
- * shared package, per the Pillar 3 convention; keep the copies in sync.
+ * The IP-validation helpers below are the synchronised private-address
+ * classifier, byte-identical to every other copy in the tree. Its own header
+ * explains why it parses addresses instead of matching their text; never edit
+ * one copy alone.
  *
- * The proxy binds 127.0.0.1 on an ephemeral port and refuses private targets,
- * so it cannot be leveraged by other local processes to reach internal
- * services.
+ * WHAT THE LOOPBACK BIND DOES AND DOES NOT GUARANTEE. The proxy listens on
+ * 127.0.0.1 on an ephemeral port, so only processes on this machine can reach
+ * it, and both request paths — the absolute-form URL and the CONNECT target —
+ * are classified by that same `isPrivateIp`, so no spelling of a private
+ * address is tunnelled or forwarded. It is NOT authenticated: any local process
+ * that finds the port can use it to reach PUBLIC hosts for as long as the
+ * browser session lasts. And an IPv4 address behind an operator-chosen NAT64
+ * prefix stays undecidable from the address alone (see the block header). Until
+ * 2026-09-18 this paragraph claimed flatly that the proxy "cannot be leveraged
+ * by other local processes to reach internal services"; it could, because the
+ * CONNECT target was classified by text and `CONNECT [0:0:0:0:0:0:0:1]:<port>`
+ * was answered with 200.
  */
 import { lookup as dnsLookup } from "node:dns/promises";
 import * as http from "node:http";
 import * as net from "node:net";
 import { ComputerUseDriverError } from "./errors";
 const defaultDnsLookup = (host) => dnsLookup(host, { verbatim: false });
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
 /**
- * Normalise an IPv4 literal to canonical dotted-decimal. Browsers and many
- * HTTP stacks accept octal (`0177.0.0.1`), hex (`0x7f.0.0.1` / `0x7f000001`),
- * and 32-bit integer (`2130706433`) forms — all of which resolve to the same
- * address as `127.0.0.1`. Canonicalising first means `isPrivateIp` classifies
- * them. Returns dotted-decimal, or `null` if `raw` is not an IPv4 literal.
+ * 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 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);
     }
-    // RFC-3986-style packing: the final component absorbs the remaining bytes
-    // (e.g. `127.1` ⇒ 127.0.0.1, `2130706433` ⇒ 127.0.0.1, `0x7f.0.0.1`).
-    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;
+    if (head.length + tail.length > 8)
         return null;
-    let rest = last;
-    for (let i = 3; i >= n - 1; i--) {
-        octets[i] = rest & 0xff;
-        rest = Math.floor(rest / 256);
+    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;
 }
-export function isPrivateIp(addr) {
-    // Strip IPv6 brackets if present.
-    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 the checks.
-    const mapped = lowerIp.match(/^::ffff:(.+)$/);
-    if (mapped) {
-        const tail = mapped[1];
-        if (tail.includes(".")) {
-            return isPrivateIp(tail);
-        }
-        // Hex form ::ffff:7f00:0001 → 127.0.0.1
-        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 IETF protocol (RFC6890)
-    if (a === 198 && (b === 18 || b === 19))
-        return true; // 198.18.0.0/15 benchmarking (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
 class BlockedTargetError extends ComputerUseDriverError {
 }
+/**
+ * A host as the classifier must see it: brackets off, lower-cased.
+ *
+ * On the plain-HTTP path `new URL()` canonicalises the hostname before we ever
+ * look at it. The CONNECT path has no URL — its target is read straight off the
+ * request line, so whatever the client typed is what arrives, uncompressed IPv6
+ * and all. Both paths go through here and then through the same `isPrivateIp`,
+ * which parses rather than matches text; that, not this function, is what makes
+ * the spelling stop mattering.
+ */
+function unbracketHost(host) {
+    return host.trim().replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+}
 /**
  * Resolve `hostname` once and validate the result. Returns the pinned IP the
  * caller must dial — never let anything re-resolve after this.
@@ -169,8 +275,11 @@ async function resolvePinned(hostname, lookupFn, isBlocked) {
         throw new BlockedTargetError(`blocked host "${hostname}": loopback/mDNS name`);
     }
     // An IP literal is its own pinned target — no DNS lookup, nothing to rebind.
-    const unbracketed = lower.replace(/^\[/, "").replace(/\]$/, "");
-    const literal = normalizeIpv4(unbracketed) ?? (unbracketed.includes(":") ? unbracketed : null);
+    // A colon alone used to be enough to call something an IPv6 literal, which
+    // handed the dial an unvalidated string; `parseIpv6` decides now, and it
+    // accepts every spelling, so nothing takes this path unclassified.
+    const unbracketed = unbracketHost(lower);
+    const literal = normalizeIpv4(unbracketed) ?? (parseIpv6(unbracketed) === null ? null : unbracketed);
     if (literal !== null) {
         if (isBlocked(literal)) {
             throw new BlockedTargetError(`blocked target IP ${literal}`);
@@ -190,9 +299,21 @@ async function resolvePinned(hostname, lookupFn, isBlocked) {
     }
     return { ip: resolved.address, family: resolved.family };
 }
-/** Parse a CONNECT target ("host:port", "[::1]:443") into host + port. */
+/**
+ * Parse a CONNECT target ("host:port", "[::1]:443") into host + port.
+ *
+ * SECURITY: this is a regex over the raw request line, because CONNECT has no
+ * URL to parse — so the host arrives exactly as the client typed it, including
+ * spellings `new URL()` would have rewritten. Returning it unbracketed and
+ * lower-cased puts it in the same shape as a hostname taken off a parsed URL,
+ * and `resolvePinned` then classifies it with the same `isPrivateIp` the HTTP
+ * path uses. Until 2026-09-18 the classifier compared text, so
+ * `CONNECT [0:0:0:0:0:0:0:1]:<port>` was answered with 200 and tunnelled to
+ * loopback; the fix is that the classifier parses, not that this regex knows
+ * more spellings.
+ */
 function parseConnectTarget(target) {
-    const m = target.match(/^\[(.+)\]:(\d{1,5})$/) ?? target.match(/^([^:]+):(\d{1,5})$/);
+    const m = target.match(/^\[([^\]]+)\]:(\d{1,5})$/) ?? target.match(/^([^:]+):(\d{1,5})$/);
     if (m === null) {
         throw new BlockedTargetError(`malformed CONNECT target "${target}"`);
     }
@@ -200,7 +321,11 @@ function parseConnectTarget(target) {
     if (port < 1 || port > 65535) {
         throw new BlockedTargetError(`malformed CONNECT target "${target}": bad port`);
     }
-    return { host: m[1], port };
+    const host = unbracketHost(m[1]);
+    if (host === "") {
+        throw new BlockedTargetError(`malformed CONNECT target "${target}": empty host`);
+    }
+    return { host, port };
 }
 // Hop-by-hop headers must not be forwarded by a proxy (RFC 7230 §6.1).
 const HOP_BY_HOP = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/computer-use-driver",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Cross-platform mouse/keyboard/screenshot driver — chromium backend (Section 25 BROW)",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.6.0"
+    "@crewhaus/errors": "0.7.0"
   },
   "peerDependencies": {
     "playwright": "*"