Skip to content

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

Make LM Studio private-network access a user setting, not a tool argument

Barack Sokullu5d6149e29dee
diff --git a/lmstudio-plugin/README.md b/lmstudio-plugin/README.md
index cd39fc0a8..32855b44e 100644
--- a/lmstudio-plugin/README.md
+++ b/lmstudio-plugin/README.md
@@ -236,9 +236,25 @@ Everything below concerns `fetch_url` / `research_url`. For `browser_task`:
this plugin makes anonymous requests.
- **Timeouts.** Default 30 s, hard cap 120 s.
-Set `allowPrivate: true` on a per-call basis to opt out of the URL
-guard + DNS check — useful when you actually want to talk to
-localhost services.
+### Private network access
+
+Private targets are opened by you, not by the model. To let `fetch_url`
+and `research_url` reach localhost or your LAN, turn on **Allow private
+network access** in this plugin's settings in LM Studio. The setting is
+per chat and off by default. The tools have no `allowPrivate` argument,
+and one sent anyway is ignored, so a page the model reads cannot talk
+it into switching the guard off.
+
+Cloud metadata endpoints stay blocked even with the setting on:
+`169.254.169.254`, `169.254.170.2`, `169.254.170.23`, `169.254.0.23`,
+`100.100.100.200`, `fd00:ec2::254`, `fd00:ec2::23`,
+`metadata.google.internal`, `metadata.goog` and `metadata`, including
+IPv4-mapped IPv6 spellings, hostnames that resolve to them, and
+redirects to them.
+
+While the setting is on, the model still chooses the URL, method,
+headers and body, and a page it reads can steer it toward your router,
+admin panels or local services. Turn it on only in chats that need it.
### Known residual gap: DNS rebinding
diff --git a/lmstudio-plugin/package.json b/lmstudio-plugin/package.json
index 095e49478..deadac8d2 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/privateNetworkSetting.test.mjs",
"clean": "rm -rf dist"
},
"keywords": [
diff --git a/lmstudio-plugin/src/index.ts b/lmstudio-plugin/src/index.ts
index e66e6d7da..1e63eb567 100644
--- a/lmstudio-plugin/src/index.ts
+++ b/lmstudio-plugin/src/index.ts
@@ -25,8 +25,8 @@
* at plugin load time.
*/
-import { tool } from "@lmstudio/sdk";
-import type { PluginContext } from "@lmstudio/sdk";
+import { createConfigSchematics, tool } from "@lmstudio/sdk";
+import type { PluginContext, ToolsProviderController } from "@lmstudio/sdk";
import { z } from "zod";
import { fetchUrl } from "./tools/fetchUrl.js";
import { researchUrl } from "./tools/researchUrl.js";
@@ -37,8 +37,45 @@ import {
browserTask,
} from "./tools/browserTask.js";
import { sharedBridge } from "./util/bridgeClient.js";
+import type { UrlGuardOptions } from "./util/urlGuard.js";
-const fetchUrlTool = tool({
+/**
+ * Per-chat plugin settings, shown to the user in LM Studio and never to
+ * the model. Private-network access lives here rather than in the tool
+ * schemas: as a tool argument, any page the model had just read could
+ * ask it to switch the guard off.
+ */
+export const configSchematics = createConfigSchematics()
+ .field(
+ "allowPrivateNetwork",
+ "boolean",
+ {
+ displayName: "Allow private network access",
+ subtitle:
+ "Let fetch_url and research_url reach localhost, your LAN (10.*, " +
+ "172.16-31.*, 192.168.*), link-local and other private addresses. " +
+ "Cloud metadata endpoints stay blocked.",
+ warning:
+ "The model chooses the URL, method, headers and body. A page it " +
+ "reads can steer it toward routers, admin panels and local services.",
+ },
+ false,
+ )
+ .build();
+
+export function readNetworkOptions(ctl: ToolsProviderController): UrlGuardOptions {
+ try {
+ return {
+ allowPrivate:
+ ctl.getPluginConfig(configSchematics).get("allowPrivateNetwork") === true,
+ };
+ } catch {
+ // An unreadable config must not take down the tools; fail closed.
+ return { allowPrivate: false };
+ }
+}
+
+const createFetchUrlTool = (network: UrlGuardOptions) => tool({
name: "fetch_url",
description:
"Fetch a URL and return its content. Auto-detects content type: " +
@@ -81,27 +118,20 @@ const fetchUrlTool = tool({
.describe(
"Compact long text/json with a head/middle/tail extractive pass. Defaults to true. Set false for head-only truncation.",
),
- allowPrivate: z
- .boolean()
- .optional()
- .describe(
- "Allow targets that resolve to RFC1918 / loopback / link-local " +
- "addresses (localhost, 192.168.*, 10.*, 172.16-31.*, " +
- "169.254.*, fe80::*, fc00::/7). Off by default to keep the " +
- "model out of cloud-metadata services and the user's intranet.",
- ),
},
- implementation: async ({ url, method, headers, body, timeout, allowPrivate, maxChars, compact }) => {
- const result = await fetchUrl({
- url,
- method,
- headers,
- body,
- timeout,
- allowPrivate,
- maxChars,
- compact,
- });
+ implementation: async ({ url, method, headers, body, timeout, maxChars, compact }) => {
+ const result = await fetchUrl(
+ {
+ url,
+ method,
+ headers,
+ body,
+ timeout,
+ maxChars,
+ compact,
+ },
+ network,
+ );
// The implementation contract returns whatever string the LLM
// should see in the tool result. JSON-stringify so the model gets
// stable, parseable structure rather than a `[object Object]`.
@@ -109,7 +139,7 @@ const fetchUrlTool = tool({
},
});
-const researchUrlTool = tool({
+const createResearchUrlTool = (network: UrlGuardOptions) => tool({
name: "research_url",
description:
"Fetch a URL and return its readable article body, biased toward " +
@@ -140,16 +170,9 @@ const researchUrlTool = tool({
.describe(
"Compact long article text with a head/middle/tail extractive pass. Defaults to true. Set false for head-only truncation.",
),
- allowPrivate: z
- .boolean()
- .optional()
- .describe(
- "Allow targets that resolve to RFC1918 / loopback / link-local. " +
- "Off by default.",
- ),
},
- implementation: async ({ url, timeout, allowPrivate, maxChars, compact }) => {
- const result = await researchUrl({ url, timeout, allowPrivate, maxChars, compact });
+ implementation: async ({ url, timeout, maxChars, compact }) => {
+ const result = await researchUrl({ url, timeout, maxChars, compact }, network);
return JSON.stringify(result, null, 2);
},
});
@@ -300,14 +323,20 @@ export async function main(ctx: PluginContext): Promise<void> {
);
}
- ctx.withToolsProvider(async () => [
- fetchUrlTool,
- researchUrlTool,
- browserTaskTool,
- browserStatusTool,
- browserRespondTool,
- browserAbortTool,
- ]);
+ ctx.withConfigSchematics(configSchematics);
+ ctx.withToolsProvider(async (ctl) => {
+ // LM Studio calls this once per session with that chat's settings,
+ // and again when the user changes them.
+ const network = readNetworkOptions(ctl);
+ return [
+ createFetchUrlTool(network),
+ createResearchUrlTool(network),
+ browserTaskTool,
+ browserStatusTool,
+ browserRespondTool,
+ browserAbortTool,
+ ];
+ });
}
// Some plugin loaders look at the default export instead of `main`.
diff --git a/lmstudio-plugin/src/tools/fetchUrl.ts b/lmstudio-plugin/src/tools/fetchUrl.ts
index 7e12f0bca..f0d5ed1a3 100644
--- a/lmstudio-plugin/src/tools/fetchUrl.ts
+++ b/lmstudio-plugin/src/tools/fetchUrl.ts
@@ -10,11 +10,14 @@
* http://169.254.169.254/latest/meta-data/ would happily exfil
* cloud-credential blobs from the user's machine; the guard
* blocks file://, RFC1918, link-local, and ULA targets by
- * default. Opt out per-call with `allowPrivate: true`.
+ * default. Private targets open only through the `opts` argument,
+ * which the plugin fills from the user's setting; `args` holds
+ * what the model sent and cannot lift the guard.
*/
import { htmlToText } from "../util/htmlToText.js";
import { safeFetch, readBodyCapped } from "../util/safeFetch.js";
+import type { UrlGuardOptions } from "../util/urlGuard.js";
import {
compactText,
normalizeTextLimit,
@@ -43,13 +46,6 @@ export interface FetchUrlArgs {
body?: string;
/** ms; default 30 000, cap 120 000. */
timeout?: number;
- /**
- * Allow URLs that target RFC1918 / loopback / link-local addresses.
- * Off by default to keep the LLM out of cloud-metadata services and
- * the user's intranet. Set to true only when you actually want the
- * plugin to talk to localhost/private services.
- */
- allowPrivate?: boolean;
/**
* Maximum characters returned in the main text/json field after compaction.
* Defaults to 8k for text/html and 16k for JSON; capped at 50k.
@@ -124,7 +120,15 @@ function prepareModelText(
};
}
-export async function fetchUrl(args: FetchUrlArgs): Promise<FetchUrlResult> {
+/**
+ * `opts.allowPrivate` opens RFC1918 / loopback / link-local targets. It
+ * is separate from `args` so a caller can pass model-supplied arguments
+ * straight through without handing the model the guard's off switch.
+ */
+export async function fetchUrl(
+ args: FetchUrlArgs,
+ opts: UrlGuardOptions = {},
+): Promise<FetchUrlResult> {
if (!args?.url) return { success: false, error: "url is required" };
const timeoutMs = Math.min(
@@ -144,7 +148,7 @@ export async function fetchUrl(args: FetchUrlArgs): Promise<FetchUrlResult> {
headers: args.headers || {},
body: args.body,
signal: controller.signal,
- allowPrivate: !!args.allowPrivate,
+ allowPrivate: opts.allowPrivate === true,
});
const contentType = (res.headers.get("content-type") || "").toLowerCase();
const status = res.status;
diff --git a/lmstudio-plugin/src/tools/researchUrl.ts b/lmstudio-plugin/src/tools/researchUrl.ts
index 32321ab1a..bfe892e47 100644
--- a/lmstudio-plugin/src/tools/researchUrl.ts
+++ b/lmstudio-plugin/src/tools/researchUrl.ts
@@ -31,6 +31,7 @@
import { htmlToText } from "../util/htmlToText.js";
import { safeFetch, readBodyCapped } from "../util/safeFetch.js";
+import type { UrlGuardOptions } from "../util/urlGuard.js";
import {
compactText,
normalizeTextLimit,
@@ -50,8 +51,6 @@ export interface ResearchUrlArgs {
url: string;
/** ms; default 30 000, cap 120 000. */
timeout?: number;
- /** Allow RFC1918 / loopback targets. Off by default. */
- allowPrivate?: boolean;
/**
* Maximum characters returned in the main text field after compaction.
* Defaults to 16k; capped at 60k.
@@ -189,7 +188,14 @@ function extractLinks(html: string, base: string): ResearchUrlLink[] {
return out;
}
-export async function researchUrl(args: ResearchUrlArgs): Promise<ResearchUrlResult> {
+/**
+ * `opts.allowPrivate` opens RFC1918 / loopback / link-local targets; it
+ * is kept out of `args` for the same reason as in `fetchUrl`.
+ */
+export async function researchUrl(
+ args: ResearchUrlArgs,
+ opts: UrlGuardOptions = {},
+): Promise<ResearchUrlResult> {
if (!args?.url) return { success: false, error: "url is required" };
const timeoutMs = Math.min(
@@ -205,7 +211,7 @@ export async function researchUrl(args: ResearchUrlArgs): Promise<ResearchUrlRes
const res = await safeFetch(args.url, {
method: "GET",
signal: controller.signal,
- allowPrivate: !!args.allowPrivate,
+ allowPrivate: opts.allowPrivate === true,
headers: {
// Some sites gate on User-Agent. Pretend to be a recent
// desktop Firefox — same MO as curl/wget defaults.
diff --git a/lmstudio-plugin/src/util/safeFetch.ts b/lmstudio-plugin/src/util/safeFetch.ts
index 1833b780d..14f693641 100644
--- a/lmstudio-plugin/src/util/safeFetch.ts
+++ b/lmstudio-plugin/src/util/safeFetch.ts
@@ -32,8 +32,10 @@
import { lookup as dnsLookup } from "node:dns/promises";
import {
assertSafeUrl,
+ isCloudMetadataHost,
isPrivateIpv4,
isPrivateIpv6,
+ PRIVATE_NETWORK_HINT,
type UrlGuardOptions,
} from "./urlGuard.js";
@@ -75,13 +77,14 @@ function stripCrossOriginHeaders(
* fetch will use: defense-in-depth against accidentally-misconfigured
* dual-stack hosts and against future fetch-implementation changes
* about which family wins in `lookup({ all: false })`.
+ *
+ * With allowPrivate the lookup still runs, because a hostname that
+ * resolves to a cloud metadata address stays blocked.
*/
async function assertHostnameDoesNotResolveToPrivate(
parsed: URL,
opts: UrlGuardOptions,
): Promise<void> {
- if (opts.allowPrivate) return;
-
// Strip the [..] wrapper IPv6 URL syntax adds.
let host = parsed.hostname;
if (host.startsWith("[") && host.endsWith("]")) {
@@ -102,14 +105,20 @@ async function assertHostnameDoesNotResolveToPrivate(
}
for (const { address, family } of addresses) {
+ if (isCloudMetadataHost(address)) {
+ throw new Error(
+ `Refusing ${host} — resolves to cloud metadata endpoint ${address}, which stays blocked even with private network access on.`,
+ );
+ }
+ if (opts.allowPrivate) continue;
if (family === 4 && isPrivateIpv4(address)) {
throw new Error(
- `Refusing ${host} — resolves to private IPv4 ${address}. Set allowPrivate to opt in.`,
+ `Refusing ${host} — resolves to private IPv4 ${address}; ${PRIVATE_NETWORK_HINT}`,
);
}
if (family === 6 && isPrivateIpv6(address)) {
throw new Error(
- `Refusing ${host} — resolves to private IPv6 ${address}. Set allowPrivate to opt in.`,
+ `Refusing ${host} — resolves to private IPv6 ${address}; ${PRIVATE_NETWORK_HINT}`,
);
}
}
@@ -120,7 +129,11 @@ export interface SafeFetchInit {
headers?: Record<string, string>;
body?: string | undefined;
signal?: AbortSignal;
- /** Allow private/loopback/link-local destinations. Default false. */
+ /**
+ * Allow private/loopback/link-local destinations. Default false. Set
+ * from the user's plugin setting, never from tool arguments. Cloud
+ * metadata endpoints stay blocked regardless.
+ */
allowPrivate?: boolean;
/** Cap manual redirect hops. Default 5. */
maxRedirects?: number;
diff --git a/lmstudio-plugin/src/util/urlGuard.ts b/lmstudio-plugin/src/util/urlGuard.ts
index 2f95374b7..e893cd88e 100644
--- a/lmstudio-plugin/src/util/urlGuard.ts
+++ b/lmstudio-plugin/src/util/urlGuard.ts
@@ -14,6 +14,7 @@
* - non-http(s) protocols (file://, ftp://, gopher://, javascript:)
* - literal RFC1918 / loopback / link-local / ULA IPv6 hostnames
* - common private DNS spellings (localhost, *.local, *.internal, *.lan)
+ * - cloud metadata endpoints, even when allowPrivate is set
*
* The DNS-resolution-aware check
* (`assertHostnameDoesNotResolveToPrivate`) lives in `safeFetch.ts`
@@ -35,7 +36,10 @@
*
* To opt-out (e.g. you really do want to point this at your intranet)
* call assertSafeUrl(url, { allowPrivate: true }) and pass the same
- * flag through to safeFetch.
+ * flag through to safeFetch. In the plugin that flag comes only from
+ * the user's "Allow private network access" setting, never from a tool
+ * argument: a page the model just read must not be able to switch the
+ * guard off. Cloud metadata endpoints stay blocked either way.
*/
const PRIVATE_IPV4_RANGES: Array<[number, number]> = [
@@ -105,11 +109,71 @@ function isPrivateHostname(host: string): boolean {
return false;
}
+// Cloud instance-metadata services hand out the machine's cloud
+// credentials. Reaching a service on the user's own LAN is a reasonable
+// opt-in; giving the model those credentials is not, so these stay
+// blocked even with allowPrivate. IPv6 entries are in the canonical form
+// the WHATWG URL parser produces.
+const CLOUD_METADATA_IPV4 = new Set([
+ "169.254.169.254", // AWS, GCP, Azure, OCI, DigitalOcean, OpenStack and others
+ "169.254.170.2", // AWS ECS task metadata and credentials
+ "169.254.170.23", // AWS EKS Pod Identity agent
+ "169.254.0.23", // Tencent Cloud
+ "100.100.100.200", // Alibaba Cloud
+]);
+const CLOUD_METADATA_IPV6 = new Set([
+ "fd00:ec2::254", // AWS IMDS over IPv6
+ "fd00:ec2::23", // AWS EKS Pod Identity agent over IPv6
+]);
+const CLOUD_METADATA_HOSTNAMES = new Set([
+ "metadata.google.internal",
+ "metadata.goog",
+ "metadata",
+]);
+
+/**
+ * True for a cloud metadata endpoint, given a URL hostname (with or
+ * without IPv6 brackets) or a resolved address. An IPv4-mapped IPv6
+ * address counts as its IPv4 address.
+ */
+export function isCloudMetadataHost(host: string): boolean {
+ let lower = host.toLowerCase();
+ if (lower.startsWith("[") && lower.endsWith("]")) lower = lower.slice(1, -1);
+ if (lower.endsWith(".")) lower = lower.slice(0, -1);
+ if (CLOUD_METADATA_IPV4.has(lower) || CLOUD_METADATA_HOSTNAMES.has(lower)) return true;
+ if (!lower.includes(":")) return false;
+
+ // Canonicalise through the URL parser so fd00:ec2:0:0:0:0:0:254 and
+ // ::ffff:169.254.169.254 compare equal to the forms listed above.
+ let canonical: string;
+ try {
+ canonical = new URL(`http://[${lower}]/`).hostname.slice(1, -1);
+ } catch {
+ return false;
+ }
+ if (CLOUD_METADATA_IPV6.has(canonical)) return true;
+ const mapped = canonical.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+ if (!mapped?.[1] || !mapped[2]) return false;
+ const hi = parseInt(mapped[1], 16);
+ const lo = parseInt(mapped[2], 16);
+ return CLOUD_METADATA_IPV4.has(`${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`);
+}
+
+/**
+ * Appended to private-target refusals. The model reads tool errors, so
+ * this tells it what to relay to the user instead of what to retry.
+ */
+export const PRIVATE_NETWORK_HINT =
+ "private network access is off. The user can turn on \"Allow private " +
+ "network access\" in this plugin's settings in LM Studio.";
+
export interface UrlGuardOptions {
/**
* Set true to allow URLs that resolve to RFC1918 / loopback / link-
* local addresses. Use only when you actually want the plugin to
- * reach intranet services. Default false.
+ * reach intranet services. Default false. Cloud metadata endpoints
+ * stay blocked regardless. The plugin sets this from the user's
+ * plugin setting; never take it from model-supplied tool arguments.
*/
allowPrivate?: boolean;
}
@@ -131,6 +195,11 @@ export function assertSafeUrl(input: string, opts: UrlGuardOptions = {}): URL {
`Refusing ${parsed.protocol} URL — this plugin only fetches http(s).`,
);
}
+ if (isCloudMetadataHost(parsed.hostname)) {
+ throw new Error(
+ `Refusing cloud metadata endpoint ${parsed.hostname} — blocked even with private network access on.`,
+ );
+ }
if (opts.allowPrivate) return parsed;
// hostname for IPv6 comes back wrapped in [] — strip them.
@@ -141,17 +210,17 @@ export function assertSafeUrl(input: string, opts: UrlGuardOptions = {}): URL {
if (isPrivateIpv4(host)) {
throw new Error(
- `Refusing private IPv4 ${host} — set allowPrivate to opt in.`,
+ `Refusing private IPv4 ${host} — ${PRIVATE_NETWORK_HINT}`,
);
}
if (host.includes(":") && isPrivateIpv6(host)) {
throw new Error(
- `Refusing private IPv6 ${host} — set allowPrivate to opt in.`,
+ `Refusing private IPv6 ${host} — ${PRIVATE_NETWORK_HINT}`,
);
}
if (isPrivateHostname(host)) {
throw new Error(
- `Refusing private hostname ${host} — set allowPrivate to opt in.`,
+ `Refusing private hostname ${host} — ${PRIVATE_NETWORK_HINT}`,
);
}
return parsed;
diff --git a/lmstudio-plugin/test/browserTask.test.mjs b/lmstudio-plugin/test/browserTask.test.mjs
index a8cabee7b..f794b4f48 100644
--- a/lmstudio-plugin/test/browserTask.test.mjs
+++ b/lmstudio-plugin/test/browserTask.test.mjs
@@ -36,6 +36,9 @@ before(async () => {
process.env.WEBBRAIN_BRIDGE_PORT = String(await freePort());
process.env.WEBBRAIN_COMMAND_TIMEOUT_MS = "50";
const context = {
+ withConfigSchematics() {
+ return context;
+ },
withToolsProvider(provider) {
toolsProvider = provider;
return context;
diff --git a/lmstudio-plugin/test/privateNetworkSetting.test.mjs b/lmstudio-plugin/test/privateNetworkSetting.test.mjs
new file mode 100644
index 000000000..93ff5686b
--- /dev/null
+++ b/lmstudio-plugin/test/privateNetworkSetting.test.mjs
@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { createServer as createNetServer } from "node:net";
+import { after, before, test } from "node:test";
+
+import { main, readNetworkOptions } from "../dist/index.js";
+import { fetchUrl } from "../dist/tools/fetchUrl.js";
+import { researchUrl } from "../dist/tools/researchUrl.js";
+import { sharedBridge } from "../dist/util/bridgeClient.js";
+
+let toolsProvider;
+let configSchematicsSet;
+let server;
+let origin;
+let requests = 0;
+
+async function freePort() {
+ const probe = createNetServer();
+ probe.listen(0, "127.0.0.1");
+ await once(probe, "listening");
+ const address = probe.address();
+ const port = typeof address === "object" && address ? address.port : 0;
+ probe.close();
+ await once(probe, "close");
+ return port;
+}
+
+// Mirrors LM Studio's ToolsProviderController: it parses the chat's stored
+// plugin config, sent over the wire as { fields: [{ key, value }] }.
+function controller(fields) {
+ return {
+ getPluginConfig: (schematics) => schematics.parse({ fields }),
+ };
+}
+
+before(async () => {
+ process.env.WEBBRAIN_BRIDGE_PORT = String(await freePort());
+ const context = {
+ withConfigSchematics(schematics) {
+ configSchematicsSet = schematics;
+ return context;
+ },
+ withToolsProvider(provider) {
+ toolsProvider = provider;
+ return context;
+ },
+ };
+ await main(context);
+
+ server = createServer((req, res) => {
+ requests += 1;
+ if (req.url === "/to-metadata") {
+ res.writeHead(302, { Location: "http://169.254.169.254/latest/meta-data/" });
+ res.end();
+ return;
+ }
+ res.writeHead(200, { "Content-Type": "text/html" });
+ res.end(
+ "<html><head><title>Router</title></head><body><main>" +
+ "Local admin page. ".repeat(10) +
+ "</main></body></html>",
+ );
+ });
+ server.listen(0, "127.0.0.1");
+ await once(server, "listening");
+ origin = `http://127.0.0.1:${server.address().port}`;
+});
+
+after(async () => {
+ server?.close();
+ await sharedBridge().stop();
+});
+
+test("private network access is a user plugin setting that defaults to off", () => {
+ assert.ok(configSchematicsSet, "main() registers the plugin config schematics");
+ assert.equal(configSchematicsSet.parse({ fields: [] }).get("allowPrivateNetwork"), false);
+ assert.deepEqual(readNetworkOptions(controller([])), { allowPrivate: false });
+ assert.deepEqual(
+ readNetworkOptions(controller([{ key: "allowPrivateNetwork", value: true }])),
+ { allowPrivate: true },
+ );
+ assert.deepEqual(
+ readNetworkOptions({
+ getPluginConfig() {
+ throw new Error("config unavailable");
+ },
+ }),
+ { allowPrivate: false },
+ );
+});
+
+test("the HTTP tools do not offer allowPrivate to the model", async () => {
+ const tools = await toolsProvider(controller([{ key: "allowPrivateNetwork", value: true }]));
+ for (const name of ["fetch_url", "research_url"]) {
+ const registered = tools.find((registeredTool) => registeredTool.name === name);
+ assert.ok(registered, name);
+ assert.equal("allowPrivate" in registered.parametersSchema.shape, false, name);
+ }
+});
+
+test("a model-sent allowPrivate cannot reach a loopback service", async () => {
+ requests = 0;
+ // fetchUrl/researchUrl take the model's arguments as-is; a stray flag there is ignored.
+ const fetched = await fetchUrl({ url: `${origin}/`, allowPrivate: true });
+ assert.equal(fetched.success, false);
+ assert.match(fetched.error, /private network access is off/);
+
+ const researched = await researchUrl({ url: `${origin}/`, allowPrivate: true });
+ assert.equal(researched.success, false);
+ assert.match(researched.error, /private network access is off/);
+
+ assert.equal(requests, 0);
+});
+
+test("the user's setting opens loopback targets to both HTTP tools", async () => {
+ const network = readNetworkOptions(controller([{ key: "allowPrivateNetwork", value: true }]));
+
+ const fetched = await fetchUrl({ url: `${origin}/` }, network);
+ assert.equal(fetched.success, true);
+ assert.equal(fetched.title, "Router");
+
+ const researched = await researchUrl({ url: `${origin}/` }, network);
+ assert.equal(researched.success, true);
+ assert.match(researched.text, /Local admin page/);
+});
+
+test("cloud metadata endpoints stay blocked with private network access on", async () => {
+ requests = 0;
+ const network = { allowPrivate: true };
+ for (const url of [
+ "http://169.254.169.254/latest/meta-data/",
+ "http://2852039166/latest/meta-data/",
+ "http://[::ffff:169.254.169.254]/latest/meta-data/",
+ "http://[fd00:ec2::254]/latest/meta-data/",
+ "http://169.254.170.2/v2/credentials/",
+ "http://100.100.100.200/latest/meta-data/",
+ "http://metadata.google.internal/computeMetadata/v1/",
+ ]) {
+ const result = await fetchUrl({ url }, network);
+ assert.equal(result.success, false, url);
+ assert.match(result.error, /cloud metadata endpoint/, url);
+ }
+
+ const researched = await researchUrl(
+ { url: "http://169.254.169.254/latest/meta-data/" },
+ network,
+ );
+ assert.equal(researched.success, false);
+ assert.match(researched.error, /cloud metadata endpoint/);
+
+ const redirected = await fetchUrl({ url: `${origin}/to-metadata` }, network);
+ assert.equal(redirected.success, false);
+ assert.match(redirected.error, /cloud metadata endpoint/);
+ assert.equal(requests, 1);
+});
diff --git a/web/docs/lm-studio/index.html b/web/docs/lm-studio/index.html
index 5c7af9591..1b02aac95 100644
--- a/web/docs/lm-studio/index.html
+++ b/web/docs/lm-studio/index.html
@@ -47,7 +47,7 @@ lms dev --install</code></pre><p>See LM Studio’s current <a href="https://lmst
<section class="doc-section" id="lifecycle"><h2>Let continuing browser runs continue</h2><p><code>browser_task</code> waits for a result, but its timeout does not cancel work already running in the extension. Keep the returned <code>runId</code> and use the recovery tool that matches the state.</p><div class="status-strip" aria-label="LM Studio browser task statuses"><div class="status-item"><code>running</code><span>Poll with browser_status</span></div><div class="status-item waiting"><code>needs_user_input</code><span>Ask, then browser_respond</span></div><div class="status-item done"><code>completed</code><span>Result is ready</span></div><div class="status-item"><code>failed</code><span>Read the error and evidence</span></div><div class="status-item"><code>aborted</code><span>Stopped; earlier actions remain</span></div></div><ul><li>Do not start a duplicate <code>browser_task</code> after a timeout; poll the existing run.</li><li>Never invent an answer to a WebBrain clarification. Ask the human and forward their response verbatim.</li><li><code>browser_abort</code> stops future steps. It cannot undo a submitted form, sent message, or other completed action.</li></ul></section>
- <section class="doc-section" id="security"><h2>Keep the two trust surfaces clear</h2><ul><li><strong>Public HTTP runs in the local plugin process.</strong> <code>fetch_url</code> can send methods, headers, and bodies, so only request a mutation when you intend one.</li><li><strong>Private network targets are blocked by default.</strong> Loopback, RFC1918, link-local, cloud-metadata, and common intranet hostnames are refused. Use <code>allowPrivate: true</code> only for an explicit local-network task you understand.</li><li><strong>Redirects are rechecked.</strong> The plugin validates each destination and strips credential-like headers when a redirect crosses origins.</li><li><strong>The browser listener stays on loopback.</strong> Never forward or proxy port <code>17375</code>. The extension handshake identifies the client but is not shared-secret authentication; treat local software as trusted.</li><li><strong>Ask mode is the default.</strong> Use Act only when the requested outcome requires visible browser interaction, and keep the browser where you can stop unexpected behavior.</li><li><strong>The LM Studio model sees tool results.</strong> A browser run also sends task context through the active provider configured inside WebBrain. Choose both model boundaries deliberately.</li></ul><p>For the implementation-level details and residual DNS-rebinding limitation, read the plugin’s <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">safety notes</a>.</p></section>
+ <section class="doc-section" id="security"><h2>Keep the two trust surfaces clear</h2><ul><li><strong>Public HTTP runs in the local plugin process.</strong> <code>fetch_url</code> can send methods, headers, and bodies, so only request a mutation when you intend one.</li><li><strong>Private network targets are blocked by default.</strong> Loopback, RFC1918, link-local, cloud-metadata, and common intranet hostnames are refused. To reach localhost or your LAN, turn on <strong>Allow private network access</strong> in the plugin’s settings in LM Studio, only in a chat that needs it. The model cannot turn it on, and cloud-metadata endpoints stay blocked even when it is on.</li><li><strong>Redirects are rechecked.</strong> The plugin validates each destination and strips credential-like headers when a redirect crosses origins.</li><li><strong>The browser listener stays on loopback.</strong> Never forward or proxy port <code>17375</code>. The extension handshake identifies the client but is not shared-secret authentication; treat local software as trusted.</li><li><strong>Ask mode is the default.</strong> Use Act only when the requested outcome requires visible browser interaction, and keep the browser where you can stop unexpected behavior.</li><li><strong>The LM Studio model sees tool results.</strong> A browser run also sends task context through the active provider configured inside WebBrain. Choose both model boundaries deliberately.</li></ul><p>For the implementation-level details and residual DNS-rebinding limitation, read the plugin’s <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">safety notes</a>.</p></section>
<section class="doc-section" id="troubleshooting"><h2>Troubleshooting by symptom</h2><div class="table-wrap"><table><thead><tr><th>Symptom</th><th>What it usually means</th><th>Fix</th></tr></thead><tbody><tr><td>The tools do not appear</td><td>The plugin is not enabled for this chat, or the selected model cannot call tools.</td><td>Enable <strong>webbrain/web-tools</strong> beside the chat input and select a tool-capable model.</td></tr><tr><td><code>browser_status</code> reports disconnected</td><td>The plugin is available, but the WebBrain extension has not attached.</td><td>Use Chromium, enable MCP, and enter exactly <code>ws://127.0.0.1:17375/extension</code>.</td></tr><tr><td>The listener cannot start or reports an address conflict</td><td>Another plugin instance or process already owns port <code>17375</code>.</td><td>Close the duplicate instance, then reload the plugin. Inspect first with <code>lsof -nP -iTCP:17375 -sTCP:LISTEN</code>.</td></tr><tr><td>A public page is empty</td><td>The page renders with JavaScript or hides content behind login.</td><td>If <code>spaSuspected</code> is true, connect the extension and use <code>browser_task</code>.</td></tr><tr><td>The task timed out but the browser is still moving</td><td>The wait budget ended without cancelling the WebBrain run.</td><td>Call <code>browser_status</code> with the returned <code>runId</code>, or <code>browser_abort</code> if you want it stopped.</td></tr><tr><td>Firefox never connects</td><td>Firefox has no offscreen-document bridge runtime.</td><td>Use a Chromium browser for browser tools. The two public HTTP tools remain usable without any extension.</td></tr><tr><td>MCP or WebBrain Cloud disconnected</td><td>The LM Studio URL replaced the extension’s one bridge destination.</td><td>Switch Settings back to port <code>17374</code> for MCP or <code>17373</code> for WebBrain Cloud when finished.</td></tr></tbody></table></div></section>
diff --git a/web/docs/zh/lm-studio/index.html b/web/docs/zh/lm-studio/index.html
index 634924b6d..2f2abaa30 100644
--- a/web/docs/zh/lm-studio/index.html
+++ b/web/docs/zh/lm-studio/index.html
@@ -48,7 +48,7 @@ lms dev --install</code></pre><p>参阅 LM Studio 的 <a href="https://lmstudio.
<section class="doc-section" id="lifecycle"><h2>让正在进行的浏览器运行继续</h2><p><code>browser_task</code> 会等待结果,但其超时不会取消扩展中已在运行的工作。保留返回的 <code>runId</code>,并使用与状态匹配的恢复工具。</p><div class="status-strip" aria-label="LM Studio 浏览器任务状态"><div class="status-item"><code>running</code><span>使用 browser_status 轮询</span></div><div class="status-item waiting"><code>needs_user_input</code><span>提问,然后使用 browser_respond</span></div><div class="status-item done"><code>completed</code><span>结果已就绪</span></div><div class="status-item"><code>failed</code><span>查看错误和证据</span></div><div class="status-item"><code>aborted</code><span>已停止;之前的操作仍然有效</span></div></div><ul><li>超时后不要启动重复的 <code>browser_task</code>;轮询现有运行。</li><li>永远不要为 WebBrain 的澄清问题编造答案。询问用户并逐字转发他们的回答。</li><li><code>browser_abort</code> 停止后续步骤。它无法撤销已提交的表单、已发送的消息或其他已完成的操作。</li></ul></section>
- <section class="doc-section" id="security"><h2>保持两个信任面清晰</h2><ul><li><strong>公开 HTTP 在本地插件进程中运行。</strong><code>fetch_url</code> 可以发送方法、请求头和请求体,因此仅在你有意时才请求修改操作。</li><li><strong>默认阻止私有网络目标。</strong>本地回环、RFC1918、链路本地、云元数据和常见内网主机名均被拒绝。仅在你理解的明确本地网络任务中使用 <code>allowPrivate: true</code>。</li><li><strong>重定向会被重新检查。</strong>插件会验证每个目标,并在重定向跨域时去除类似凭据的请求头。</li><li><strong>浏览器监听器保持在本地回环。</strong>永远不要转发或代理端口 <code>17375</code>。扩展握手可以识别客户端但不是共享密钥认证;将本地软件视为可信软件。</li><li><strong>Ask 模式是默认选项。</strong>仅在请求的结果需要可见浏览器交互时使用 Act,并保持浏览器在你可以停止意外行为的范围内。</li><li><strong>LM Studio 模型可以看到工具结果。</strong>浏览器运行还会通过 WebBrain 内配置的活跃提供商发送任务上下文。请慎重选择两个模型的边界。</li></ul><p>有关实现级别的细节和残余 DNS 重绑定限制,请阅读插件的 <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">安全说明</a>。</p></section>
+ <section class="doc-section" id="security"><h2>保持两个信任面清晰</h2><ul><li><strong>公开 HTTP 在本地插件进程中运行。</strong><code>fetch_url</code> 可以发送方法、请求头和请求体,因此仅在你有意时才请求修改操作。</li><li><strong>默认阻止私有网络目标。</strong>本地回环、RFC1918、链路本地、云元数据和常见内网主机名均被拒绝。如需访问 localhost 或局域网,请仅在需要的对话中,于 LM Studio 的插件设置里打开 <strong>Allow private network access</strong>。模型无法自行打开该设置,并且即使打开,云元数据端点仍会被阻止。</li><li><strong>重定向会被重新检查。</strong>插件会验证每个目标,并在重定向跨域时去除类似凭据的请求头。</li><li><strong>浏览器监听器保持在本地回环。</strong>永远不要转发或代理端口 <code>17375</code>。扩展握手可以识别客户端但不是共享密钥认证;将本地软件视为可信软件。</li><li><strong>Ask 模式是默认选项。</strong>仅在请求的结果需要可见浏览器交互时使用 Act,并保持浏览器在你可以停止意外行为的范围内。</li><li><strong>LM Studio 模型可以看到工具结果。</strong>浏览器运行还会通过 WebBrain 内配置的活跃提供商发送任务上下文。请慎重选择两个模型的边界。</li></ul><p>有关实现级别的细节和残余 DNS 重绑定限制,请阅读插件的 <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">安全说明</a>。</p></section>
<section class="doc-section" id="troubleshooting"><h2>按症状排查</h2><div class="table-wrap"><table><thead><tr><th>症状</th><th>通常含义</th><th>解决方法</th></tr></thead><tbody><tr><td>工具没有出现</td><td>此聊天未启用插件,或所选模型无法调用工具。</td><td>在聊天输入旁启用 <strong>webbrain/web-tools</strong>,并选择支持工具的模型。</td></tr><tr><td><code>browser_status</code> 报告已断开连接</td><td>插件可用,但 WebBrain 扩展尚未连接。</td><td>使用 Chromium,启用云桥接,并精确输入 <code>ws://127.0.0.1:17375/extension</code>。</td></tr><tr><td>监听器无法启动或报告地址冲突</td><td>另一个插件实例或进程已占用端口 <code>17375</code>。</td><td>关闭重复实例,然后重新加载插件。先使用 <code>lsof -nP -iTCP:17375 -sTCP:LISTEN</code> 检查。</td></tr><tr><td>公开页面为空</td><td>页面使用 JavaScript 渲染或将内容隐藏在登录后。</td><td>如果 <code>spaSuspected</code> 为 true,连接扩展并使用 <code>browser_task</code>。</td></tr><tr><td>任务超时但浏览器仍在操作</td><td>等待预算已用尽,但 WebBrain 运行未被取消。</td><td>使用返回的 <code>runId</code> 调用 <code>browser_status</code>,或在需要停止时使用 <code>browser_abort</code>。</td></tr><tr><td>Firefox 始终无法连接</td><td>Firefox 没有离屏文档桥接运行时。</td><td>使用 Chromium 浏览器进行浏览器工具操作。两个公开 HTTP 工具无需扩展即可使用。</td></tr><tr><td>MCP 或 WebBrain Cloud 已断开连接</td><td>LM Studio URL 替换了扩展的单个桥接目标。</td><td>完成后将设置切换回端口 <code>17374</code>(MCP)或 <code>17373</code>(WebBrain Cloud)。</td></tr></tbody></table></div></section>