Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

Classify LM Studio fetch targets by IP bytes, not spelling

Barack Sokullu2189954742d2
diff --git a/lmstudio-plugin/README.md b/lmstudio-plugin/README.md
index 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 is
diff --git a/lmstudio-plugin/package.json b/lmstudio-plugin/package.json
index 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.ts
index 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.ts
index 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.mjs
new file mode 100644
index 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;
+ }
+});