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
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.mdindex 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 rebindingdiff --git a/lmstudio-plugin/package.json b/lmstudio-plugin/package.jsonindex 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.tsindex 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.tsindex 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.tsindex 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<ResearchUrlResconst 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.tsindex 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.tsindex 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.mjsindex 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.mjsnew file mode 100644index 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.htmlindex 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.htmlindex 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>