Open-source AI browser agent for Chrome and Firefox (monorepo) π§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
Classify LM Studio fetch targets by IP bytes, not spelling
Barack Sokullu2189954742d2
diff --git a/lmstudio-plugin/README.md b/lmstudio-plugin/README.mdindex cd39fc0a8..0dcea5f92 100644--- a/lmstudio-plugin/README.md+++ b/lmstudio-plugin/README.md@@ -213,7 +213,11 @@ Everything below concerns `fetch_url` / `research_url`. For `browser_task`:- **URL guard, structural (sync).** Requests to RFC1918 (`10.*`,`172.16-31.*`, `192.168.*`), loopback (`127.*`, `::1`), link-local(`169.254.*`, `fe80::/10`), unique-local IPv6 (`fc00::/7`),- cloud-metadata IPs, and `*.local` / `*.internal` / `*.lan` /+ carrier-grade NAT (`100.64.0.0/10`), unspecified (`0.0.0.0/8`, `::`),+ multicast, cloud-metadata IPs, IPv6 addresses that embed any of+ those IPv4 ranges (IPv4-mapped `::ffff:7f00:1` in any spelling,+ IPv4-compatible, NAT64 `64:ff9b::/96`, 6to4 `2002::/16`, Teredo),+ and `*.local` / `*.internal` / `*.lan` /`*.home` / `*.corp` / `*.intranet` are blocked. Non-`http(s)`protocols (`file://`, `ftp://`, `gopher://`, `javascript:`) too.- **DNS resolution check.** Before each hop, the hostname isdiff --git a/lmstudio-plugin/package.json b/lmstudio-plugin/package.jsonindex 095e49478..187a1c8cf 100644--- a/lmstudio-plugin/package.json+++ b/lmstudio-plugin/package.json@@ -15,7 +15,7 @@"scripts": {"build": "tsc","dev": "tsc --watch",- "test": "npm run build && node --test test/browserTask.test.mjs",+ "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs","clean": "rm -rf dist"},"keywords": [diff --git a/lmstudio-plugin/src/util/safeFetch.ts b/lmstudio-plugin/src/util/safeFetch.tsindex 1833b780d..ae06ed83f 100644--- a/lmstudio-plugin/src/util/safeFetch.ts+++ b/lmstudio-plugin/src/util/safeFetch.ts@@ -30,6 +30,7 @@*/import { lookup as dnsLookup } from "node:dns/promises";+import { isIP } from "node:net";import {assertSafeUrl,isPrivateIpv4,@@ -68,8 +69,7 @@ function stripCrossOriginHeaders(/*** Resolve a hostname's A/AAAA records and reject if any address is in- * a private range. Literal IPs are short-circuited (the sync URL guard- * already covered them).+ * a private range. Literal IPs skip DNS and are classified directly.** Why we check ALL returned addresses rather than just the first one* fetch will use: defense-in-depth against accidentally-misconfigured@@ -88,9 +88,17 @@ async function assertHostnameDoesNotResolveToPrivate(host = host.slice(1, -1);}- // Literal IP β the sync guard already validated. Skip DNS.- if (/^\d+\.\d+\.\d+\.\d+$/.test(host)) return;- if (host.includes(":")) return; // literal IPv6+ // Literal IP β nothing to resolve, but classify it here as well+ // rather than trusting the sync guard ran with the same rules.+ const literal = isIP(host);+ if (literal === 4 || literal === 6) {+ if (literal === 4 ? isPrivateIpv4(host) : isPrivateIpv6(host)) {+ throw new Error(+ `Refusing private IPv${literal} ${host} β set allowPrivate to opt in.`,+ );+ }+ return;+ }let addresses: Array<{ address: string; family: number }>;try {diff --git a/lmstudio-plugin/src/util/urlGuard.ts b/lmstudio-plugin/src/util/urlGuard.tsindex 2f95374b7..26fca7d4e 100644--- a/lmstudio-plugin/src/util/urlGuard.ts+++ b/lmstudio-plugin/src/util/urlGuard.ts@@ -12,7 +12,9 @@** `assertSafeUrl(url)` (sync) rejects:* - non-http(s) protocols (file://, ftp://, gopher://, javascript:)- * - literal RFC1918 / loopback / link-local / ULA IPv6 hostnames+ * - literal RFC1918 / loopback / link-local / ULA IPv6 hostnames,+ * including IPv6 forms that embed a private IPv4 (IPv4-mapped,+ * NAT64, 6to4, Teredo)* - common private DNS spellings (localhost, *.local, *.internal, *.lan)** The DNS-resolution-aware check@@ -38,14 +40,14 @@* flag through to safeFetch.*/-const PRIVATE_IPV4_RANGES: Array<[number, number]> = [- // [first byte, second byte]; second byte 0xFF means any- [10, 0xff], // 10.0.0.0/8- [127, 0xff], // 127.0.0.0/8 (loopback)- [169, 254], // 169.254.0.0/16 (link-local + cloud metadata)- [192, 168], // 192.168.0.0/16- [100, 64], // 100.64.0.0/10 carrier-grade NAT (we treat as private)-];+/*+ * IP literals are classified on their bytes, never on their spelling.+ * The WHATWG URL parser rewrites `[::ffff:127.0.0.1]` to+ * `[::ffff:7f00:1]` and `http://2130706433/` to `127.0.0.1`, and an+ * IPv6 address has many equivalent texts (`::1`, `0:0:0:0:0:0:0:1`,+ * `::0001`), so any string-prefix check misses forms that still+ * connect to the same host.+ */function ipv4ToBytes(ip: string): number[] | null {const m = ip.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);@@ -55,29 +57,129 @@ function ipv4ToBytes(ip: string): number[] | null {return bytes;}+/**+ * Parse an IPv6 literal (optionally `[...]`-wrapped, with a `%zone`+ * suffix or a trailing dotted IPv4) into its 16 bytes. Returns null for+ * anything that is not a well-formed IPv6 address.+ */+function ipv6ToBytes(ip: string): number[] | null {+ let s = ip;+ if (s.startsWith("[") && s.endsWith("]")) s = s.slice(1, -1);+ const zone = s.indexOf("%");+ if (zone !== -1) s = s.slice(0, zone);+ if (!s.includes(":")) return null;++ // Rewrite a trailing dotted IPv4 (`::ffff:1.2.3.4`) as two hex groups.+ const lastColon = s.lastIndexOf(":");+ const tail = s.slice(lastColon + 1);+ if (tail.includes(".")) {+ const v4 = ipv4ToBytes(tail);+ if (!v4) return null;+ s = s.slice(0, lastColon + 1) ++ ((v4[0]! << 8) | v4[1]!).toString(16) + ":" ++ ((v4[2]! << 8) | v4[3]!).toString(16);+ }++ const halves = s.split("::");+ if (halves.length > 2) return null;+ const groupsToBytes = (part: string): number[] | null => {+ if (part === "") return [];+ const out: number[] = [];+ for (const group of part.split(":")) {+ if (!/^[0-9a-fA-F]{1,4}$/.test(group)) return null;+ const v = parseInt(group, 16);+ out.push(v >> 8, v & 0xff);+ }+ return out;+ };+ const head = groupsToBytes(halves[0]!);+ if (!head) return null;+ if (halves.length === 1) return head.length === 16 ? head : null;+ const rest = groupsToBytes(halves[1]!);+ // `::` must stand for at least one zero group.+ if (!rest || head.length + rest.length > 14) return null;+ return [+ ...head,+ ...new Array<number>(16 - head.length - rest.length).fill(0),+ ...rest,+ ];+}++/** True if the first `bits` bits of `addr` equal those of `prefix`. */+function inPrefix(addr: number[], prefix: number[], bits: number): boolean {+ for (let i = 0; i * 8 < bits; i++) {+ const take = Math.min(8, bits - i * 8);+ const mask = (0xff << (8 - take)) & 0xff;+ if (((addr[i]! ^ prefix[i]!) & mask) !== 0) return false;+ }+ return true;+}++function v6(text: string): number[] {+ const bytes = ipv6ToBytes(text);+ if (!bytes) throw new Error(`bad IPv6 range constant ${text}`);+ return bytes;+}++const PRIVATE_IPV4_RANGES: Array<[number[], number]> = [+ [[0, 0, 0, 0], 8], // 0.0.0.0/8 "this host"; 0.0.0.0 connects to loopback+ [[10, 0, 0, 0], 8], // 10.0.0.0/8+ [[100, 64, 0, 0], 10], // 100.64.0.0/10 carrier-grade NAT (we treat as private)+ [[127, 0, 0, 0], 8], // 127.0.0.0/8 (loopback)+ [[169, 254, 0, 0], 16], // 169.254.0.0/16 (link-local + cloud metadata)+ [[172, 16, 0, 0], 12], // 172.16.0.0/12+ [[192, 168, 0, 0], 16], // 192.168.0.0/16+ [[224, 0, 0, 0], 4], // 224.0.0.0/4 multicast+ [[240, 0, 0, 0], 4], // 240.0.0.0/4 reserved, incl. 255.255.255.255+];++const PRIVATE_IPV6_RANGES: Array<[number[], number]> = [+ [v6("::"), 128], // unspecified; connects to loopback+ [v6("::1"), 128], // loopback+ [v6("fc00::"), 7], // unique-local+ [v6("fe80::"), 10], // link-local+ [v6("fec0::"), 10], // site-local (deprecated)+ [v6("ff00::"), 8], // multicast+];++/**+ * IPv6 ranges that carry an IPv4 address inside them. The stack (or a+ * translator on the path) delivers these to the embedded IPv4 host, so+ * that address gets the IPv4 rules. Teredo carries two: the server, and+ * the client XOR 0xff.+ */+const IPV4_EMBEDDING_RANGES: Array<[number[], number, (b: number[]) => number[][]]> = [+ [v6("::ffff:0:0"), 96, (b) => [b.slice(12)]], // IPv4-mapped+ [v6("::"), 96, (b) => [b.slice(12)]], // IPv4-compatible (deprecated)+ [v6("::ffff:0:0:0"), 96, (b) => [b.slice(12)]], // IPv4-translated (SIIT)+ [v6("64:ff9b::"), 96, (b) => [b.slice(12)]], // NAT64 well-known prefix+ [v6("2002::"), 16, (b) => [b.slice(2, 6)]], // 6to4+ [v6("2001::"), 32, (b) => [ // Teredo+ b.slice(4, 8),+ b.slice(12).map((x) => x ^ 0xff),+ ]],+];++function isPrivateIpv4Bytes(bytes: number[]): boolean {+ return PRIVATE_IPV4_RANGES.some(([prefix, bits]) => inPrefix(bytes, prefix, bits));+}+export function isPrivateIpv4(ip: string): boolean {const bytes = ipv4ToBytes(ip);- if (!bytes || bytes.length < 4) return false;- const a = bytes[0]!;- const b = bytes[1]!;- for (const [pa, pb] of PRIVATE_IPV4_RANGES) {- if (a === pa && (pb === 0xff || b === pb)) return true;- }- // 172.16.0.0/12 β non-contiguous; second byte 16..31- if (a === 172 && b >= 16 && b <= 31) return true;- return false;+ return !!bytes && isPrivateIpv4Bytes(bytes);}export function isPrivateIpv6(host: string): boolean {- const lower = host.toLowerCase();- // Loopback ::1, link-local fe80::/10, ULAs fc00::/7 (fc00..fdff),- // mapped IPv4 ::ffff:<ipv4> if the inner ipv4 is private.- if (lower === "::1") return true;- if (lower.startsWith("fe8") || lower.startsWith("fe9") ||- lower.startsWith("fea") || lower.startsWith("feb")) return true;- if (lower.startsWith("fc") || lower.startsWith("fd")) return true;- const v4mapped = lower.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);- if (v4mapped?.[1] && isPrivateIpv4(v4mapped[1])) return true;+ const bytes = ipv6ToBytes(host);+ if (!bytes) return false;+ if (PRIVATE_IPV6_RANGES.some(([prefix, bits]) => inPrefix(bytes, prefix, bits))) {+ return true;+ }+ for (const [prefix, bits, embedded] of IPV4_EMBEDDING_RANGES) {+ if (inPrefix(bytes, prefix, bits) && embedded(bytes).some(isPrivateIpv4Bytes)) {+ return true;+ }+ }return false;}diff --git a/lmstudio-plugin/test/urlGuard.test.mjs b/lmstudio-plugin/test/urlGuard.test.mjsnew file mode 100644index 000000000..64cb430eb--- /dev/null+++ b/lmstudio-plugin/test/urlGuard.test.mjs@@ -0,0 +1,164 @@+import assert from "node:assert/strict";+import { once } from "node:events";+import { createServer } from "node:http";+import { createRequire } from "node:module";+import { test } from "node:test";++import {+ assertSafeUrl,+ isPrivateIpv4,+ isPrivateIpv6,+} from "../dist/util/urlGuard.js";+import { safeFetch } from "../dist/util/safeFetch.js";++// [address, why it reaches a private host]+const PRIVATE_IPV6 = [+ ["::1", "loopback"],+ ["0:0:0:0:0:0:0:1", "loopback, uncompressed"],+ ["::", "unspecified"],+ ["::ffff:127.0.0.1", "IPv4-mapped loopback, dotted"],+ ["::ffff:7f00:1", "IPv4-mapped loopback, hex (WHATWG form)"],+ ["::FFFF:7F00:0001", "IPv4-mapped loopback, upper-case and padded"],+ ["0:0:0:0:0:ffff:7f00:1", "IPv4-mapped loopback, uncompressed"],+ ["::ffff:a9fe:a9fe", "IPv4-mapped cloud metadata"],+ ["::ffff:a00:1", "IPv4-mapped 10.0.0.1"],+ ["::ffff:ac10:1", "IPv4-mapped 172.16.0.1"],+ ["::ffff:c0a8:101", "IPv4-mapped 192.168.1.1"],+ ["::ffff:0:0", "IPv4-mapped 0.0.0.0"],+ ["::ffff:0:7f00:1", "IPv4-translated loopback"],+ ["::7f00:1", "IPv4-compatible loopback"],+ ["::127.0.0.1", "IPv4-compatible loopback, dotted"],+ ["64:ff9b::7f00:1", "NAT64 loopback"],+ ["64:ff9b::169.254.169.254", "NAT64 cloud metadata"],+ ["2002:7f00:1::", "6to4 loopback"],+ ["2002:a9fe:a9fe::1", "6to4 cloud metadata"],+ ["2001:0:4136:e378::80ff:fffe", "Teredo client 127.0.0.1"],+ ["2001:0:a9fe:a9fe::f7f7:f7f7", "Teredo server 169.254.169.254"],+ ["fe80::1", "link-local"],+ ["febf:ffff::1", "link-local, top of /10"],+ ["fe80::1%eth0", "link-local with zone id"],+ ["fc00::1", "unique-local"],+ ["fd12:3456:789a::1", "unique-local"],+ ["fec0::1", "site-local"],+ ["ff02::1", "multicast"],+];++const PUBLIC_IPV6 = [+ "2606:4700:4700::1111",+ "2001:4860:4860::8888",+ "::ffff:8.8.8.8",+ "::ffff:808:808",+ "64:ff9b::808:808",+ "2002:808:808::1",+ "2001:0:4136:e378:8000:63bf:3fff:fdd2",+];++const PRIVATE_IPV4 = [+ "0.0.0.0",+ "0.1.2.3",+ "10.1.2.3",+ "100.64.0.1",+ "100.127.255.255",+ "127.0.0.1",+ "169.254.169.254",+ "172.16.0.1",+ "172.31.255.255",+ "192.168.0.1",+ "224.0.0.1",+ "255.255.255.255",+];++const PUBLIC_IPV4 = [+ "1.1.1.1",+ "8.8.8.8",+ "100.63.255.255",+ "100.128.0.1",+ "172.15.255.255",+ "172.32.0.1",+ "192.0.2.1",+];++test("isPrivateIpv6 classifies by address bytes, not spelling", () => {+ for (const [address, why] of PRIVATE_IPV6) {+ assert.equal(isPrivateIpv6(address), true, `${address} (${why})`);+ }+ for (const address of PUBLIC_IPV6) {+ assert.equal(isPrivateIpv6(address), false, address);+ }+});++test("isPrivateIpv4 covers this-host, CGNAT /10, multicast and reserved", () => {+ for (const address of PRIVATE_IPV4) {+ assert.equal(isPrivateIpv4(address), true, address);+ }+ for (const address of PUBLIC_IPV4) {+ assert.equal(isPrivateIpv4(address), false, address);+ }+});++test("assertSafeUrl refuses every spelling of a private IP host", () => {+ const hosts = [+ ...PRIVATE_IPV6+ .filter(([address]) => !address.includes("%"))+ .map(([address]) => `[${address}]`),+ ...PRIVATE_IPV4,+ "127.1",+ "2130706433",+ "0x7f.0.0.1",+ "0",+ ];+ for (const host of hosts) {+ assert.throws(+ () => assertSafeUrl(`http://${host}:8080/`),+ /Refusing private/,+ host,+ );+ }+});++test("assertSafeUrl still allows public IP hosts", () => {+ for (const host of [...PUBLIC_IPV6.map((a) => `[${a}]`), ...PUBLIC_IPV4]) {+ assert.doesNotThrow(() => assertSafeUrl(`http://${host}/`), host);+ }+});++test("safeFetch does not reach loopback through IPv4-mapped or unspecified hosts", async () => {+ let hits = 0;+ const server = createServer((_req, res) => {+ hits++;+ res.end("local secret");+ });+ server.listen(0, "127.0.0.1");+ await once(server, "listening");+ const { port } = server.address();+ try {+ for (const host of ["[::ffff:127.0.0.1]", "[::ffff:7f00:1]", "0.0.0.0", "[::]"]) {+ await assert.rejects(+ safeFetch(`http://${host}:${port}/`),+ /Refusing private/,+ host,+ );+ }+ assert.equal(hits, 0);+ } finally {+ server.close();+ }+});++test("safeFetch's DNS layer classifies literal IPs itself", async () => {+ // Disable the sync guard so only the resolver-side check is left.+ const guard = createRequire(import.meta.url)("../dist/util/urlGuard.js");+ const original = guard.assertSafeUrl;+ guard.assertSafeUrl = (url) => new URL(url);+ try {+ for (const host of ["[::ffff:7f00:1]", "[64:ff9b::a9fe:a9fe]", "0.0.0.0"]) {+ await assert.rejects(+ safeFetch(`http://${host}:9/`),+ /Refusing private/,+ host,+ );+ }+ } finally {+ guard.assertSafeUrl = original;+ }+});