Skip to content

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

Merge origin/main into fix-529 and unify DNS pinning with private network setting

Emre Sokullu5e7f6c457a30
diff --cc lmstudio-plugin/README.md
index 0d370309a,aad5301a4..34d09ce31
--- a/lmstudio-plugin/README.md
+++ b/lmstudio-plugin/README.md
@@@ -240,37 -244,16 +244,32 @@@ Everything below concerns `fetch_url`
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
-
- An attacker controlling a domain with TTL=0 can return a public IP
- when our guard runs `dns.lookup` and a private IP a moment later when
- `fetch` connects. Closing this fully requires pinning the resolved
- IP via a custom `undici` Agent's `connect.lookup` hook so the
- connection uses the exact address we validated. Tracked as a
- follow-up. If you're running this on a cloud VM with sensitive
- instance-metadata endpoints, use a network policy that blocks
- `169.254.169.254` outbound rather than relying solely on this
- plugin's checks.
+ ### Not a sandbox
+
+ These checks only see the address ranges they know about. If you're
+ running this on a cloud VM with sensitive instance-metadata
+ endpoints, use a network policy that blocks `169.254.169.254`
+ outbound rather than relying solely on this plugin's checks.
## License
diff --cc lmstudio-plugin/package.json
index 394081519,98adaa2f9..55ca8f0c3
--- a/lmstudio-plugin/package.json
+++ b/lmstudio-plugin/package.json
@@@ -15,7 -15,7 +15,7 @@@
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
- "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs test/toolParameters.test.mjs test/privateNetworkSetting.test.mjs",
- "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs test/toolParameters.test.mjs test/safeFetch.test.mjs",
++ "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs test/toolParameters.test.mjs test/safeFetch.test.mjs test/privateNetworkSetting.test.mjs",
"clean": "rm -rf dist"
},
"keywords": [
diff --cc lmstudio-plugin/src/util/safeFetch.ts
index e92713de4,e3379b16c..2777488f7
--- a/lmstudio-plugin/src/util/safeFetch.ts
+++ b/lmstudio-plugin/src/util/safeFetch.ts
@@@ -29,14 -31,16 +31,18 @@@
* open-redirect chain.
*/
- import { lookup as dnsLookup } from "node:dns/promises";
- import { isIP } from "node:net";
+ import { lookup as dnsLookup, type LookupAddress } from "node:dns";
+ import * as http from "node:http";
+ import * as https from "node:https";
+ import { isIP, type LookupFunction } from "node:net";
+ import { pipeline, Readable } from "node:stream";
+ import * as zlib from "node:zlib";
import {
assertSafeUrl,
+ isCloudMetadataHost,
isPrivateIpv4,
isPrivateIpv6,
+ PRIVATE_NETWORK_HINT,
type UrlGuardOptions,
} from "./urlGuard.js";
@@@ -70,71 -74,239 +76,255 @@@ function stripCrossOriginHeaders
}
/**
- * Resolve a hostname's A/AAAA records and reject if any address is in
- * a private range. Literal IPs skip DNS and are classified directly.
+ * Reject if any resolved address is in a private range.
*
- * Why we check ALL returned addresses rather than just the first one
- * 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 })`.
+ * Why we check ALL returned addresses rather than just the first one:
+ * Node's happy-eyeballs connect may try any of them, and it is
+ * defense-in-depth against accidentally-misconfigured dual-stack hosts.
+ *
- * With allowPrivate the lookup still runs, because a hostname that
++ * With allowPrivate the check still runs, because a hostname that
+ * resolves to a cloud metadata address stays blocked.
*/
- async function assertHostnameDoesNotResolveToPrivate(
- parsed: URL,
- opts: UrlGuardOptions,
- ): Promise<void> {
- // Strip the [..] wrapper IPv6 URL syntax adds.
- let host = parsed.hostname;
- if (host.startsWith("[") && host.endsWith("]")) {
- host = host.slice(1, -1);
- }
-
- // 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 (!opts.allowPrivate && (literal === 4 ? isPrivateIpv4(host) : isPrivateIpv6(host))) {
- throw new Error(
- `Refusing private IPv${literal} ${host} — ${PRIVATE_NETWORK_HINT}`,
- );
-function assertAddressesArePublic(host: string, addresses: LookupAddress[]): void {
++function assertAddressesArePublic(host: string, addresses: LookupAddress[], opts: UrlGuardOptions = {}): void {
+ for (const { address, family } of addresses) {
- if (family === 4 && isPrivateIpv4(address)) {
- throw new Error(
- `Refusing ${host} — resolves to private IPv4 ${address}. Set allowPrivate to opt in.`,
- );
++ if (!opts.allowPrivate) {
++ if (family === 4 && isPrivateIpv4(address)) {
++ throw new Error(
++ `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}; ${PRIVATE_NETWORK_HINT}`,
++ );
++ }
}
- if (isCloudMetadataHost(host)) {
- if (family === 6 && isPrivateIpv6(address)) {
++ if (isCloudMetadataHost(address)) {
throw new Error(
- `Refusing cloud metadata endpoint ${host} — blocked even with private network access on.`,
- `Refusing ${host} — resolves to private IPv6 ${address}. Set allowPrivate to opt in.`,
++ `Refusing ${host} — resolves to cloud metadata endpoint ${address}, which stays blocked even with private network access on.`,
);
}
- return;
}
+ }
- let addresses: Array<{ address: string; family: number }>;
- try {
- addresses = await dnsLookup(host, { all: true });
- } catch (e) {
- // Resolution failure isn't a security signal — let the subsequent
- // fetch surface a clean error. Don't fail the guard here.
- return;
+ /**
+ * Literal-IP hosts never reach `guardedLookup`: Node connects to them
+ * directly without calling the socket's `lookup` hook. Classify them here
+ * on every hop so this layer does not depend on `assertSafeUrl` alone.
+ */
-function assertLiteralIpIsPublic(url: URL): void {
++function assertLiteralIpIsPublic(url: URL, opts: UrlGuardOptions = {}): void {
+ let host = url.hostname;
+ if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+ const family = isIP(host);
- if (family === 4 ? isPrivateIpv4(host) : family === 6 && isPrivateIpv6(host)) {
++ if (family === 0) return;
++ if (!opts.allowPrivate && (family === 4 ? isPrivateIpv4(host) : isPrivateIpv6(host))) {
+ throw new Error(
- `Refusing private IPv${family} ${host} — set allowPrivate to opt in.`,
++ `Refusing private IPv${family} ${host} — ${PRIVATE_NETWORK_HINT}`,
++ );
+ }
++ if (isCloudMetadataHost(host)) {
++ throw new Error(
++ `Refusing cloud metadata endpoint ${host} — blocked even with private network access on.`,
+ );
+ }
+ }
- 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.`,
- );
+ /**
+ * `lookup` hook for the request socket. Node calls it when connecting
+ * and dials only the addresses it hands back, so the check and the use
+ * are the same resolution — resolving first and then letting the HTTP
+ * client resolve the name again would let a TTL=0 record answer public
+ * to the check and private to the connection. Literal-IP hosts never
+ * reach a lookup; `assertLiteralIpIsPublic` covers them.
+ */
-const guardedLookup: LookupFunction = (hostname, options, callback) => {
- dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
- if (err) {
- callback(err, "");
- return;
- }
- try {
- if (addresses.length === 0) throw new Error(`No addresses found for ${hostname}`);
- assertAddressesArePublic(hostname, addresses);
- } catch (e) {
- callback(e as NodeJS.ErrnoException, "");
- return;
- }
- if (options.all) callback(null, addresses);
- else callback(null, addresses[0]!.address, addresses[0]!.family);
- });
-};
++function createGuardedLookup(opts: UrlGuardOptions): LookupFunction {
++ return (hostname, options, callback) => {
++ dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
++ if (err) {
++ callback(err, "");
++ return;
++ }
++ try {
++ if (addresses.length === 0) throw new Error(`No addresses found for ${hostname}`);
++ assertAddressesArePublic(hostname, addresses, opts);
++ } catch (e) {
++ callback(e as NodeJS.ErrnoException, "");
++ return;
++ }
++ if (options.all) callback(null, addresses);
++ else callback(null, addresses[0]!.address, addresses[0]!.family);
++ });
++ };
++}
+
+ /** Statuses whose Response must have a null body (Fetch standard). */
+ const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+ /** Lenient flushing, as fetch uses, so a truncated stream still yields what decoded. */
+ const ZLIB_OPTIONS = {
+ flush: zlib.constants.Z_SYNC_FLUSH,
+ finishFlush: zlib.constants.Z_SYNC_FLUSH,
+ };
+ const BROTLI_OPTIONS = {
+ flush: zlib.constants.BROTLI_OPERATION_FLUSH,
+ finishFlush: zlib.constants.BROTLI_OPERATION_FLUSH,
+ };
+
+ function abortReason(signal: AbortSignal): Error {
+ return signal.reason ??
+ Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
+ }
+
+ interface HopInit {
+ method: string;
+ headers: Record<string, string>;
+ body: string | undefined;
+ signal?: AbortSignal;
+ }
+
+ /**
+ * Headers fetch adds on its own. Without them some servers refuse the
+ * request (no User-Agent) or skip compression. Caller values win.
+ */
+ function withFetchDefaultHeaders(
+ headers: Record<string, string>,
+ body: string | undefined,
+ ): Record<string, string> {
+ const out = { ...headers };
+ const present = new Set(Object.keys(out).map((k) => k.toLowerCase()));
+ const defaults: Array<[string, string]> = [
+ ["accept", "*/*"],
+ ["accept-encoding", "gzip, deflate, br"],
+ ["user-agent", "node"],
+ ];
+ if (body !== undefined) defaults.push(["content-type", "text/plain;charset=UTF-8"]);
+ for (const [k, v] of defaults) {
+ if (!present.has(k)) out[k] = v;
+ }
+ return out;
+ }
+
+ /**
+ * Undo Content-Encoding like fetch: gzip / deflate / br, last-applied
+ * first. An unknown coding leaves the body as it came.
+ */
+ function decodeBody(incoming: http.IncomingMessage): Readable {
+ const codings = (incoming.headers["content-encoding"] || "")
+ .toLowerCase()
+ .split(",")
+ .map((c) => c.trim())
+ .filter(Boolean)
+ .reverse();
+ if (codings.length === 0) return incoming;
+ const decoders: NodeJS.ReadWriteStream[] = [];
+ for (const coding of codings) {
+ if (coding === "gzip" || coding === "x-gzip") decoders.push(zlib.createGunzip(ZLIB_OPTIONS));
+ else if (coding === "deflate") decoders.push(zlib.createInflate(ZLIB_OPTIONS));
+ else if (coding === "br") decoders.push(zlib.createBrotliDecompress(BROTLI_OPTIONS));
+ else return incoming;
+ }
+ // pipeline destroys every stage when one fails or the last is
+ // destroyed (e.g. readBodyCapped cancelling), which closes the socket.
+ return pipeline([incoming, ...decoders], () => {}) as unknown as Readable;
+ }
+
+ /**
+ * Send one request (no redirect following) over a connection whose
+ * address went through `guardedLookup`, and wrap the reply in a
+ * standard `Response` with `url` set, as fetch would return it.
+ */
+ function pinnedFetch(url: URL, init: HopInit, opts: UrlGuardOptions): Promise<Response> {
+ return new Promise((resolve, reject) => {
+ const { signal } = init;
+ if (url.username || url.password) {
+ reject(new TypeError(
+ `Request cannot be constructed from a URL that includes credentials: ${url}`,
+ ));
+ return;
}
- if (opts.allowPrivate) continue;
- if (family === 4 && isPrivateIpv4(address)) {
- throw new Error(
- `Refusing ${host} — resolves to private IPv4 ${address}; ${PRIVATE_NETWORK_HINT}`,
- );
+ if (signal?.aborted) {
+ reject(abortReason(signal));
+ return;
}
- if (family === 6 && isPrivateIpv6(address)) {
- throw new Error(
- `Refusing ${host} — resolves to private IPv6 ${address}; ${PRIVATE_NETWORK_HINT}`,
- );
+
- if (!opts.allowPrivate) {
- try { assertLiteralIpIsPublic(url); } catch (e) { reject(e); return; }
- }
++ try { assertLiteralIpIsPublic(url, opts); } catch (e) { reject(e); return; }
+
+ let req: http.ClientRequest;
+ try {
+ req = (url.protocol === "https:" ? https : http).request(url, {
+ method: init.method,
+ headers: withFetchDefaultHeaders(init.headers, init.body),
+ // A fresh connection per request: a pooled keep-alive socket was
+ // resolved for whichever request opened it (possibly one with
+ // allowPrivate), so reusing it would skip this request's lookup.
+ agent: false,
- ...(opts.allowPrivate ? {} : { lookup: guardedLookup }),
++ lookup: createGuardedLookup(opts),
+ });
+ } catch (e) {
+ reject(e);
+ return;
+ }
+
+ const onAbort = () => req.destroy(abortReason(signal!));
+ signal?.addEventListener("abort", onAbort, { once: true });
+ // Kept for the request's lifetime: a late socket error with no
+ // listener would crash the plugin process.
+ req.on("error", (e) => {
+ signal?.removeEventListener("abort", onAbort);
+ reject(e);
+ });
+ req.once("response", (incoming) => {
+ signal?.removeEventListener("abort", onAbort);
+ try {
+ resolve(toFetchResponse(incoming, url, init.method, signal));
+ } catch (e) {
+ incoming.destroy();
+ reject(e);
+ }
+ });
+ req.end(init.body);
+ });
+ }
+
+ function toFetchResponse(
+ incoming: http.IncomingMessage,
+ url: URL,
+ method: string,
+ signal: AbortSignal | undefined,
+ ): Response {
+ const status = incoming.statusCode ?? 0;
+ if (status < 200 || status > 599) {
+ throw new Error(`Unsupported HTTP status ${status} from ${url.origin}`);
+ }
+ const headers = new Headers();
+ for (let i = 0; i + 1 < incoming.rawHeaders.length; i += 2) {
+ headers.append(incoming.rawHeaders[i]!, incoming.rawHeaders[i + 1]!);
+ }
+
+ let body: ReadableStream<Uint8Array> | null = null;
+ if (method === "HEAD" || NULL_BODY_STATUSES.has(status)) {
+ incoming.on("error", () => {});
+ incoming.resume();
+ } else {
+ const decoded = decodeBody(incoming);
+ if (signal) {
+ // Aborting mid-body errors the stream with the abort reason, as fetch does.
+ const onAbort = () => decoded.destroy(abortReason(signal));
+ signal.addEventListener("abort", onAbort, { once: true });
+ decoded.once("close", () => signal.removeEventListener("abort", onAbort));
}
+ body = Readable.toWeb(decoded) as unknown as ReadableStream<Uint8Array>;
}
+
+ // Response's constructor rejects reason phrases fetch would accept;
+ // the phrase is cosmetic.
+ const statusMessage = incoming.statusMessage ?? "";
+ const statusText = /^[\t\x20-\x7e\x80-\xff]*$/.test(statusMessage) ? statusMessage : "";
+ const res = new Response(body, { status, statusText, headers });
+ // Only fetch() can set Response.url; callers report it as the final URL.
+ const finalUrl = new URL(url);
+ finalUrl.hash = "";
+ Object.defineProperty(res, "url", { value: finalUrl.toString() });
+ return res;
}
export interface SafeFetchInit {
diff --cc lmstudio-plugin/src/util/urlGuard.ts
index 42c1e9700,c5ec22ceb..bfe5b78dc
--- a/lmstudio-plugin/src/util/urlGuard.ts
+++ b/lmstudio-plugin/src/util/urlGuard.ts
@@@ -16,25 -16,21 +16,22 @@@
* including IPv6 forms that embed a private IPv4 (IPv4-mapped,
* NAT64, 6to4, Teredo)
* - 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`
- * because it requires `node:dns` and is awaited once per redirect hop
- * inside the `safeFetch` wrapper. That additional layer closes the case
+ * The DNS-resolution-aware check (`guardedLookup`) lives in
+ * `safeFetch.ts` because it requires `node:dns`. It runs as the request
+ * socket's `lookup` hook on every hop, so the connection can only use
+ * addresses that passed it. That additional layer closes the case
* where a public-looking hostname has an A record pointing into
* RFC1918 / loopback / link-local space, e.g. `attacker.example A
- * 127.0.0.1`. `isPrivateIpv4` / `isPrivateIpv6` are exported so the
- * resolver-side check reuses the same range definitions.
+ * 127.0.0.1`, and DNS rebinding (a TTL=0 record answering public to a
+ * check and private to the connection), because there is no separate
+ * check to answer. `isPrivateIpv4` / `isPrivateIpv6` are exported so
+ * the resolver-side check reuses the same range definitions.
*
- * Residual gap: DNS rebinding. An attacker controlling a domain with
- * TTL=0 can return a public IP at the time of the guard check and a
- * private IP at the time `fetch` connects. Closing this fully requires
- * pinning the resolved IP via a custom undici Agent + `lookup` hook —
- * tracked as a follow-up. The current layered defense (sync check +
- * DNS check + per-redirect re-validation) raises the bar enough to
- * stop drive-by SSRF from open redirects and naive hostname tricks
- * but is NOT a hardened sandbox.
+ * The layered defense (sync check + connect-time DNS check +
+ * per-redirect re-validation) stops drive-by SSRF from open redirects,
+ * naive hostname tricks and rebinding, but is NOT a hardened sandbox.
*
* To opt-out (e.g. you really do want to point this at your intranet)
* call assertSafeUrl(url, { allowPrivate: true }) and pass the same
diff --cc web/docs/lm-studio/index.html
index 1b02aac95,16ea875c8..5100c22d3
--- a/web/docs/lm-studio/index.html
+++ b/web/docs/lm-studio/index.html
@@@ -47,7 -47,7 +47,7 @@@ lms dev --install</code></pre><p>See L
<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. 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="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, including how each connection is pinned to the address that was checked, 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, including how each connection is pinned to the address that was checked, 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 --cc web/docs/zh/lm-studio/index.html
index 2f2abaa30,d8c2bd4fd..7655c1b41
--- a/web/docs/zh/lm-studio/index.html
+++ b/web/docs/zh/lm-studio/index.html
@@@ -48,7 -48,7 +48,7 @@@ lms dev --install</code></pre><p>参�
<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、链路本地、云元数据和常见内网主机名均被拒绝。如需访问 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="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>有关实现级别的细节(包括每个连接如何固定到已检查的地址),请阅读插件的 <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>有关实现级别的细节(包括每个连接如何固定到已检查的地址),请阅读插件的 <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>