feat(web): enforce localhost-only binding; expand loopback origin allow-list (#1796)

Closes #1795.

Enforce localhost-only binding in code (the "never 0.0.0.0" rule was only a spec note): refuse an all-interfaces HOST — across every spelling the OS binds as the wildcard (inet_aton decimal/octal/hex, IPv6, IPv4-mapped, zone-scoped, IDNA/Unicode) — unless DANGEROUSLY_BIND_ALL_INTERFACES=true (Docker's sanctioned opt-in). Fixes the reported stdio-connect 403 by expanding the default loopback origin allow-list to all three interchangeable forms.

Hardening surfaced across an extended review: closes an IDNA/fullwidth wildcard bypass, a blank-ALLOWED_ORIGINS fail-open, and the CLI/TUI OAuth-callback wildcard bind (loopback-only now, RFC 8252); canonicalizes the origin allow-list the way a browser does; derives frame-ancestors from the real embedder list (IPv6-literal exclusion verified in headless Chromium); strictPort on all three bind points; and preserves the CLI exit-code map + JSON envelope through the mcp-inspector --cli launcher path. Shared host normalization lives in core/node/hostUrl.ts. Docs + tests + smokes throughout.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Cliff Hall 2026-07-26 22:15:10 -04:00 • committed by GitHub
commit cea22d86b8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 1610 additions and 86 deletions

View file

@ -16,7 +16,8 @@ The `server/` directory holds the Node-only backend:
- **`vite-hono-plugin.ts`** — mounts the Hono `/api/*` middleware onto the Vite dev server (so `npm run dev` has a live backend).
- **`server.ts`** — the standalone Hono production server (serves `dist/` + `/api/*`).
- **`run-web.ts`** / **`start-vite-dev-server.ts`** — entry points the launcher calls for prod `--web` and `--web --dev`.
- **`web-server-config.ts`** — env parsing, the `GET /api/config` payload, the startup banner.
- **`web-server-config.ts`** — env parsing, the `GET /api/config` payload, the startup banner, the default origin allow-list.
- **`resolve-bind-host.ts`** — the shared bind-host guard (refuses an all-interfaces `HOST` unless `DANGEROUSLY_BIND_ALL_INTERFACES`), used by both bind points (`web-server-config.ts` + `vite.config.ts`); see [Host binding & the origin allow-list](#host-binding--the-origin-allow-list).
- **`inject-auth-token.ts`** — embeds the API token into the served `index.html` (see [Auth token](#auth-token)).
- **`sandbox-controller.ts`** — the MCP Apps sandbox HTTP server; **`ensure-web-build.ts`** — builds `dist/` on demand for prod `--web`; **`vite-base-config.ts`** — shared `optimizeDeps` exclusions.
- **`browser-externalized-builtin-gate.ts`** — Vite-agnostic build-gate logic that fails `vite build` when a Node built-in reaches the browser bundle (#1769); the thin Vite plugin wiring lives in `vite.config.ts`. It sits under `server/` (rather than `src/`) as the home for Node-only, build-time tooling — it's imported by the Vite config, never by the browser — alongside the other `vite-*` config helpers here.
@ -159,6 +160,26 @@ Storybook is first-class here because the components are presentational — each
The dev/prod backend guards every `/api/*` route with `x-mcp-remote-auth: Bearer <MCP_INSPECTOR_API_TOKEN>`. The browser recovers the token, in priority order (see `App.tsx` `getAuthToken()`): the `window.__INSPECTOR_API_TOKEN__` global injected into `index.html` on every page load (`server/inject-auth-token.ts`), then a `?MCP_INSPECTOR_API_TOKEN=…` query param, then `sessionStorage`. Injection is a no-op when auth is disabled (`DANGEROUSLY_OMIT_AUTH`). See the root [AGENTS.md](../../AGENTS.md) for the full rationale.
## Host binding & the origin allow-list
Both the prod backend (`server/web-server-config.ts`) and the dev Vite server (`vite.config.ts`) resolve their bind host through one shared guard, `server/resolve-bind-host.ts`. It binds `localhost` by default and **refuses an all-interfaces host** (`0.0.0.0`, `::`, empty, or any equivalent spelling — `0`, `0x0`, `0.0`, `::0`, `::ffff:0.0.0.0`, … are all folded to the wildcard and refused) — which would expose the process-spawning backend to the whole network, the exposure DNS-rebinding attacks target — unless `DANGEROUSLY_BIND_ALL_INTERFACES=true` is set. The Docker image sets that flag (a container must bind `0.0.0.0` to be reachable through `-p`); a bare `HOST=0.0.0.0` anywhere else exits with an actionable error.
The backend's `/api/*` routes also enforce an **origin allow-list** (`allowedOrigins`) as DNS-rebinding protection. When left to default on a loopback host, it expands to all three interchangeable loopback origin forms for the port — `http://localhost:PORT`, `http://127.0.0.1:PORT`, and `http://[::1]:PORT` — because `localhost` resolves to either IPv4 or IPv6 loopback and Node/Vite may bind the IPv6 form, so the browser can legitimately arrive at `http://[::1]:PORT`. Set `ALLOWED_ORIGINS` (comma-separated) to override; entries are canonicalized (`new URL(o).origin`), so a trailing slash / uppercase host / explicit `:80` still match. **Each entry must include the scheme** — `http://localhost:6274`, not `localhost:6274` (a scheme-less value is dropped with a warning). `ALLOWED_ORIGINS` **replaces** the default list (it does not merge), so **list every origin you'll browse from, including the loopback forms** you still want (`http://localhost:PORT`, `http://127.0.0.1:PORT`, `http://[::1]:PORT`) — otherwise local access stops working. A blank `ALLOWED_ORIGINS` does **not** disable the check — it falls back to the default (fail closed); there is no env knob to turn origin validation off.
### Hosting on a network
The guard blocks only the **wildcard** all-interfaces addresses. Binding a **specific** IP or hostname is allowed with no opt-in — that's a single, deliberate exposure, unlike the wildcard which binds every interface at once (the pattern DNS-rebinding exploits). To serve the Inspector on a LAN or the internet:
- **Bind a specific address.** `HOST=192.168.1.50` (a LAN IP) or a public IP works directly: the default origin allow-list follows the bind host, so `allowedOrigins` becomes `http://<that-host>:PORT` and a browser hitting that address is accepted with no extra config. (The host is canonicalized the way a browser is — so `HOST=127.1` advertises `http://127.0.0.1:PORT`, an IPv6 bind host is bracketed as `http://[2001:db8::1]:PORT`, and the port is dropped when it's the http default `:80` — matching what the browser sends.)
- **Behind TLS or a reverse proxy**, the browser's `Origin` becomes the public origin (e.g. `https://inspector.example.com`, often without a port), which won't match the auto-derived `http://<bind-host>:PORT`. Set `ALLOWED_ORIGINS` to the real public origin(s): `ALLOWED_ORIGINS=https://inspector.example.com`.
- **Using the `0.0.0.0` wildcard** (opt-in via `DANGEROUSLY_BIND_ALL_INTERFACES=true`, as the Docker image does): a wildcard bind also serves loopback, so the default allow-list is the loopback trio plus the canonical wildcard origins (`http://0.0.0.0:PORT`, `http://[::]:PORT`), and **local access works out of the box** — `docker run -p 6274:6274` browsed at `http://localhost:6274` connects with no extra config. Reaching it at a **non-loopback** address (a LAN IP, a public hostname) still needs `ALLOWED_ORIGINS` — but since that **replaces** the default, keep the loopback forms in the list if you also browse locally: `ALLOWED_ORIGINS=http://localhost:PORT,http://127.0.0.1:PORT,http://192.168.1.50:PORT,https://inspector.example.com`.
The bind-host guard and the `ALLOWED_ORIGINS` allow-list apply to both the prod server and `--dev`. Note that in **`--dev`** the Vite dev server _additionally_ enforces its own `server.allowedHosts` Host-header check, whose default accepts loopback and IP-literal hosts. The host you **bind** is auto-allowed (Vite adds the resolved `server.host` — which this config sets from `HOST` — to the allow-list), so `HOST=<hostname>` works out of the box under `--dev` too. What needs an explicit `server.allowedHosts` entry is reaching the dev server at a **different** name than the one bound — e.g. a wildcard bind reached by hostname, or a reverse-proxy domain. For those, prefer the prod server (`mcp-inspector --web`) or add the host to `server.allowedHosts`.
**MCP Apps caveats.** The MCP Apps sandbox runs on a **separate** port (`MCP_SANDBOX_PORT`, dynamic by default). For the Apps tab to work off loopback, that sandbox port must be independently reachable from the browser — pin it with `MCP_SANDBOX_PORT` and expose/forward it too (the Docker image `EXPOSE`s only `6274`). (Under a `0.0.0.0` wildcard bind the sandbox URL is advertised as `localhost`, which is reachable — a wildcard bind serves loopback — so only the port needs handling.) Also note the sandbox iframe is gated by a `frame-ancestors` CSP, and **a bracketed IPv6 literal is not a valid CSP host-source** — so MCP Apps requires browsing the app at a name or IPv4 (`localhost`, `127.0.0.1`, a hostname, a LAN IPv4), **not** a bare `http://[::1]:…` address. Finally, the sandbox URL is always `http://` — so **behind TLS** (an `https://` app page) the browser blocks the `http://…/sandbox` iframe as mixed content and MCP Apps can't render; the Apps tab needs a plain-`http` app origin today.
In every case, exposing the Inspector beyond loopback also means anyone who can reach it can drive its backend — keep authentication on (do **not** set `DANGEROUSLY_OMIT_AUTH`) and prefer a specific bind address over the wildcard.
## HTTP proxy support
The web backend connects to remote MCP servers through the shared Node transport (`core/mcp/node/transport.ts`), which honors the conventional proxy environment variables: `HTTPS_PROXY` / `HTTP_PROXY` (and their lowercase forms) select the proxy, and `NO_PROXY` exempts hosts. Routing is powered by [`undici`](https://www.npmjs.com/package/undici)'s `EnvHttpProxyAgent`, imported lazily only when a proxy variable is set, so runs without a proxy configured pay no cost. See the CLI README for more detail.

View file

@ -0,0 +1,67 @@
/**
* Resolves and validates the hostname the web server (prod backend + Vite dev
* server) binds to. Enforces the localhost-only default so the Inspector can't
* accidentally expose its process-spawning proxy to the whole network.
*
* Shared by `web-server-config.ts` (the Node backend) and `vite.config.ts` (the
* dev server) so both bind points enforce the same policy.
*/
import {
canonicalUrlHost,
isAllInterfacesHost,
stripBrackets,
} from "../../../core/node/hostUrl.ts";
/** Env var that opts into binding all network interfaces (see {@link resolveBindHostname}). */
export const BIND_ALL_INTERFACES_ENV = "DANGEROUSLY_BIND_ALL_INTERFACES";
/**
* An explicit, unambiguous opt-in. Unlike a bare `!!value` (which treats the
* string `"false"` as truthy), only `"true"`/`"1"` (case-insensitive) enable
* the override, so `DANGEROUSLY_BIND_ALL_INTERFACES=false` reads as "off".
*/
function isEnabled(value: string | undefined): boolean {
const v = value?.trim().toLowerCase();
return v === "true" || v === "1";
}
/**
* Resolve the bind hostname from `env` (default `process.env`), defaulting to
* `localhost`. Refuses an all-interfaces host (`0.0.0.0` / `::` / empty / their
* legacy spellings) unless {@link BIND_ALL_INTERFACES_ENV} is explicitly
* enabled — the published Docker image sets it, since a container must bind
* `0.0.0.0` to be reachable through `-p`. Throws (fail fast, loudly) rather than
* silently binding wide open. The returned value is trimmed and de-bracketed
* (an IPv6 literal is returned bare, e.g. `HOST=[::1]` → `::1`) so detection,
* `listen()`, and the origin list all consume the same value; `formatHostForUrl`
* re-adds the brackets wherever a URL is built.
*/
export function resolveBindHostname(
env: NodeJS.ProcessEnv = process.env,
): string {
const host = (env.HOST ?? "localhost").trim();
if (isAllInterfacesHost(host) && !isEnabled(env[BIND_ALL_INTERFACES_ENV])) {
// Show the resolved address when it differs from the typed spelling — the
// guard now catches forms the resolver folds to the wildcard (a fullwidth
// `HOST="0"` renders like `0`, `HOST=0` / `0x0` / `::0` bind `0.0.0.0`), and
// "bind a loopback host" reads as a non-sequitur without that hint.
const resolved = canonicalUrlHost(host);
// Compare de-bracketed on BOTH sides so neither a plain `HOST="::"` nor a
// bracketed `HOST="[::]"` is reported as "(resolves to [::])" — the
// bracketing is a URL-authority detail, not a resolution.
const shown =
stripBrackets(resolved) === stripBrackets(host.toLowerCase())
? `HOST="${host}"`
: `HOST="${host}" (resolves to ${resolved})`;
throw new Error(
`Refusing to bind ${shown}: this exposes the MCP Inspector to your ` +
`entire network, and its backend can spawn local processes and connect ` +
`to MCP servers on your behalf — the exposure DNS-rebinding attacks ` +
`target. Bind a loopback host (localhost / 127.0.0.1) instead. To ` +
`override — only inside an isolated container or trusted network — set ` +
`${BIND_ALL_INTERFACES_ENV}=true.`,
);
}
return stripBrackets(host);
}

View file

@ -18,7 +18,10 @@ import {
parseHeaderPair,
type ServerConfigOptions,
} from "../../../core/mcp/node/config.ts";
import { buildWebServerConfig } from "./web-server-config.js";
import {
buildWebServerConfig,
type WebServerConfig,
} from "./web-server-config.js";
import { startViteDevServer } from "./start-vite-dev-server.js";
import { startHonoServer } from "./server.js";
import { ensureWebBuild } from "./ensure-web-build.js";
@ -232,12 +235,25 @@ export async function runWeb(argv: string[]): Promise<number> {
process.exit(1);
}
const webConfig = buildWebServerConfig({
initialMcpConfig,
mcpConfigPath,
writable,
initialServers,
});
let webConfig: WebServerConfig;
try {
webConfig = buildWebServerConfig({
initialMcpConfig,
mcpConfigPath,
writable,
initialServers,
});
} catch (err) {
// e.g. the bind-host guard refusing HOST=0.0.0.0 — surface the actionable
// message rather than a raw stack trace from the launcher's top-level handler.
const message =
err instanceof Error
? err.message
: /* v8 ignore next -- buildWebServerConfig only ever throws Error instances; this fallback is a defensive guard for the impossible non-Error throw. */
"Invalid web server configuration.";
console.error("Error:", message);
process.exit(1);
}
const webRoot = join(__dirname, "..");
const distRoot = join(webRoot, "dist");
if (!isDev) {

View file

@ -7,6 +7,10 @@ import { createServer, type Server } from "node:http";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import {
canonicalUrlHost,
isAllInterfacesHost,
} from "../../../core/node/hostUrl.ts";
const __dirname = dirname(fileURLToPath(import.meta.url));
@ -15,6 +19,59 @@ export interface SandboxControllerOptions {
port: number;
/** Host to bind (default localhost). */
host?: string;
/**
* The backend's origin allow-list (the embedder origins). Used to build the
* proxy's `frame-ancestors` so the sandbox iframe isn't CSP-blocked when the
* inspector is served on a non-loopback host (network hosting / Docker). The
* real callers always pass a non-empty list (`buildWebServerConfig` never
* produces an empty `allowedOrigins` since #1795's H1 fix); an empty/omitted
* list (only a hand-constructed caller or a test) falls back to loopback-only.
*/
allowedOrigins?: string[];
}
// Loopback fallback. NB: no `http://[::1]:*` — a **bracketed IPv6 literal is not
// a valid CSP `host-source`** (the CSP3 `host-char` grammar is ALPHA/DIGIT/"-"
// only). Chromium rejects `http://[::1]:*` and, if it's the sole source, the
// directive degrades to `frame-ancestors 'none'` and blocks the frame — verified
// empirically. So MCP Apps requires browsing the app at a name or IPv4
// (`localhost` / `127.0.0.1`), which these two cover; a bare `[::1]` embedder
// can't be admitted by any frame-ancestors source and is unsupported for Apps.
const LOOPBACK_FRAME_ANCESTORS = ["http://127.0.0.1:*", "http://localhost:*"];
/**
* A well-formed CSP host-source: `scheme://host[:port]` with no whitespace, CSP
* metacharacters, or brackets. `allowedOrigins` comes from
* `web-server-config.ts`, where every entry is already a `new URL().origin`
* (canonical, no path/newline/`;`), so its **load-bearing job today is dropping
* bracketed IPv6** — a `http://[::1]:PORT` literal isn't a valid CSP host-source
* and, as the only source, would collapse the directive to `'none'`. The
* whitespace/metacharacter exclusions are belt-and-braces: `sandboxFrameAncestors`
* takes the list from a caller, not from env directly, so a future caller that
* doesn't pre-canonicalize can't corrupt or widen the header — `*` is excluded
* too, so a `http://*.example.com` entry (which the origin allow-list already
* rejects, but a future caller might not) can't broaden the embedder set. This
* filters the caller-supplied `allowedOrigins` only; {@link LOOPBACK_FRAME_ANCESTORS}
* is a trusted constant that deliberately uses the `:*` port-wildcard and is
* emitted as-is (it does NOT pass this regex, by design).
*/
const CSP_HOST_SOURCE = /^[a-z][a-z0-9+.-]*:\/\/[^\s;,'"[\]*]+$/i;
/**
* The proxy's `frame-ancestors` sources. The embedder is the inspector app
* page, whose origin is (by construction) in the backend's `allowedOrigins`, so
* derive the directive from that list — this keeps the MCP Apps iframe working
* on whatever host the app is actually served from, not just loopback.
* Malformed entries are dropped (see {@link CSP_HOST_SOURCE}); if nothing valid
* remains (the real backend always passes a non-empty list, so this is a
* hand-constructed caller, a test, or an all-malformed `ALLOWED_ORIGINS`), it
* falls back to the loopback family so the sandbox still loads locally and the
* header can't be corrupted.
*/
export function sandboxFrameAncestors(allowedOrigins?: string[]): string {
const valid = (allowedOrigins ?? []).filter((o) => CSP_HOST_SOURCE.test(o));
const sources = valid.length > 0 ? valid : LOOPBACK_FRAME_ANCESTORS;
return `frame-ancestors ${sources.join(" ")}`;
}
export interface SandboxController {
@ -23,27 +80,40 @@ export interface SandboxController {
getUrl(): string | null;
}
/**
* A usable listen port from a raw env value, or `undefined` if it isn't a plain
* integer in `0`–`65535` (0 = OS-assigned). The `^\d+$` test rejects `parseInt`
* partial parses (`6274abc`) and the upper bound keeps an out-of-range value
* (`70000`) from reaching `server.listen`, which throws `ERR_SOCKET_BAD_PORT`
* synchronously — matching the strict `CLIENT_PORT` validation.
*/
function parseListenPort(raw: string | undefined): number | undefined {
const v = raw?.trim();
if (!v || !/^\d+$/.test(v)) return undefined;
const n = parseInt(v, 10);
return n <= 65535 ? n : undefined;
}
/**
* Resolve sandbox port from env: MCP_SANDBOX_PORT → SERVER_PORT → 0 (dynamic).
* An invalid value falls through rather than crashing the boot; a set-but-invalid
* MCP_SANDBOX_PORT (the dedicated knob) is warned so the fall-through isn't
* silent — matching the warn-and-drop precedent for ALLOWED_ORIGINS.
*/
export function resolveSandboxPort(): number {
const fromSandbox = process.env.MCP_SANDBOX_PORT;
if (fromSandbox !== undefined && fromSandbox !== "") {
const n = parseInt(fromSandbox, 10);
if (!Number.isNaN(n) && n >= 0) return n;
const fromSandbox = parseListenPort(process.env.MCP_SANDBOX_PORT);
if (fromSandbox === undefined && process.env.MCP_SANDBOX_PORT?.trim()) {
console.warn(
`Ignoring invalid MCP_SANDBOX_PORT="${process.env.MCP_SANDBOX_PORT}" (need an integer 0–65535); falling back.`,
);
}
const fromServer = process.env.SERVER_PORT;
if (fromServer !== undefined && fromServer !== "") {
const n = parseInt(fromServer, 10);
if (!Number.isNaN(n) && n >= 0) return n;
}
return 0;
return fromSandbox ?? parseListenPort(process.env.SERVER_PORT) ?? 0;
}
export function createSandboxController(
options: SandboxControllerOptions,
): SandboxController {
const { port, host = "localhost" } = options;
const { port, host = "localhost", allowedOrigins } = options;
let server: Server | null = null;
let sandboxUrl: string | null = null;
@ -54,10 +124,10 @@ export function createSandboxController(
// the inner app document and, since multiple CSPs intersect, would override
// the per-app `connect-src`/`img-src` allowlists the host bakes into the
// wrapped HTML (see src/utils/sandbox-csp.ts). The opaque-origin sandbox on
// the inner frame is the structural boundary; `frame-ancestors` ensures the
// proxy can only be embedded by the local inspector itself.
const SANDBOX_PROXY_CSP =
"frame-ancestors http://127.0.0.1:* http://localhost:*";
// the inner frame is the structural boundary; `frame-ancestors` restricts the
// proxy to being embedded by the inspector app itself — see
// `sandboxFrameAncestors` for how the embedder origins are derived.
const SANDBOX_PROXY_CSP = sandboxFrameAncestors(allowedOrigins);
let sandboxHtml: string;
try {
@ -132,7 +202,19 @@ export function createSandboxController(
string form only occurs for unix-socket/pipe listens, which
this controller never performs. */
(addr as unknown as number);
sandboxUrl = `http://${host}:${actualPort}/sandbox`;
// Advertise `localhost` for a wildcard bind: the sandbox URL is
// served to the browser (via /api/config) and printed in the banner,
// and `http://0.0.0.0:PORT` isn't reachable from the client — but a
// wildcard bind serves loopback, so `localhost` is. Otherwise use the
// same canonical host the origin allow-list emits, so the served URL
// is reachable and its origin is allow-listed (matches the app banner).
// (`isAllInterfacesHost` canonicalizes internally too, so passing the
// pre-canonicalized host is belt-and-braces.)
const canonicalHost = canonicalUrlHost(host);
const urlHost = isAllInterfacesHost(canonicalHost)
? "localhost"
: canonicalHost;
sandboxUrl = `http://${urlHost}:${actualPort}/sandbox`;
settle({ port: actualPort, url: sandboxUrl });
});
});

View file

@ -15,6 +15,7 @@ import { serveStatic } from "@hono/node-server/serve-static";
import { Hono } from "hono";
import type { Context } from "hono";
import { createRemoteApp } from "../../../core/mcp/remote/node/server.ts";
import { formatHostForUrl } from "../../../core/node/hostUrl.ts";
import { createSandboxController } from "./sandbox-controller.js";
import { injectAuthToken } from "./inject-auth-token.js";
import type { WebServerConfig } from "./web-server-config.js";
@ -39,6 +40,7 @@ export async function startHonoServer(
const sandboxController = createSandboxController({
port: config.sandboxPort,
host: config.sandboxHost,
allowedOrigins: config.allowedOrigins,
});
await sandboxController.start();
@ -131,7 +133,7 @@ export async function startHonoServer(
httpServer.on("error", (err: Error) => {
if (err.message.includes("EADDRINUSE")) {
console.error(
`MCP Inspector PORT IS IN USE at http://${config.hostname}:${config.port}`,
`MCP Inspector PORT IS IN USE at http://${formatHostForUrl(config.hostname)}:${config.port}`,
);
process.exit(1);
} else {

View file

@ -57,6 +57,12 @@ export async function startViteDevServer(
server: {
port: config.port,
host: config.hostname,
// `strictPort: true` (matching `vite.config.ts`) so a busy port fails
// loudly instead of silently binding a different one — the origin
// allow-list and the sandbox `frame-ancestors` are derived from
// `config.port`, so a drifted bind would 403 every connect and CSP-block
// the MCP Apps iframe while the banner advertises the unusable port.
strictPort: true,
// Allow Vite to serve source files from the repo root (core/ lives
// outside clients/web), matching `vite.config.ts`'s `server.fs.allow`.
fs: {

View file

@ -63,6 +63,7 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
const sandboxController = createSandboxController({
port: config.sandboxPort,
host: config.sandboxHost,
allowedOrigins: config.allowedOrigins,
});
await sandboxController.start();

View file

@ -16,6 +16,11 @@ import {
import type { InitialConfigPayload } from "../../../core/mcp/remote/node/server.ts";
import { readInspectorVersionSafe } from "../../../core/node/version.ts";
import { resolveSandboxPort } from "./sandbox-controller.js";
import { resolveBindHostname } from "./resolve-bind-host.js";
import {
canonicalUrlHost,
isAllInterfacesHost,
} from "../../../core/node/hostUrl.ts";
// The single-source Inspector version (root package.json), read once at load.
// The browser can't read the filesystem the way the CLI/TUI do, so the backend
@ -163,7 +168,19 @@ export function printServerBanner(
resolvedToken: string,
sandboxUrl: string | undefined,
): string {
const baseUrl = `http://${config.hostname}:${actualPort}`;
// Advertise `localhost` for a wildcard bind (`http://0.0.0.0:PORT` is an
// awkward URL to click and points the user at a reachable, allow-listed
// address); otherwise use the SAME canonical host the allow-list emits, so the
// advertised URL's origin is always a member of `allowedOrigins`
// (`banner ⊆ allowedOrigins`) — including the IPv4-mapped case where
// `canonicalUrlHost` unmaps but `formatHostForUrl` wouldn't. `httpOrigin`
// keeps the banner and the list agreeing on the default-port form (both drop
// :80). Computing `h` once keeps the predicate and the value reading the same
// form; `isAllInterfacesHost` also canonicalizes internally, so this is
// belt-and-braces, not what makes them agree.
const h = canonicalUrlHost(config.hostname);
const bannerHost = isAllInterfacesHost(h) ? "localhost" : h;
const baseUrl = httpOrigin(bannerHost, actualPort);
const url =
config.dangerouslyOmitAuth || !resolvedToken
? baseUrl
@ -196,6 +213,87 @@ export interface BuildWebServerConfigOptions {
initialServers?: MCPConfig | null;
}
/**
* Loopback hostnames that all address the local machine. `localhost` resolves
* to *either* `127.0.0.1` (IPv4) or `::1` (IPv6) depending on the OS resolver,
* and Node/Vite may bind the IPv6 form — so the browser can legitimately end up
* at `http://[::1]:PORT` even though the banner printed `http://localhost:PORT`.
* IPv6 is the **bracketed** form only (`[::1]`): the sole caller looks up
* `canonicalUrlHost(hostname)`, which always brackets an IPv6 literal.
*/
const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
/**
* Build an http origin string. The port is omitted when it's the http scheme
* default (80): browsers drop the default port from `Origin`, and the guard is
* an exact string match, so `http://host:80` could never match a real request.
*/
function httpOrigin(host: string, port: number): string {
return port === 80 ? `http://${host}` : `http://${host}:${port}`;
}
/** The three interchangeable loopback origin forms for a port. */
function loopbackOrigins(port: number): string[] {
return [
httpOrigin("localhost", port),
httpOrigin("127.0.0.1", port),
httpOrigin("[::1]", port),
];
}
/**
* The default allowed-origins list for a given bind host/port.
*
* When the bind host is loopback, `localhost`, `127.0.0.1`, and `[::1]` are
* interchangeable ways to reach the same server, so the origin the browser
* actually sends is nondeterministic (it depends on how `localhost` resolved
* and which family got bound). Returning all three loopback origin forms keeps
* the DNS-rebinding guard effective — still scoped to loopback at this exact
* port — while not 403-ing a browser that landed on `[::1]` instead of the
* `localhost` the banner advertised. The host is canonicalized first
* ({@link canonicalUrlHost}), so a non-canonical spelling of a loopback address
* still lands in the loopback branch.
*
* An **all-interfaces** bind (`0.0.0.0` / `::`, the opt-in path the Docker image
* uses) also serves loopback, so it gets the loopback trio *plus the canonical
* wildcard origins* `http://0.0.0.0:PORT` and `http://[::]:PORT`. Both are
* locally connectable, the image/docs describe binding to `0.0.0.0:6274`, and a
* dual-stack `::` bind serves IPv4 too — so a browser may send either. We emit
* the **canonical** pair rather than the typed `HOST` spelling because browsers
* canonicalize the address before building the `Origin` (`HOST=0` / `0x0` /
* `0.0.0` all send `http://0.0.0.0:PORT`, `::0` sends `http://[::]:PORT`), so
* echoing the raw spelling would emit an entry the browser can never match.
* Including these weakens nothing (no attacker document can claim a loopback /
* `0.0.0.0` origin without the user having navigated there). Reaching the server
* at a non-loopback address — a LAN IP, a public hostname — still needs
* `ALLOWED_ORIGINS`, since those origins can't be enumerated from the wildcard.
*
* For a specific non-loopback host (a real IP/hostname) we return the single
* exact origin — canonicalized and, for an IPv6 literal, bracketed, so it
* matches the `Origin` header the browser actually sends.
*/
export function defaultAllowedOrigins(
hostname: string,
port: number,
): string[] {
// The loopback lookup and the emitted origin both read the canonicalized `h`
// (the wildcard check via `isAllInterfacesHost` canonicalizes internally), so
// every branch reasons about the same address.
const h = canonicalUrlHost(hostname);
if (LOOPBACK_HOSTNAMES.has(h)) {
return loopbackOrigins(port);
}
if (isAllInterfacesHost(h)) {
return [
...loopbackOrigins(port),
httpOrigin("0.0.0.0", port),
httpOrigin("[::]", port),
];
}
// `h` is already the canonical, URL-ready host (bracketed for IPv6).
return [httpOrigin(h, port)];
}
/**
* Build WebServerConfig from process.env and optional initial MCP server config.
* Used by the launcher runner, Vite dev (`buildWebServerConfigFromEnv`), and prod standalone.
@ -209,9 +307,21 @@ export function buildWebServerConfig(
writable = true,
initialServers = null,
} = options;
const port = parseInt(process.env.CLIENT_PORT ?? "6274", 10);
const hostname = process.env.HOST ?? "localhost";
const baseUrl = `http://${hostname}:${port}`;
// Treat an empty CLIENT_PORT as unset (matches resolveSandboxPort's handling
// of MCP_SANDBOX_PORT / SERVER_PORT), then require a fixed port: the origin
// allow-list and the sandbox CSP are both built from it, so `0` (OS-assigned),
// a non-numeric value, or trailing garbage would make them reference a port
// the server isn't on — every connect 403s and the MCP Apps iframe is blocked.
// The `^\d+$` test rejects `parseInt`'s partial parses (`6274abc`, `80.9`).
// Fail fast with an actionable message (run-web surfaces it cleanly).
const rawPort = process.env.CLIENT_PORT?.trim() || "6274";
const port = parseInt(rawPort, 10);
if (!/^\d+$/.test(rawPort) || port < 1 || port > 65535) {
throw new Error(
`Invalid CLIENT_PORT="${process.env.CLIENT_PORT}": the web server needs a fixed port in 1–65535 (0 / dynamic is unsupported — the origin allow-list and sandbox CSP are derived from it).`,
);
}
const hostname = resolveBindHostname();
const dangerouslyOmitAuth = !!process.env.DANGEROUSLY_OMIT_AUTH;
const authToken = dangerouslyOmitAuth
? ""
@ -233,6 +343,48 @@ export function buildWebServerConfig(
);
}
// Parse ALLOWED_ORIGINS into canonical origins. Each entry is normalized via
// `new URL(o).origin` (drops a trailing slash/path and any userinfo, lowercases
// and punycodes the host, drops the default :80) so the natural copy-paste
// forms — `http://localhost:6274/` from the address bar, an uppercase or IDN
// host, an explicit `:80` — match the canonical `Origin` the browser sends
// rather than 403ing on an exact-string compare. Unparseable, opaque, and
// wildcard entries are warned and dropped (see inline).
//
// When nothing survives (unset, `""`, `" "`, `","`, or all-invalid) we fall
// back to `defaultAllowedOrigins` below — critically NOT to `[]`, which the
// origin middleware treats as *allow-all*, silently disabling the guard.
const configuredOrigins = process.env.ALLOWED_ORIGINS?.split(",")
.map((o) => o.trim())
.filter(Boolean)
.map((o) => {
try {
const { origin } = new URL(o);
// A scheme-less entry (`localhost:6274`) doesn't throw — `new URL` reads
// the host as the scheme and `.origin` is the literal string "null"
// (also non-special schemes: `file:`, `about:`, `javascript:`, `data:`,
// and browser-extension schemes like `chrome-extension:`). Reject it:
// it's not the origin the user meant, AND "null" is a real header value
// browsers send from opaque origins (a sandboxed iframe, a `data:` doc),
// so allow-listing it would erode the guard. Entries need an http(s)
// scheme — the app is served over http(s), and a browser's `Origin` on
// any request (including a WebSocket handshake) is its page's http(s)
// origin, never a `ws:` one, so a `ws://` entry could never match anyway.
if (origin === "null") throw new Error("opaque origin");
// A wildcard (`http://*.example.com`) survives `new URL` but can never
// match the exact-compare origin guard — yet `*.example.com` IS a legal
// CSP host-source, so it would silently work for the sandbox iframe and
// silently 403 every connect (the most confusing split). Reject it so it
// fails loudly and consistently; list exact origins instead.
if (origin.includes("*")) throw new Error("wildcard origin");
return origin;
} catch {
console.warn(`Ignoring invalid ALLOWED_ORIGINS entry: ${o}`);
return null;
}
})
.filter((o): o is string => o !== null);
return {
port,
hostname,
@ -243,9 +395,9 @@ export function buildWebServerConfig(
writable,
initialServers,
storageDir: process.env.MCP_STORAGE_DIR,
allowedOrigins: process.env.ALLOWED_ORIGINS?.split(",").filter(Boolean) ?? [
baseUrl,
],
allowedOrigins: configuredOrigins?.length
? configuredOrigins
: defaultAllowedOrigins(hostname, port),
sandboxPort,
sandboxHost: hostname,
logger,

View file

@ -76,6 +76,29 @@ describe("runner OAuth callback URL", () => {
).toThrow(/must use http scheme/);
});
it.each([
"http://0.0.0.0:6276/oauth/callback", // wildcard
"http://[::]:6276/oauth/callback", // IPv6 wildcard
"http://192.168.1.50:6276/oauth/callback", // LAN — plaintext code over the network
"http://example.com:6276/oauth/callback", // routable hostname
])(
"rejects a non-loopback callback host %j (the code listener must be loopback)",
(url) => {
expect(() => parseRunnerOAuthCallbackUrl(url)).toThrow(
/must bind a loopback host/,
);
},
);
it.each([
["http://127.0.0.1:6276/oauth/callback", "127.0.0.1"],
["http://localhost:6276/oauth/callback", "localhost"],
["http://127.5:6276/oauth/callback", "127.0.0.5"], // 127.0.0.0/8, shorthand normalized by new URL
["http://[::1]:6276/oauth/callback", "::1"], // de-bracketed so listen() can bind it
])("accepts the loopback callback host %j", (url, expectedHostname) => {
expect(parseRunnerOAuthCallbackUrl(url).hostname).toBe(expectedHostname);
});
it("formatRunnerOAuthRedirectUrl round-trips default config", () => {
const config = parseRunnerOAuthCallbackUrl();
expect(formatRunnerOAuthRedirectUrl(config)).toBe(

View file

@ -0,0 +1,164 @@
import { describe, it, expect } from "vitest";
import {
canonicalUrlHost,
formatHostForUrl,
isAllInterfacesHost,
isLoopbackHost,
stripBrackets,
} from "@inspector/core/node/hostUrl.js";
describe("isLoopbackHost", () => {
it.each([
"localhost",
"LOCALHOST",
"127.0.0.1",
"127.5", // 127.0.0.0/8 shorthand
"0x7f.0.0.1",
"2130706433",
"::1",
"[::1]",
"0:0:0:0:0:0:0:1",
"::ffff:127.0.0.1", // IPv4-mapped loopback → unmapped to 127.0.0.1
"::ffff:7f00:1", // its canonical serialization (what new URL().hostname yields)
"127.255.255.255", // top of 127.0.0.0/8
"localhost.", // root-anchored FQDN (WHATWG keeps the dot; binds loopback)
"127.0.0.1.", // trailing dot on an IP literal (WHATWG strips it)
])("flags the loopback host %j", (host) => {
expect(isLoopbackHost(host)).toBe(true);
});
it.each([
"0.0.0.0",
"::",
"192.168.1.50",
"example.com",
"126.0.0.1", // adjacent to but outside 127/8
"128.0.0.1",
"0.0.0.127", // bare "127" resolves here, not loopback
"", // empty is the wildcard (isAllInterfacesHost's job), not loopback
// Out-of-range octets survive canonicalUrlHost's non-URL fallback — the
// bounded regex must still reject them.
"127.999.0.1",
"127.0.0.256",
])("does not flag the non-loopback host %j", (host) => {
expect(isLoopbackHost(host)).toBe(false);
});
});
describe("isAllInterfacesHost", () => {
it.each([
"0.0.0.0",
"::",
"",
" 0.0.0.0 ",
" :: ",
"[::]",
"0:0:0:0:0:0:0:0",
"::ffff:0.0.0.0",
"::ffff:0:0",
// IPv6 wildcard spellings that canonicalize to `::`.
"::0",
"0::0",
"::0.0.0.0",
"0:0::0",
"0000:0000:0000:0000:0000:0000:0000:0000",
// Zone-scoped wildcard: net.isIPv6 accepts the %zone, new URL() rejects it,
// so the zone must be stripped before canonicalizing (else it throws).
"::%eth0",
// Legacy inet_aton spellings the OS still binds as 0.0.0.0.
"0",
"0x0",
"0x0.0.0.0",
"000.000.000.000",
"0.0", // short inet_aton form (1–3 parts) still binds the wildcard
"0.0.0",
"00000000000", // bare octal zero — parseAddressPart's [0-9]+ handles octal
"0x00000000", // bare hex zero
// Fullwidth (IDNA-mapped) spellings the resolver folds to 0.0.0.0 before
// binding — the guard must canonicalize, not read the raw string.
"0", // fullwidth "0"
"00.0.0", // fullwidth "0" + ".0.0"
"0.0.0.0", // fullwidth dots
])("flags the all-interfaces host %j", (host) => {
expect(isAllInterfacesHost(host)).toBe(true);
});
it.each([
"localhost",
"127.0.0.1",
"::1",
"[::1]",
"example.com",
"192.168.1.50",
"1.0.0.0",
"0.0.0.1",
"::ffff:0", // canonicalizes to ::ffff:0, a distinct address — not the wildcard
"0.0.0.0.0", // 5 octets — not a valid IPv4, must not be flagged (parts.length > 4)
"fe80::1%eth0", // a zone-scoped link-local — a real bind host, not the wildcard
"::1%lo0", // zone-scoped loopback — must not be flagged and must not throw
"127.0.0.1", // fullwidth 127 → 127.0.0.1, a real loopback address, not the wildcard
])("does not flag the loopback/specific host %j", (host) => {
expect(isAllInterfacesHost(host)).toBe(false);
});
});
describe("formatHostForUrl", () => {
it.each([
["::1", "[::1]"],
["fe80::1", "[fe80::1]"],
[" ::1 ", "[::1]"],
["fe80::1%eth0", "[fe80::1]"], // zone id dropped — a URL host can't carry one
["::1%lo0", "[::1]"],
["[fe80::1%eth0]", "[fe80::1]"], // bracketed-with-zone → still a valid URL host
])("brackets the IPv6 literal %j", (host, expected) => {
expect(formatHostForUrl(host)).toBe(expected);
});
it.each(["localhost", "127.0.0.1", "192.168.1.50", "example.com", "[::1]"])(
"passes the non-IPv6 / already-bracketed host %j through",
(host) => {
expect(formatHostForUrl(host)).toBe(host.trim());
},
);
it("does not bracket a non-IPv6 value that merely contains a colon", () => {
// A mistyped host:port must not be wrapped as [host:port].
expect(formatHostForUrl("localhost:6274")).toBe("localhost:6274");
});
});
describe("stripBrackets", () => {
it.each([
["[::1]", "::1"],
["[fe80::1%eth0]", "fe80::1%eth0"],
["[]", ""], // zero-or-more: an empty bracket pair reduces to ""
["127.0.0.1", "127.0.0.1"],
])("strips a surrounding bracket pair from %j", (host, expected) => {
expect(stripBrackets(host)).toBe(expected);
});
});
describe("canonicalUrlHost", () => {
it.each([
["127.1", "127.0.0.1"],
["0x7f.0.0.1", "127.0.0.1"],
["2130706433", "127.0.0.1"],
["0:0:0:0:0:0:0:1", "[::1]"],
["::0001", "[::1]"],
["LOCALHOST", "localhost"],
["Example.COM", "example.com"],
["fe80::1", "[fe80::1]"],
// IPv4-mapped IPv6 → the dotted IPv4 the socket answers on (intentional
// divergence from browser canonicalization).
["::ffff:127.0.0.1", "127.0.0.1"],
["::ffff:192.168.1.50", "192.168.1.50"],
// A distinct address is unchanged.
["127.0.0.2", "127.0.0.2"],
])("canonicalizes %j to %j", (host, expected) => {
expect(canonicalUrlHost(host)).toBe(expected);
});
it("falls back to the formatted value when the host isn't a parseable URL", () => {
expect(canonicalUrlHost("")).toBe("");
});
});

View file

@ -0,0 +1,91 @@
import { describe, it, expect } from "vitest";
import {
BIND_ALL_INTERFACES_ENV,
resolveBindHostname,
} from "../../../../server/resolve-bind-host.js";
describe("resolveBindHostname", () => {
it("defaults to localhost when HOST is unset", () => {
expect(resolveBindHostname({})).toBe("localhost");
});
it("returns a loopback HOST unchanged", () => {
expect(resolveBindHostname({ HOST: "127.0.0.1" })).toBe("127.0.0.1");
});
it("trims the returned host so detection and the bind value agree", () => {
expect(resolveBindHostname({ HOST: " 127.0.0.1 " })).toBe("127.0.0.1");
});
it("returns a bracketed IPv6 HOST bare so listen() can bind it", () => {
expect(resolveBindHostname({ HOST: "[::1]" })).toBe("::1");
});
it("keeps the zone index on a link-local HOST for listen()", () => {
// The guard must not throw on a zone-scoped host, and must return it with
// the zone intact (listen() needs the zone to pick the interface).
expect(resolveBindHostname({ HOST: "fe80::1%eth0" })).toBe("fe80::1%eth0");
});
it.each([
"0.0.0.0",
"::",
"",
"0",
"0x0.0.0.0",
"::ffff:0.0.0.0",
" 0 ",
"0", // fullwidth "0" — the resolver binds it as 0.0.0.0, so the guard must refuse it
])("refuses the all-interfaces host %j without the opt-in", (host) => {
expect(() => resolveBindHostname({ HOST: host })).toThrow(
new RegExp(BIND_ALL_INTERFACES_ENV),
);
});
it("names the resolved wildcard address when the spelling differs (fullwidth)", () => {
// `HOST="0"` renders like `0`, so the message shows it resolves to 0.0.0.0.
expect(() => resolveBindHostname({ HOST: "0" })).toThrow(
/resolves to 0\.0\.0\.0/,
);
});
it("does not add a resolved-address hint for an already-canonical bracketed HOST", () => {
// `HOST="[::]"` is accepted-then-refused as the wildcard; the message must
// not read "(resolves to [::])" — same value, just bracketed. Capture the
// message outside try/catch so a stopped-throwing regression reports clearly.
let message = "";
expect(() => {
try {
resolveBindHostname({ HOST: "[::]" });
} catch (err) {
message = (err as Error).message;
throw err;
}
}).toThrow(BIND_ALL_INTERFACES_ENV);
expect(message).not.toContain("resolves to");
});
it.each(["true", "TRUE", "1", " true "])(
"allows 0.0.0.0 when the opt-in is %j",
(flag) => {
expect(
resolveBindHostname({
HOST: "0.0.0.0",
[BIND_ALL_INTERFACES_ENV]: flag,
}),
).toBe("0.0.0.0");
},
);
it.each(["false", "0", "", "yes", "no"])(
"still refuses 0.0.0.0 when the opt-in reads %j",
(flag) => {
expect(() =>
resolveBindHostname({
HOST: "0.0.0.0",
[BIND_ALL_INTERFACES_ENV]: flag,
}),
).toThrow();
},
);
});

View file

@ -42,6 +42,7 @@ describe("runWeb", () => {
let exitSpy: ReturnType<typeof vi.spyOn>;
let exitCode: number | undefined;
let catalogEnvSnapshot: string | undefined;
let hostEnvSnapshot: string | undefined;
const signalHandlers = new Map<string, () => void>();
beforeEach(() => {
@ -54,6 +55,8 @@ describe("runWeb", () => {
exitCode = undefined;
catalogEnvSnapshot = process.env.MCP_CATALOG_PATH;
delete process.env.MCP_CATALOG_PATH;
hostEnvSnapshot = process.env.HOST;
delete process.env.HOST;
logLines = [];
warnLines = [];
@ -98,6 +101,11 @@ describe("runWeb", () => {
} else {
process.env.MCP_CATALOG_PATH = catalogEnvSnapshot;
}
if (hostEnvSnapshot === undefined) {
delete process.env.HOST;
} else {
process.env.HOST = hostEnvSnapshot;
}
});
async function expectServerStarted(
@ -162,6 +170,19 @@ describe("runWeb", () => {
expect(startHonoServer).not.toHaveBeenCalled();
});
it("surfaces the bind-guard error as an actionable message, not a stack trace", async () => {
// HOST=0.0.0.0 without the opt-in makes buildWebServerConfig throw; run-web
// must catch it and print "Error: …" rather than let it bubble as a raw
// stack trace from the launcher's top-level handler.
process.env.HOST = "0.0.0.0";
await expect(runWeb(["node", "run-web"])).rejects.toThrow("process.exit:1");
expect(
errorLines.some((l) => l.includes("DANGEROUSLY_BIND_ALL_INTERFACES")),
).toBe(true);
expect(startHonoServer).not.toHaveBeenCalled();
expect(startViteDevServer).not.toHaveBeenCalled();
});
it("starts Vite when --dev is set", async () => {
void runWeb(["node", "run-web", "--dev"]);
await expectServerStarted(startViteDevServer);

View file

@ -3,10 +3,58 @@ import { createServer, type Server } from "node:http";
import {
createSandboxController,
resolveSandboxPort,
sandboxFrameAncestors,
} from "../../../../server/sandbox-controller.js";
describe("sandboxFrameAncestors", () => {
it("derives the directive from the provided allow-list", () => {
expect(
sandboxFrameAncestors([
"http://192.168.1.50:6274",
"https://inspector.example.com",
]),
).toBe(
"frame-ancestors http://192.168.1.50:6274 https://inspector.example.com",
);
});
it.each([[undefined], [[]]])(
"falls back to the loopback family when the list is %j",
(origins) => {
// No `[::1]` source — a bracketed IPv6 literal is not a valid CSP
// host-source (see sandbox-controller.ts).
expect(sandboxFrameAncestors(origins as string[] | undefined)).toBe(
"frame-ancestors http://127.0.0.1:* http://localhost:*",
);
},
);
it("drops malformed and IPv6-literal entries that can't be valid CSP sources", () => {
// A newline would make writeHead throw ERR_INVALID_CHAR; a ';' would inject
// extra directives; a bracketed IPv6 literal isn't a valid CSP host-source.
// Only the well-formed origin survives.
expect(
sandboxFrameAncestors([
"http://good.example:6274",
"http://a:1; sandbox",
"http://b:2\nX-Evil: 1",
"http://[::1]:6274",
"http://*.example.com", // a wildcard would widen the embedder set
"not a url",
]),
).toBe("frame-ancestors http://good.example:6274");
});
it("falls back to loopback when every entry is malformed or IPv6-literal", () => {
expect(
sandboxFrameAncestors(["http://a:1; sandbox", "http://[::1]:6274"]),
).toBe("frame-ancestors http://127.0.0.1:* http://localhost:*");
});
});
describe("resolveSandboxPort", () => {
let envSnapshot: { mcp?: string; server?: string };
let warnSpy: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
envSnapshot = {
@ -15,9 +63,12 @@ describe("resolveSandboxPort", () => {
};
delete process.env.MCP_SANDBOX_PORT;
delete process.env.SERVER_PORT;
// A set-but-invalid MCP_SANDBOX_PORT warns; keep it off the test console.
warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
});
afterEach(() => {
warnSpy.mockRestore();
if (envSnapshot.mcp === undefined) delete process.env.MCP_SANDBOX_PORT;
else process.env.MCP_SANDBOX_PORT = envSnapshot.mcp;
if (envSnapshot.server === undefined) delete process.env.SERVER_PORT;
@ -65,6 +116,17 @@ describe("resolveSandboxPort", () => {
process.env.MCP_SANDBOX_PORT = "-1";
expect(resolveSandboxPort()).toBe(0);
});
it("rejects a partial-parse value (6274abc) rather than binding 6274", () => {
process.env.MCP_SANDBOX_PORT = "6274abc";
process.env.SERVER_PORT = "9100";
expect(resolveSandboxPort()).toBe(9100);
});
it("rejects an out-of-range value (70000) so it can't crash listen", () => {
process.env.MCP_SANDBOX_PORT = "70000";
expect(resolveSandboxPort()).toBe(0);
});
});
describe("createSandboxController", () => {
@ -85,7 +147,10 @@ describe("createSandboxController", () => {
// container, so any default-src/connect-src here would intersect with and
// override the per-app CSP baked into the inner document.
const csp = res.headers.get("content-security-policy") ?? "";
expect(csp).toContain("frame-ancestors http://127.0.0.1:*");
// Assert the FULL directive (toBe, not toContain) so re-adding a source —
// e.g. the `http://[::1]:*` that F2 proved harmful — would fail the test.
// No `[::1]` — a bracketed IPv6 literal is not a valid CSP host-source.
expect(csp).toBe("frame-ancestors http://127.0.0.1:* http://localhost:*");
expect(csp).not.toContain("default-src");
expect(csp).not.toContain("connect-src");
const body = await res.text();
@ -97,6 +162,57 @@ describe("createSandboxController", () => {
}
});
it("serves a CSP derived from allowedOrigins (the shipped default path)", async () => {
// Both real callers always pass allowedOrigins, so the header the product
// actually serves is the derived exact-origin directive, not the fallback.
const controller = createSandboxController({
port: 0,
allowedOrigins: [
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274", // dropped — not a valid CSP host-source
],
});
try {
const { url } = await controller.start();
const res = await fetch(url);
const csp = res.headers.get("content-security-policy") ?? "";
expect(csp).toBe(
"frame-ancestors http://localhost:6274 http://127.0.0.1:6274",
);
} finally {
await controller.close();
}
});
it("advertises localhost in the sandbox URL for a wildcard bind", async () => {
// 0.0.0.0 isn't reachable from the browser, but a wildcard bind serves
// loopback — so the URL handed to the client (and printed in the banner)
// uses localhost.
const controller = createSandboxController({ port: 0, host: "0.0.0.0" });
try {
const { url, port } = await controller.start();
expect(url).toBe(`http://localhost:${port}/sandbox`);
} finally {
await controller.close();
}
});
it("uses the canonical (unmapped) host in the sandbox URL", async () => {
// Same canonicalization as the origin allow-list, so the served sandbox URL
// is reachable — ::ffff:127.0.0.1 answers at 127.0.0.1, not [::ffff:...].
const controller = createSandboxController({
port: 0,
host: "::ffff:127.0.0.1",
});
try {
const { url, port } = await controller.start();
expect(url).toBe(`http://127.0.0.1:${port}/sandbox`);
} finally {
await controller.close();
}
});
it("returns 404 for paths other than /sandbox", async () => {
const controller = createSandboxController({ port: 0 });
try {

View file

@ -1,7 +1,8 @@
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import {
buildWebServerConfig,
buildWebServerConfigFromEnv,
defaultAllowedOrigins,
printServerBanner,
webServerConfigToInitialPayload,
type WebServerConfig,
@ -20,6 +21,7 @@ const MUTATED_ENV_KEYS = [
"CLIENT_PORT",
"HOST",
"DANGEROUSLY_OMIT_AUTH",
"DANGEROUSLY_BIND_ALL_INTERFACES",
"MCP_STORAGE_DIR",
"ALLOWED_ORIGINS",
"MCP_SANDBOX_PORT",
@ -75,7 +77,11 @@ describe("buildWebServerConfigFromEnv", () => {
expect(cfg.dangerouslyOmitAuth).toBe(false);
expect(cfg.initialMcpConfig).toBeNull();
expect(cfg.storageDir).toBeUndefined();
expect(cfg.allowedOrigins).toEqual(["http://localhost:6274"]);
expect(cfg.allowedOrigins).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
expect(cfg.sandboxPort).toBe(0);
expect(cfg.sandboxHost).toBe("localhost");
expect(cfg.logger).toBeUndefined();
@ -85,13 +91,54 @@ describe("buildWebServerConfigFromEnv", () => {
expect(cfg.autoOpen).toBe(false);
});
it("honors CLIENT_PORT and HOST", () => {
it("honors CLIENT_PORT and a loopback HOST", () => {
process.env.CLIENT_PORT = "8123";
process.env.HOST = "0.0.0.0";
process.env.HOST = "127.0.0.1";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.port).toBe(8123);
expect(cfg.hostname).toBe("127.0.0.1");
});
it("refuses HOST=0.0.0.0 without the bind-all opt-in", () => {
process.env.HOST = "0.0.0.0";
expect(() => buildWebServerConfigFromEnv()).toThrow(
/DANGEROUSLY_BIND_ALL_INTERFACES/,
);
});
it("allows HOST=0.0.0.0 when the bind-all opt-in is set", () => {
process.env.CLIENT_PORT = "8123";
process.env.HOST = "0.0.0.0";
process.env.DANGEROUSLY_BIND_ALL_INTERFACES = "true";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.hostname).toBe("0.0.0.0");
expect(cfg.allowedOrigins).toEqual(["http://0.0.0.0:8123"]);
// A wildcard bind serves loopback, so the default allow-list is the
// loopback trio (what a `docker run -p` browser actually sends) plus the
// canonical wildcard pair (0.0.0.0 / [::]).
expect(cfg.allowedOrigins).toEqual([
"http://localhost:8123",
"http://127.0.0.1:8123",
"http://[::1]:8123",
"http://0.0.0.0:8123",
"http://[::]:8123",
]);
});
it("expands a loopback HOST into all equivalent loopback origins", () => {
// `localhost` resolves to either 127.0.0.1 or ::1 depending on the OS, and
// Node/Vite may bind the IPv6 form — so a browser can send `Origin:
// http://[::1]:PORT` even though the banner advertised `localhost`. The
// default must accept all three so the DNS-rebinding guard doesn't 403 a
// legitimate loopback connect (the exact bug behind an stdio server that
// "should always work" failing with a 403 Invalid origin).
process.env.HOST = "127.0.0.1";
process.env.CLIENT_PORT = "6274";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.allowedOrigins).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
});
it("clears authToken when DANGEROUSLY_OMIT_AUTH is set even if AUTH_TOKEN is present", () => {
@ -121,10 +168,107 @@ describe("buildWebServerConfigFromEnv", () => {
expect(cfg.authToken).toBe("primary");
});
it("parses ALLOWED_ORIGINS and filters empty entries", () => {
process.env.ALLOWED_ORIGINS = "http://a,,http://b";
it("parses ALLOWED_ORIGINS, trimming entries and filtering empties", () => {
process.env.ALLOWED_ORIGINS = "http://a:1, , http://b:2 ";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.allowedOrigins).toEqual(["http://a", "http://b"]);
expect(cfg.allowedOrigins).toEqual(["http://a:1", "http://b:2"]);
});
it.each(["", " ", ","])(
"falls back to the default (not an empty allow-all) when ALLOWED_ORIGINS is %j",
(value) => {
// An empty parsed list must NOT reach the middleware — it treats an empty
// allow-list as allow-all, which would silently disable the origin guard.
process.env.ALLOWED_ORIGINS = value;
const cfg = buildWebServerConfigFromEnv();
expect(cfg.allowedOrigins).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
},
);
it("canonicalizes ALLOWED_ORIGINS entries so copy-paste forms still match", () => {
// Trailing slash, uppercase host, explicit default :80 — all normalized to
// the canonical Origin the browser actually sends.
process.env.ALLOWED_ORIGINS =
"http://localhost:6274/, http://Example.COM:6274, http://myhost:80";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.allowedOrigins).toEqual([
"http://localhost:6274",
"http://example.com:6274",
"http://myhost",
]);
});
it("drops unparseable ALLOWED_ORIGINS entries (and falls back if none survive)", () => {
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
try {
process.env.ALLOWED_ORIGINS = "not a url, *, http://ok:1";
const cfg = buildWebServerConfigFromEnv();
// "not a url" / "*" throw; "http://ok:1" parses.
expect(cfg.allowedOrigins).toEqual(["http://ok:1"]);
process.env.ALLOWED_ORIGINS = "not a url, also bad";
const cfg2 = buildWebServerConfigFromEnv();
expect(cfg2.allowedOrigins).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
} finally {
warnSpy.mockRestore();
}
});
it('drops scheme-less / opaque ALLOWED_ORIGINS entries rather than allow-listing "null"', () => {
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
try {
// `new URL("localhost:6274").origin` is the literal "null" (not a throw) —
// must be dropped, not allow-listed (it'd match a real `Origin: null`).
process.env.ALLOWED_ORIGINS =
"localhost:6274, file:///srv, http://real:1";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.allowedOrigins).toEqual(["http://real:1"]);
// All scheme-less → nothing survives → fail-closed fallback to default.
process.env.ALLOWED_ORIGINS = "localhost:6274, myhost:8080";
const cfg2 = buildWebServerConfigFromEnv();
expect(cfg2.allowedOrigins).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
} finally {
warnSpy.mockRestore();
}
});
it("drops a wildcard ALLOWED_ORIGINS entry (works for CSP but never for the origin check)", () => {
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
try {
process.env.ALLOWED_ORIGINS =
"http://*.example.com:6274, http://real.example.com:6274";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.allowedOrigins).toEqual(["http://real.example.com:6274"]);
} finally {
warnSpy.mockRestore();
}
});
it.each(["0", "abc", "70000", "-1", "6274abc", "80.9"])(
"rejects an unusable CLIENT_PORT %j with an actionable error",
(value) => {
process.env.CLIENT_PORT = value;
expect(() => buildWebServerConfigFromEnv()).toThrow(/CLIENT_PORT/);
},
);
it("treats an empty CLIENT_PORT as unset (defaults to 6274)", () => {
process.env.CLIENT_PORT = "";
const cfg = buildWebServerConfigFromEnv();
expect(cfg.port).toBe(6274);
});
it("resolves sandboxPort from MCP_SANDBOX_PORT", () => {
@ -196,6 +340,110 @@ describe("buildWebServerConfigFromEnv", () => {
});
});
describe("defaultAllowedOrigins", () => {
it.each(["localhost", "127.0.0.1", "::1", "[::1]", "LOCALHOST"])(
"expands the loopback host %s into all three loopback origins",
(host) => {
expect(defaultAllowedOrigins(host, 6274)).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
},
);
it("returns a single exact origin for a specific non-loopback host", () => {
expect(defaultAllowedOrigins("192.168.1.50", 6274)).toEqual([
"http://192.168.1.50:6274",
]);
});
// A non-canonical spelling of a loopback address is canonicalized (the way the
// browser canonicalizes it into `Origin`), so it's recognized as loopback and
// gets the trio — not a single unmatchable entry.
it.each([
"127.1",
"0x7f.0.0.1",
"2130706433",
"0:0:0:0:0:0:0:1",
"::0001",
"::ffff:127.0.0.1", // IPv4-mapped loopback — the socket answers on 127.0.0.1
])("canonicalizes the loopback spelling %j and returns the trio", (host) => {
expect(defaultAllowedOrigins(host, 6274)).toEqual([
"http://localhost:6274",
"http://127.0.0.1:6274",
"http://[::1]:6274",
]);
});
it("unmaps an IPv4-mapped non-loopback host to its dotted form", () => {
expect(defaultAllowedOrigins("::ffff:192.168.1.50", 6274)).toEqual([
"http://192.168.1.50:6274",
]);
});
it("keeps a distinct non-loopback address (127.0.0.2) as a single origin", () => {
// 127.0.0.2 is canonical and a bind there doesn't serve 127.0.0.1, so the
// single-origin branch is correct — only non-canonical *spellings* expand.
expect(defaultAllowedOrigins("127.0.0.2", 6274)).toEqual([
"http://127.0.0.2:6274",
]);
});
it("handles an empty host (canonicalUrlHost's non-URL fallback) as the wildcard", () => {
// `new URL("http://")` throws, so canonicalUrlHost falls back to "" — which
// isAllInterfacesHost treats as the wildcard. No `http://:PORT` garbage.
expect(defaultAllowedOrigins("", 8123)).toEqual([
"http://localhost:8123",
"http://127.0.0.1:8123",
"http://[::1]:8123",
"http://0.0.0.0:8123",
"http://[::]:8123",
]);
});
// Any wildcard spelling yields the loopback trio + the CANONICAL wildcard pair
// (0.0.0.0 / [::]) — not the typed spelling, which the browser canonicalizes
// away (HOST=0 / 0x0 / 0.0.0 all send http://0.0.0.0:PORT; ::0 sends [::]).
it.each(["0.0.0.0", "::", "::0", "0", "0x0", "0.0.0"])(
"returns the loopback trio + canonical wildcard pair for the all-interfaces host %j",
(host) => {
expect(defaultAllowedOrigins(host, 8123)).toEqual([
"http://localhost:8123",
"http://127.0.0.1:8123",
"http://[::1]:8123",
"http://0.0.0.0:8123",
"http://[::]:8123",
]);
},
);
it("lowercases a non-loopback hostname to match the browser's Origin", () => {
expect(defaultAllowedOrigins("Example.COM", 6274)).toEqual([
"http://example.com:6274",
]);
});
it("omits the port from the origin when it's the http default (80)", () => {
// Browsers drop :80 from the Origin header, and the guard is an exact
// match, so an origin with :80 could never match a real request.
expect(defaultAllowedOrigins("192.168.1.50", 80)).toEqual([
"http://192.168.1.50",
]);
expect(defaultAllowedOrigins("localhost", 80)).toEqual([
"http://localhost",
"http://127.0.0.1",
"http://[::1]",
]);
});
it("brackets a non-loopback IPv6 literal so it's a valid origin", () => {
expect(defaultAllowedOrigins("fe80::1", 6274)).toEqual([
"http://[fe80::1]:6274",
]);
});
});
describe("buildWebServerConfig", () => {
it("matches buildWebServerConfigFromEnv when initialMcpConfig is omitted", () => {
process.env[API_SERVER_ENV_VARS.AUTH_TOKEN] = "shared";
@ -239,7 +487,11 @@ describe("buildWebServerConfig", () => {
const cfg = buildWebServerConfig({ initialMcpConfig });
expect(cfg.port).toBe(7000);
expect(cfg.initialMcpConfig).toEqual(initialMcpConfig);
expect(cfg.allowedOrigins).toEqual(["http://localhost:7000"]);
expect(cfg.allowedOrigins).toEqual([
"http://localhost:7000",
"http://127.0.0.1:7000",
"http://[::1]:7000",
]);
});
it("preserves remote transport initialMcpConfig", () => {
@ -368,6 +620,31 @@ describe("printServerBanner", () => {
expect(url).toBe("http://localhost:6274");
});
it("brackets an IPv6 bind host in the printed URL", () => {
const cfg = baseConfig();
cfg.hostname = "::1";
const url = printServerBanner(cfg, 6274, "", undefined);
expect(url).toBe("http://[::1]:6274");
});
it("advertises localhost for a wildcard bind rather than the wildcard host", () => {
const cfg = baseConfig();
cfg.hostname = "0.0.0.0";
const url = printServerBanner(cfg, 6274, "", undefined);
expect(url).toBe("http://localhost:6274");
});
it("advertises the canonical (unmapped) host so banner ⊆ allowedOrigins", () => {
// An IPv4-mapped bind host: the allow-list emits the loopback trio (which
// includes http://127.0.0.1), so the banner must advertise a member of it,
// not the [::ffff:127.0.0.1] form (whose Origin is [::ffff:7f00:1]).
const cfg = baseConfig();
cfg.hostname = "::ffff:127.0.0.1";
const url = printServerBanner(cfg, 6274, "", undefined);
expect(url).toBe("http://127.0.0.1:6274");
expect(defaultAllowedOrigins(cfg.hostname, 6274)).toContain(url);
});
it("prints the sandbox URL when provided", () => {
printServerBanner(baseConfig(), 6274, "tok", "http://sandbox:9999/sandbox");
expect(

View file

@ -93,10 +93,22 @@ function browserExternalizedBuiltinGate(): Plugin {
// More info at: https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon
export default defineConfig(({ command }) => {
const isDevServer = command === "serve" && !process.env.VITEST;
// Build the validated dev backend config ONCE (when serving) and reuse it for
// both the Hono plugin and the `server` block below, so the dev server's
// `port`/`host` come from the same guard-checked source (`resolveBindHostname`
// + the CLIENT_PORT validation) rather than a second raw parse. This also
// removes the implicit "plugins must be evaluated before server" ordering the
// guard previously relied on to throw first.
const devConfig = isDevServer ? buildWebServerConfigFromEnv() : undefined;
return {
// `honoMiddlewarePlugin` is gated by `apply: 'serve'` so it only attaches
// during `vite dev` / `vite preview` — vitest projects share this config
// but never invoke `configureServer`, so the plugin stays inert there.
// `honoMiddlewarePlugin` only attaches during `vite dev` / `vite preview`.
// It's included conditionally on `isDevServer` (not merely `apply: 'serve'`)
// because `devConfig` (from `buildWebServerConfigFromEnv()`, which calls
// `resolveBindHostname()`) is built eagerly above. Left unconditional, an
// ambient `HOST=0.0.0.0` would make the guard throw at config load for
// `vite build` and every vitest project too, not just when serving. Gating
// the whole plugin also skips that wasted config build for non-serve
// commands.
//
// The plugin statically imports the node-only dev backend
// (`core/mcp/remote/node/server.ts`), so Vite's config bundler (Rolldown)
@ -113,7 +125,7 @@ export default defineConfig(({ command }) => {
// reaches the browser bundle (#1769) — see its definition above.
plugins: [
react(),
honoMiddlewarePlugin(buildWebServerConfigFromEnv()),
...(devConfig ? [honoMiddlewarePlugin(devConfig)] : []),
browserExternalizedBuiltinGate(),
],
// Shared optimizeDeps exclusions so node-only packages
@ -146,18 +158,26 @@ export default defineConfig(({ command }) => {
// location (which has no node_modules of its own yet).
dedupe: sharedDedupe,
},
// Pin the Vite dev server to the same port (and host) the Hono plugin
// configures from env, so `allowedOrigins` actually matches the browser
// origin. Without this, `vite dev` falls back to Vite's default 5173
// while the dev backend's `buildWebServerConfigFromEnv()` defaults to
// CLIENT_PORT=6274 — origin check rejects every `/api/*` request from
// the browser. CLIENT_PORT / HOST overrides flow through here too.
// `strictPort: true` so a port collision fails loudly instead of
// silently picking a different port (which would leave `allowedOrigins`
// pointing at the wrong host and break browser fetches).
// Pin the Vite dev server to the same port and host the Hono plugin
// configures, so `allowedOrigins` actually matches the browser origin.
// Without this, `vite dev` falls back to Vite's default 5173 while the dev
// backend defaults to CLIENT_PORT=6274 — origin check rejects every `/api/*`
// request. When serving, both come from the already-validated `devConfig`
// (guard-checked host + CLIENT_PORT); `vite build` and the vitest projects
// evaluate this config but never bind, so they fall back to the raw env
// (an ambient HOST=0.0.0.0 must not fail them at config load).
// `strictPort: true` so a port collision fails loudly instead of silently
// picking a different port (which would leave `allowedOrigins` wrong).
server: {
port: parseInt(process.env.CLIENT_PORT ?? "6274", 10),
host: process.env.HOST ?? "localhost",
// The `|| "6274"` (empty ⇒ unset) mirrors buildWebServerConfig, so the
// non-serve fallback agrees with the validated dev path on a blank
// CLIENT_PORT rather than parsing it to NaN.
port:
devConfig?.port ??
parseInt(process.env.CLIENT_PORT?.trim() || "6274", 10),
// `|| "localhost"` (empty ⇒ unset) like the port above — an ambient
// HOST="" is Node's all-interfaces address, the one value this guards.
host: devConfig?.hostname ?? (process.env.HOST?.trim() || "localhost"),
strictPort: true,
fs: {
allow: [path.resolve(dirname, "../..")],