@modelcontextprotocol/inspector 1.0.1 → 1.0.3

package/server/build/proxy-security.js

@@ -0,0 +1,154 @@
+/**
+ * SSRF-prevention helpers for the /fetch reverse proxy.
+ *
+ * Extracted from index.ts so they can be unit-tested independently.
+ *
+ * ## DNS-rebinding / TOCTOU threat model
+ *
+ * `assertSafeProxyTarget` resolves the target hostname and validates every
+ * returned IP against the block-list.  The resolved IPs are returned to the
+ * caller so they can be passed to `createPinnedAgent`, which builds an
+ * http/https.Agent whose `lookup` callback unconditionally returns the
+ * pre-validated IP.  The agent is then passed to `node-fetch`, which calls the
+ * lookup hook instead of doing its own DNS query.
+ *
+ * Without this pinning there is a TOCTOU race: an attacker who controls the
+ * target domain can flip its DNS record to 169.254.169.254 (AWS/GCP/Azure
+ * instance-metadata) in the window between `assertSafeProxyTarget` returning
+ * and `fetch` performing its own resolution.  Pinning eliminates that window.
+ */
+import http from "node:http";
+import https from "node:https";
+import { isIP } from "node:net";
+import { lookup as dnsLookup } from "node:dns/promises";
+// ---------------------------------------------------------------------------
+// Block-list
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if `ip` is a link-local or cloud-metadata address that must
+ * never be reachable through the proxy.
+ *
+ * Blocked ranges:
+ *  - 169.254.0.0/16  (IPv4 link-local; includes 169.254.169.254 IMDS)
+ *  - ::ffff:169.254.x.x  (IPv4-mapped IPv6 variants of the above)
+ *  - fe80::/10  (IPv6 link-local)
+ *  - fd00:ec2::254  (AWS IPv6 instance-metadata)
+ */
+export function isBlockedProxyAddress(ip) {
+    const kind = isIP(ip);
+    if (kind === 4) {
+        const parts = ip.split(".").map(Number);
+        return parts[0] === 169 && parts[1] === 254;
+    }
+    if (kind === 6) {
+        const addr = ip.toLowerCase();
+        // IPv4-mapped IPv6 — two serialization forms:
+        //   dotted   ::ffff:169.254.169.254
+        //   hex      ::ffff:a9fe:a9fe
+        const mapped = addr.match(/^::ffff:(.+)$/);
+        if (mapped) {
+            const tail = mapped[1];
+            if (isIP(tail) === 4) {
+                return isBlockedProxyAddress(tail);
+            }
+            const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+            if (hex) {
+                const high = parseInt(hex[1], 16);
+                const low = parseInt(hex[2], 16);
+                return isBlockedProxyAddress(`${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`);
+            }
+        }
+        if (/^fe[89ab]/.test(addr))
+            return true; // fe80::/10
+        return addr === "fd00:ec2::254"; // AWS IPv6 IMDS
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// DNS validation
+// ---------------------------------------------------------------------------
+/** Raised when the /fetch proxy is asked to reach a disallowed target. */
+export class ProxyTargetError extends Error {
+}
+/**
+ * Resolves `parsedUrl`'s hostname and asserts that every returned IP is
+ * outside the block-list.
+ *
+ * Returns the list of validated IP strings so the caller can pin one of them
+ * into an HTTP agent (see `createPinnedAgent`), eliminating the TOCTOU window
+ * between this check and the actual `fetch()` call.
+ *
+ * @throws {ProxyTargetError} if the host cannot be resolved or any resolved
+ *   address falls inside the block-list.
+ */
+export async function assertSafeProxyTarget(parsedUrl) {
+    const host = parsedUrl.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+    let addresses;
+    if (isIP(host)) {
+        addresses = [host];
+    }
+    else {
+        try {
+            addresses = (await dnsLookup(host, { all: true })).map((r) => r.address);
+        }
+        catch {
+            throw new ProxyTargetError(`Could not resolve host: ${host}`);
+        }
+    }
+    if (addresses.length === 0) {
+        throw new ProxyTargetError(`Could not resolve host: ${host}`);
+    }
+    for (const address of addresses) {
+        if (isBlockedProxyAddress(address)) {
+            throw new ProxyTargetError(`Refusing to proxy request to blocked address (${address})`);
+        }
+    }
+    return addresses;
+}
+// ---------------------------------------------------------------------------
+// IP-pinned agent factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates an `http.Agent` or `https.Agent` whose internal `lookup` hook always
+ * returns `pinnedIps`, bypassing the OS resolver entirely.
+ *
+ * Pass this agent to `node-fetch` on every hop of `safeProxyFetch` so the TCP
+ * connection always goes to an IP that was validated by `assertSafeProxyTarget`
+ * — even if the domain's DNS record changes mid-flight.
+ *
+ * Every address `assertSafeProxyTarget` returned is handed to the hook, not
+ * just the first, so Node keeps its normal address-family fallback: a
+ * dual-stack host whose first address is unreachable (IPv6 on an IPv4-only
+ * network, say) still connects via a later one. The set it may choose from is
+ * exactly the prevalidated set, so the TOCTOU guarantee is unchanged.
+ *
+ * @param protocol - `"http:"` or `"https:"` (from `URL.protocol`)
+ * @param pinnedIps - Validated IPv4/IPv6 address strings, in preference order
+ */
+export function createPinnedAgent(protocol, pinnedIps) {
+    if (pinnedIps.length === 0) {
+        throw new ProxyTargetError("No validated address to connect to");
+    }
+    const resolved = pinnedIps.map((address) => ({
+        address,
+        family: isIP(address) === 6 ? 6 : 4,
+    }));
+    // Node.js lookup signature: (hostname, options, callback).
+    //
+    // The callback shape depends on `options.all`. Node's `net.connect` runs with
+    // `autoSelectFamily` enabled by default (Node >= 20), so it calls the hook
+    // with `{ all: true }` and expects an ARRAY of `{ address, family }` — handing
+    // it the scalar form there fails the connection with ERR_INVALID_IP_ADDRESS.
+    // Both shapes are supported so the agent works on either call path.
+    const lookup = (_hostname, opts, callback) => {
+        if (opts?.all) {
+            callback(null, resolved);
+            return;
+        }
+        callback(null, resolved[0].address, resolved[0].family);
+    };
+    if (protocol === "https:") {
+        return new https.Agent({ lookup });
+    }
+    return new http.Agent({ lookup });
+}

package/server/build/request-guards.js

@@ -0,0 +1,83 @@
+/**
+ * Request guards for the proxy server: the auth-disable flag parser and the
+ * Origin validation middleware (which also applies the same-origin
+ * fetch-metadata check from fetch-metadata.ts).
+ *
+ * Extracted from index.ts so they can be unit-tested independently (index.ts
+ * starts listening on import).
+ */
+import { isExplicitTruthyFlag } from "./env-flags.js";
+import { shouldRejectSameOriginRequest } from "./fetch-metadata.js";
+/**
+ * Parses the value of `DANGEROUSLY_OMIT_AUTH`.
+ *
+ * Only an explicit truthy value (`true`, `1` or `yes`, case-insensitive,
+ * surrounding whitespace ignored) disables authentication. Anything else —
+ * unset, empty, `false`, `0`, or an unrecognized value — leaves auth enabled.
+ *
+ * `client/bin/start.js` carries an identical copy of this function so the
+ * launcher and the proxy always agree on whether auth is disabled; keep the
+ * two in sync.
+ */
+export function isAuthDisabledFlag(value) {
+    return isExplicitTruthyFlag(value);
+}
+/**
+ * Returns the list of origins allowed to talk to the proxy: the
+ * comma-separated `ALLOWED_ORIGINS` environment variable, or the client's
+ * default origin (`http://localhost:${CLIENT_PORT}`, port 6274 by default).
+ */
+export function getAllowedOrigins(env = process.env) {
+    const clientPort = env.CLIENT_PORT || "6274";
+    const defaultOrigin = `http://localhost:${clientPort}`;
+    return env.ALLOWED_ORIGINS?.split(",") || [defaultOrigin];
+}
+/**
+ * Builds the Origin validation middleware.
+ *
+ * A request carrying an `Origin` header that is not in the allowed list is
+ * always rejected with 403.
+ *
+ * A request with no `Origin` header is handled according to `authDisabled`:
+ * - auth enabled: it passes this check. Non-browser clients legitimately send
+ *   no `Origin`, and the session token checked by the auth middleware is what
+ *   protects them.
+ * - auth disabled: it is rejected with the same 403. With no token to check,
+ *   the `Origin` header is the only thing tying a request to the Inspector web
+ *   client, whose requests to the proxy are cross-origin and always carry one.
+ *
+ * Before either of those, a same-origin browser request
+ * (`Sec-Fetch-Site: same-origin`) is rejected with 403 unless
+ * `allowSameOriginApi` is true (`DANGEROUSLY_ALLOW_SAME_ORIGIN_API`). Such a
+ * request carries no `Origin` header, so the allow-list cannot see it; see
+ * fetch-metadata.ts.
+ */
+export function createOriginValidationMiddleware(authDisabled, allowSameOriginApi = false) {
+    return (req, res, next) => {
+        // A same-origin request carries no Origin header, so the allow-list below
+        // cannot see it. The client never shares the proxy's origin; only documents
+        // the proxy serves itself (the MCP Apps sandbox) do. See fetch-metadata.ts.
+        if (shouldRejectSameOriginRequest(req.headers, allowSameOriginApi)) {
+            console.error("Rejected same-origin request to an API route");
+            res.status(403).json({
+                error: "Forbidden - same-origin request",
+                message: "API routes cannot be called from documents served by the proxy.",
+            });
+            return;
+        }
+        const origin = req.headers.origin;
+        const allowedOrigins = getAllowedOrigins();
+        const rejected = origin ? !allowedOrigins.includes(origin) : authDisabled;
+        if (rejected) {
+            console.error(origin
+                ? `Invalid origin: ${origin}`
+                : "Missing origin (required when authentication is disabled)");
+            res.status(403).json({
+                error: "Forbidden - invalid origin",
+                message: "Request blocked to prevent DNS rebinding attacks. Configure allowed origins via environment variable.",
+            });
+            return;
+        }
+        next();
+    };
+}