@juspay/neurolink 13.8.16 → 13.8.18

package/dist/mcp/mcpClientFactory.js

@@ -10,6 +10,7 @@ import { CircuitBreakerOpenError } from "../types/index.js";
 import { withHTTPRetry, DEFAULT_HTTP_RETRY_CONFIG, } from "./httpRetryHandler.js";
 import { globalRateLimiterManager } from "./httpRateLimiter.js";
 import { NeuroLinkOAuthProvider, InMemoryTokenStorage } from "./auth/index.js";
+import { assertMcpTransportUrlAllowed } from "./transportUrlPolicy.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /**
@@ -197,8 +198,13 @@ export class MCPClientFactory {
         name: "neurolink-sdk",
         version: "1.0.0",
     };
+    /**
+     * No `sampling` here: advertising it tells a server it may send
+     * `sampling/createMessage` and have this client run an LLM call on its
+     * behalf, and the client has no handler for it. Only what is implemented
+     * is announced.
+     */
     static DEFAULT_CAPABILITIES = {
-        sampling: {},
         roots: {
             listChanged: false,
         },
@@ -396,15 +402,36 @@ export class MCPClientFactory {
             case "stdio":
                 return this.createStdioTransport(config);
             case "sse":
+                await this.assertNetworkUrlAllowed(config);
                 return this.createSSETransport(config);
             case "websocket":
+                await this.assertNetworkUrlAllowed(config);
                 return this.createWebSocketTransport(config);
             case "http":
+                await this.assertNetworkUrlAllowed(config);
                 return this.createHTTPTransport(config);
             default:
                 throw new Error(`Unsupported transport type: ${config.transport}`);
         }
     }
+    /**
+     * Apply the transport URL policy (`transportUrlPolicy.ts`) before any
+     * network transport is built: TLS unless loopback, and no private,
+     * link-local or metadata destinations unless the server config says
+     * `allowPrivateNetwork: true`. Runs for every network server, whether it
+     * came from a project config or from `addExternalMCPServer`.
+     */
+    static async assertNetworkUrlAllowed(config) {
+        if (!config.url) {
+            throw new Error(`URL is required for ${config.transport} transport`);
+        }
+        await assertMcpTransportUrlAllowed(config.url, {
+            transport: config.transport,
+            allowPrivateNetwork: config.allowPrivateNetwork,
+            hostOwnedEgress: typeof config.fetch === "function",
+            serverId: config.id,
+        });
+    }
     /**
      * Create a stdio transport.
      *
@@ -431,13 +458,23 @@ export class MCPClientFactory {
         if (!config.command) {
             throw new Error(`Command is required for stdio transport`);
         }
-        const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+        const { StdioClientTransport, getDefaultEnvironment } = await import("@modelcontextprotocol/sdk/client/stdio.js");
         const { ChildProcess: childProcessClass } = await import("node:child_process");
+        // The child gets the SDK's minimal default environment (HOME, PATH,
+        // SHELL, TERM, USER, LOGNAME on POSIX) plus the server's own `env`. It
+        // used to get the whole parent `process.env` — every provider key and
+        // token this process held — and an `npx -y <package>` server is exactly
+        // the kind of code that should not. `inheritParentEnv: true` restores
+        // the old behaviour for a server that needs it; a single variable is
+        // better passed through explicitly: `"env": {"X": "${X}"}`.
+        const baseEnv = config.inheritParentEnv === true
+            ? { ...process.env }
+            : getDefaultEnvironment();
         const transport = new StdioClientTransport({
             command: config.command,
             args: config.args || [],
             env: Object.fromEntries(Object.entries({
-                ...process.env,
+                ...baseEnv,
                 ...config.env,
             })
                 .filter(([, value]) => value !== undefined)
@@ -495,15 +532,41 @@ export class MCPClientFactory {
         mcpLogger.debug(`[MCPClientFactory] Creating WebSocket transport for ${config.id}`, {
             url: config.url,
         });
+        // The SDK's WebSocket transport opens the platform `WebSocket`, which
+        // takes a URL and a subprotocol and nothing else: there is no way to
+        // send `headers` or an `auth` token with the handshake. Dropping them
+        // silently would connect unauthenticated to a server the operator
+        // configured credentials for, so this fails closed instead.
+        const headerCount = Object.keys(config.headers ?? {}).length;
+        if (headerCount > 0 || config.auth !== undefined) {
+            throw new Error(`WebSocket transport for ${config.id} cannot send the configured ${headerCount > 0 ? "headers" : "auth"}: the WebSocket handshake carries no custom headers. Use the "http" or "sse" transport for an authenticated server, or remove the credentials.`);
+        }
+        let url;
+        let transportModule;
         try {
-            const url = new URL(config.url);
-            const { WebSocketClientTransport } = await import("@modelcontextprotocol/sdk/client/websocket.js");
-            const transport = new WebSocketClientTransport(url);
-            return { transport };
+            url = new URL(config.url);
+            transportModule =
+                await import("@modelcontextprotocol/sdk/client/websocket.js");
         }
         catch (error) {
             throw new Error(`Invalid WebSocket URL: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
+        const transport = new transportModule.WebSocketClientTransport(url);
+        // Same connect bound as the HTTP transports: a socket that never opens
+        // or errors would otherwise leave `connect()` pending for the whole
+        // client timeout. On expiry the socket is closed so nothing lingers.
+        const connectTimeoutMs = config.httpOptions?.connectionTimeout ?? 30000;
+        const start = transport.start.bind(transport);
+        transport.start = async () => {
+            try {
+                await this.raceWithTimeout(start(), connectTimeoutMs, `WebSocket connection timeout for ${config.id} after ${connectTimeoutMs}ms`);
+            }
+            catch (error) {
+                await transport.close().catch(() => undefined);
+                throw error;
+            }
+        };
+        return { transport };
     }
     /**
      * Create HTTP transport (Streamable HTTP)

package/dist/mcp/projectConfigTrust.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Trust for a project's `.mcp-config.json`.
+ *
+ * A directory is not a trust boundary. Every tool-enabled `generate()` and
+ * `stream()` used to load `<cwd>/.mcp-config.json` and start what it named,
+ * so cloning a repository and running anything built on this SDK inside it
+ * ran that repository's commands with the user's credentials. This module
+ * is the one place that decides whether a project config may be loaded:
+ *
+ * - **SDK**: never implicitly. `new NeuroLink({ mcp: { configPath } })` names
+ *   a file; `mcp: { trustProjectConfig: true }` opts into the working
+ *   directory. `ProviderRegistry.setOptions({ enableManualMCP: true })` is the
+ *   legacy opt-in and is honoured for the first time.
+ * - **CLI**: the entry point hashes the file, compares it with the accepted
+ *   hashes in `~/.neurolink/trusted-mcp-configs.json`, and registers a hook
+ *   here. The hook runs only when a `NeuroLink` instance is about to load
+ *   the file, so `neurolink --version` in a hostile directory costs nothing
+ *   and `neurolink generate` there is refused.
+ */
+import type { ProjectMcpConfigPathResolution, ProjectMcpConfigSummary, ProjectMcpConfigTrustHook, ProjectMcpConfigTrustStatus, ProjectMcpConfigTrustStore } from "../types/index.js";
+export declare const PROJECT_MCP_CONFIG_FILENAME = ".mcp-config.json";
+export declare const TRUSTED_MCP_CONFIGS_FILENAME = "trusted-mcp-configs.json";
+/** `1` trusts the working directory's config for this run; `0` ignores it. */
+export declare const TRUST_MCP_CONFIG_ENV = "NEUROLINK_TRUST_MCP_CONFIG";
+/** CLI flag with the same meaning as `NEUROLINK_TRUST_MCP_CONFIG=1`. */
+export declare const TRUST_MCP_CONFIG_FLAG = "--trust-mcp-config";
+export declare function getTrustedMcpConfigStorePath(): string;
+export declare function hashProjectMcpConfig(content: string | Buffer): string;
+/**
+ * Read the store. A missing, unreadable or malformed file reads as empty:
+ * the only consequence is that every config has to be accepted again, which
+ * is the safe direction.
+ */
+export declare function readProjectMcpConfigTrustStore(storePath?: string): ProjectMcpConfigTrustStore;
+export declare function getProjectMcpConfigTrustStatus(configPath: string, sha256: string, storePath?: string): ProjectMcpConfigTrustStatus;
+/**
+ * Record an acceptance. The store directory is created `0700`, the file is
+ * written `0600` through a uniquely named temporary file opened with `wx`
+ * and renamed into place, so a concurrent writer or a pre-planted symlink
+ * cannot redirect the write or leave a torn file.
+ */
+export declare function recordTrustedProjectMcpConfig(configPath: string, sha256: string, storePath?: string): void;
+/**
+ * Read and describe a project config without evaluating any of it. Values
+ * under `env` and `headers` are never included — a summary is printed to a
+ * terminal and must not echo a secret the file happens to inline.
+ */
+export declare function summarizeProjectMcpConfig(configPath: string): ProjectMcpConfigSummary;
+/** Render a summary as the lines the CLI prints before asking for trust. */
+export declare function formatProjectMcpConfigSummary(summary: ProjectMcpConfigSummary): string[];
+/**
+ * Register (or clear, with `null`) the process-wide hook the CLI uses to hand
+ * its trust decision to every `NeuroLink` instance built afterwards. SDK
+ * hosts do not need this: they pass `mcp.configPath` or
+ * `mcp.trustProjectConfig` to the constructor instead.
+ */
+export declare function setProjectMcpConfigTrustHook(hook: ProjectMcpConfigTrustHook | null): void;
+export declare function getProjectMcpConfigTrustHook(): ProjectMcpConfigTrustHook | null;
+/**
+ * Decide which project config, if any, a `NeuroLink` instance loads.
+ *
+ * Precedence: an explicit `configPath`; `trustProjectConfig` for
+ * `<cwd>/.mcp-config.json`; the CLI's registered hook; the legacy
+ * `enableManualMCP` registry option. With none of them the answer is `null`
+ * and nothing is read from the working directory — the SDK default.
+ */
+export declare function resolveProjectMcpConfigPath(options: {
+    cwd?: string;
+    configPath?: string;
+    trustProjectConfig?: boolean;
+    enableManualMCP?: boolean;
+}): Promise<ProjectMcpConfigPathResolution | null>;

package/dist/mcp/projectConfigTrust.js

@@ -0,0 +1,237 @@
+/**
+ * Trust for a project's `.mcp-config.json`.
+ *
+ * A directory is not a trust boundary. Every tool-enabled `generate()` and
+ * `stream()` used to load `<cwd>/.mcp-config.json` and start what it named,
+ * so cloning a repository and running anything built on this SDK inside it
+ * ran that repository's commands with the user's credentials. This module
+ * is the one place that decides whether a project config may be loaded:
+ *
+ * - **SDK**: never implicitly. `new NeuroLink({ mcp: { configPath } })` names
+ *   a file; `mcp: { trustProjectConfig: true }` opts into the working
+ *   directory. `ProviderRegistry.setOptions({ enableManualMCP: true })` is the
+ *   legacy opt-in and is honoured for the first time.
+ * - **CLI**: the entry point hashes the file, compares it with the accepted
+ *   hashes in `~/.neurolink/trusted-mcp-configs.json`, and registers a hook
+ *   here. The hook runs only when a `NeuroLink` instance is about to load
+ *   the file, so `neurolink --version` in a hostile directory costs nothing
+ *   and `neurolink generate` there is refused.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import * as path from "node:path";
+import { isNonNullObject } from "../utils/typeUtils.js";
+export const PROJECT_MCP_CONFIG_FILENAME = ".mcp-config.json";
+export const TRUSTED_MCP_CONFIGS_FILENAME = "trusted-mcp-configs.json";
+/** `1` trusts the working directory's config for this run; `0` ignores it. */
+export const TRUST_MCP_CONFIG_ENV = "NEUROLINK_TRUST_MCP_CONFIG";
+/** CLI flag with the same meaning as `NEUROLINK_TRUST_MCP_CONFIG=1`. */
+export const TRUST_MCP_CONFIG_FLAG = "--trust-mcp-config";
+const MAX_SUMMARY_ARGS_LENGTH = 160;
+export function getTrustedMcpConfigStorePath() {
+    return path.join(homedir(), ".neurolink", TRUSTED_MCP_CONFIGS_FILENAME);
+}
+export function hashProjectMcpConfig(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function emptyStore() {
+    return { version: 1, entries: {} };
+}
+function isTrustStore(value) {
+    if (!isNonNullObject(value)) {
+        return false;
+    }
+    const record = value;
+    if (record.version !== 1 || !isNonNullObject(record.entries)) {
+        return false;
+    }
+    return Object.values(record.entries).every((entry) => isNonNullObject(entry) &&
+        typeof entry.sha256 === "string" &&
+        typeof entry.trustedAt === "string");
+}
+/**
+ * Read the store. A missing, unreadable or malformed file reads as empty:
+ * the only consequence is that every config has to be accepted again, which
+ * is the safe direction.
+ */
+export function readProjectMcpConfigTrustStore(storePath = getTrustedMcpConfigStorePath()) {
+    try {
+        const parsed = JSON.parse(readFileSync(storePath, "utf8"));
+        return isTrustStore(parsed) ? parsed : emptyStore();
+    }
+    catch {
+        return emptyStore();
+    }
+}
+export function getProjectMcpConfigTrustStatus(configPath, sha256, storePath = getTrustedMcpConfigStorePath()) {
+    const entry = readProjectMcpConfigTrustStore(storePath).entries[path.resolve(configPath)];
+    if (!entry) {
+        return "untrusted";
+    }
+    return entry.sha256 === sha256 ? "trusted" : "changed";
+}
+/**
+ * Record an acceptance. The store directory is created `0700`, the file is
+ * written `0600` through a uniquely named temporary file opened with `wx`
+ * and renamed into place, so a concurrent writer or a pre-planted symlink
+ * cannot redirect the write or leave a torn file.
+ */
+export function recordTrustedProjectMcpConfig(configPath, sha256, storePath = getTrustedMcpConfigStorePath()) {
+    const store = readProjectMcpConfigTrustStore(storePath);
+    store.entries[path.resolve(configPath)] = {
+        sha256,
+        trustedAt: new Date().toISOString(),
+    };
+    const dir = path.dirname(storePath);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${storePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", {
+            mode: 0o600,
+            flag: "wx",
+        });
+        renameSync(tmp, storePath);
+        chmodSync(storePath, 0o600);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+function summarizeServer(id, value) {
+    if (!isNonNullObject(value)) {
+        return { id, transport: "invalid" };
+    }
+    const record = value;
+    const transport = typeof record.transport === "string"
+        ? record.transport
+        : typeof record.url === "string"
+            ? "http"
+            : "stdio";
+    const summary = { id, transport };
+    if (typeof record.command === "string") {
+        summary.command = record.command;
+    }
+    if (Array.isArray(record.args)) {
+        summary.args = record.args.map((arg) => String(arg));
+    }
+    if (typeof record.url === "string") {
+        summary.url = record.url;
+    }
+    if (isNonNullObject(record.env)) {
+        summary.envKeys = Object.keys(record.env);
+    }
+    return summary;
+}
+/**
+ * Read and describe a project config without evaluating any of it. Values
+ * under `env` and `headers` are never included — a summary is printed to a
+ * terminal and must not echo a secret the file happens to inline.
+ */
+export function summarizeProjectMcpConfig(configPath) {
+    const absolute = path.resolve(configPath);
+    const bytes = readFileSync(absolute);
+    const summary = {
+        path: absolute,
+        sha256: hashProjectMcpConfig(bytes),
+        servers: [],
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+    }
+    catch (error) {
+        summary.parseError = `not valid JSON (${error instanceof Error ? error.message : String(error)})`;
+        return summary;
+    }
+    if (!isNonNullObject(parsed) ||
+        !isNonNullObject(parsed.mcpServers)) {
+        summary.parseError = 'no "mcpServers" object';
+        return summary;
+    }
+    const servers = parsed.mcpServers;
+    for (const [id, value] of Object.entries(servers)) {
+        summary.servers.push(summarizeServer(id, value));
+    }
+    return summary;
+}
+/** Render a summary as the lines the CLI prints before asking for trust. */
+export function formatProjectMcpConfigSummary(summary) {
+    const lines = [`${summary.path}  (sha256 ${summary.sha256.slice(0, 16)}…)`];
+    if (summary.parseError) {
+        lines.push(`  ${summary.parseError}`);
+        return lines;
+    }
+    if (summary.servers.length === 0) {
+        lines.push("  declares no servers");
+        return lines;
+    }
+    lines.push(`  declares ${summary.servers.length} server(s):`);
+    for (const server of summary.servers) {
+        let what;
+        if (server.command !== undefined) {
+            const argv = [server.command, ...(server.args ?? [])].join(" ");
+            what =
+                argv.length > MAX_SUMMARY_ARGS_LENGTH
+                    ? `${argv.slice(0, MAX_SUMMARY_ARGS_LENGTH)}…`
+                    : argv;
+        }
+        else if (server.url !== undefined) {
+            what = server.url;
+        }
+        else {
+            what = "(neither command nor url)";
+        }
+        const env = server.envKeys && server.envKeys.length > 0
+            ? `  env: ${server.envKeys.join(", ")}`
+            : "";
+        lines.push(`  - ${server.id}  [${server.transport}]  ${what}${env}`);
+    }
+    return lines;
+}
+let trustHook = null;
+/**
+ * Register (or clear, with `null`) the process-wide hook the CLI uses to hand
+ * its trust decision to every `NeuroLink` instance built afterwards. SDK
+ * hosts do not need this: they pass `mcp.configPath` or
+ * `mcp.trustProjectConfig` to the constructor instead.
+ */
+export function setProjectMcpConfigTrustHook(hook) {
+    trustHook = hook;
+}
+export function getProjectMcpConfigTrustHook() {
+    return trustHook;
+}
+/**
+ * Decide which project config, if any, a `NeuroLink` instance loads.
+ *
+ * Precedence: an explicit `configPath`; `trustProjectConfig` for
+ * `<cwd>/.mcp-config.json`; the CLI's registered hook; the legacy
+ * `enableManualMCP` registry option. With none of them the answer is `null`
+ * and nothing is read from the working directory — the SDK default.
+ */
+export async function resolveProjectMcpConfigPath(options) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.configPath !== undefined && options.configPath.length > 0) {
+        return {
+            path: path.resolve(cwd, options.configPath),
+            source: "configPath",
+        };
+    }
+    const candidate = path.join(cwd, PROJECT_MCP_CONFIG_FILENAME);
+    if (options.trustProjectConfig === true) {
+        return { path: candidate, source: "trustProjectConfig" };
+    }
+    if (trustHook) {
+        if (!existsSync(candidate)) {
+            return null;
+        }
+        const accepted = await trustHook(candidate);
+        return accepted ? { path: accepted, source: "cliTrust" } : null;
+    }
+    if (options.enableManualMCP === true) {
+        return { path: candidate, source: "enableManualMCP" };
+    }
+    return null;
+}

package/dist/mcp/transportUrlPolicy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * URL policy for the network MCP transports (http, sse, websocket).
+ *
+ * An MCP server URL names where every tool call, and every configured
+ * header, is sent. Until this policy existed, nothing checked it: a project
+ * config could point a server at `http://169.254.169.254/` or at an
+ * attacker's plaintext host and the SDK would connect. The rules, in order:
+ *
+ *  1. The scheme is one of `https:`, `wss:`, `http:`, `ws:`.
+ *  2. A loopback host (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`) may
+ *     use any of the four. Local development servers are the common case
+ *     for plaintext and they never leave the machine.
+ *  3. Otherwise plaintext is refused, and a host that is — or resolves to —
+ *     a private, link-local, CGNAT, multicast or cloud-metadata address is
+ *     refused too, so a tool call cannot be turned into a request against
+ *     the machine's own network.
+ *  4. `allowPrivateNetwork: true` on that server's config lifts rule 3 for
+ *     private addresses, and lets plaintext reach them. A public host still
+ *     needs TLS.
+ *
+ * `utils/ssrfGuard.ts` is deliberately not reused: it is HTTPS-only and treats
+ * loopback as blocked, which is right for a server fetching an untrusted URL
+ * and wrong for a client talking to a local MCP server.
+ */
+import type { McpTransportAddressClass, McpTransportUrlPolicyOptions } from "../types/index.js";
+/**
+ * Classify one IP literal. Throws when `ip` is not an IP address at all, so a
+ * caller never silently treats a host name as public.
+ */
+export declare function classifyMcpTransportAddress(ip: string): McpTransportAddressClass;
+/**
+ * Enforce the policy described in this module's header on `rawUrl`.
+ *
+ * Rejection is an `Error` whose message names the rule and, where one
+ * applies, the opt-out (`allowPrivateNetwork`). The URL itself is quoted so
+ * an operator can find the offending server entry; it never carries
+ * credentials, because `headers` are not part of the URL.
+ */
+export declare function assertMcpTransportUrlAllowed(rawUrl: string, options: McpTransportUrlPolicyOptions): Promise<void>;

package/dist/mcp/transportUrlPolicy.js

@@ -0,0 +1,172 @@
+/**
+ * URL policy for the network MCP transports (http, sse, websocket).
+ *
+ * An MCP server URL names where every tool call, and every configured
+ * header, is sent. Until this policy existed, nothing checked it: a project
+ * config could point a server at `http://169.254.169.254/` or at an
+ * attacker's plaintext host and the SDK would connect. The rules, in order:
+ *
+ *  1. The scheme is one of `https:`, `wss:`, `http:`, `ws:`.
+ *  2. A loopback host (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`) may
+ *     use any of the four. Local development servers are the common case
+ *     for plaintext and they never leave the machine.
+ *  3. Otherwise plaintext is refused, and a host that is — or resolves to —
+ *     a private, link-local, CGNAT, multicast or cloud-metadata address is
+ *     refused too, so a tool call cannot be turned into a request against
+ *     the machine's own network.
+ *  4. `allowPrivateNetwork: true` on that server's config lifts rule 3 for
+ *     private addresses, and lets plaintext reach them. A public host still
+ *     needs TLS.
+ *
+ * `utils/ssrfGuard.ts` is deliberately not reused: it is HTTPS-only and treats
+ * loopback as blocked, which is right for a server fetching an untrusted URL
+ * and wrong for a client talking to a local MCP server.
+ */
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+const PLAINTEXT_SCHEMES = new Set(["http:", "ws:"]);
+const TLS_SCHEMES = new Set(["https:", "wss:"]);
+const LOOPBACK_ADDRESSES = new BlockList();
+LOOPBACK_ADDRESSES.addSubnet("127.0.0.0", 8, "ipv4");
+LOOPBACK_ADDRESSES.addAddress("::1", "ipv6");
+/**
+ * Non-public ranges: RFC 1918, link-local (which holds the AWS/GCP/Azure
+ * metadata endpoint), CGNAT (which holds Alibaba's), "this network",
+ * protocol assignments, benchmarking, multicast, reserved, and the IPv6
+ * unspecified, unique-local and link-local ranges. `BlockList` checks an
+ * IPv4-mapped IPv6 address against the IPv4 rules on its own.
+ */
+const PRIVATE_ADDRESSES = new BlockList();
+PRIVATE_ADDRESSES.addSubnet("0.0.0.0", 8, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("10.0.0.0", 8, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("100.64.0.0", 10, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("169.254.0.0", 16, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("172.16.0.0", 12, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("192.0.0.0", 24, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("192.168.0.0", 16, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("198.18.0.0", 15, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("224.0.0.0", 4, "ipv4");
+PRIVATE_ADDRESSES.addSubnet("240.0.0.0", 4, "ipv4");
+PRIVATE_ADDRESSES.addAddress("::", "ipv6");
+PRIVATE_ADDRESSES.addSubnet("fc00::", 7, "ipv6");
+PRIVATE_ADDRESSES.addSubnet("fe80::", 10, "ipv6");
+function stripBrackets(host) {
+    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function isLoopbackName(host) {
+    const name = host.endsWith(".") ? host.slice(0, -1) : host;
+    return name === "localhost" || name.endsWith(".localhost");
+}
+/**
+ * Classify one IP literal. Throws when `ip` is not an IP address at all, so a
+ * caller never silently treats a host name as public.
+ */
+export function classifyMcpTransportAddress(ip) {
+    const family = isIP(ip);
+    if (family === 0) {
+        throw new Error(`"${ip}" is not an IP address`);
+    }
+    const type = family === 4 ? "ipv4" : "ipv6";
+    if (LOOPBACK_ADDRESSES.check(ip, type)) {
+        return "loopback";
+    }
+    if (PRIVATE_ADDRESSES.check(ip, type)) {
+        return "private";
+    }
+    return "public";
+}
+function describe(options) {
+    return options.serverId
+        ? `MCP server "${options.serverId}" (${options.transport})`
+        : `MCP ${options.transport} transport`;
+}
+async function resolveHostAddresses(host) {
+    const records = await lookup(host, { all: true, verbatim: true });
+    return records.map((record) => record.address);
+}
+/**
+ * Enforce the policy described in this module's header on `rawUrl`.
+ *
+ * Rejection is an `Error` whose message names the rule and, where one
+ * applies, the opt-out (`allowPrivateNetwork`). The URL itself is quoted so
+ * an operator can find the offending server entry; it never carries
+ * credentials, because `headers` are not part of the URL.
+ */
+export async function assertMcpTransportUrlAllowed(rawUrl, options) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`${describe(options)}: "${rawUrl}" is not a valid URL`);
+    }
+    const scheme = url.protocol;
+    const tls = TLS_SCHEMES.has(scheme);
+    if (!tls && !PLAINTEXT_SCHEMES.has(scheme)) {
+        throw new Error(`${describe(options)}: scheme "${scheme}" is not allowed (use https:, wss:, or http:/ws: for a loopback host)`);
+    }
+    const host = stripBrackets(url.hostname).toLowerCase();
+    if (host.length === 0) {
+        throw new Error(`${describe(options)}: "${rawUrl}" has no host`);
+    }
+    // A host-supplied fetch/dispatcher owns the connection (the egress suites
+    // pin DNS through exactly such a fetch); judging the hostname here would
+    // refuse names only that resolver knows. The scheme check above still ran.
+    if (options.hostOwnedEgress === true) {
+        return;
+    }
+    const allowPrivate = options.allowPrivateNetwork === true;
+    const literalClass = isLoopbackName(host)
+        ? "loopback"
+        : isIP(host) !== 0
+            ? classifyMcpTransportAddress(host)
+            : undefined;
+    if (literalClass !== undefined) {
+        if (literalClass === "loopback") {
+            return;
+        }
+        if (!allowPrivate) {
+            if (literalClass === "private") {
+                throw new Error(`${describe(options)}: "${rawUrl}" points at a private, link-local or metadata address; set "allowPrivateNetwork": true on this server if that is intended`);
+            }
+            if (!tls) {
+                throw new Error(`${describe(options)}: "${rawUrl}" uses plaintext ${scheme} to a non-loopback host; use ${scheme === "ws:" ? "wss:" : "https:"}`);
+            }
+            return;
+        }
+        if (literalClass === "public" && !tls) {
+            throw new Error(`${describe(options)}: "${rawUrl}" uses plaintext ${scheme} to a public host; allowPrivateNetwork only permits plaintext to private addresses`);
+        }
+        return;
+    }
+    // A host name. Plaintext to anything that is not a loopback literal or
+    // `localhost` is refused before any lookup, so a hostile config cannot
+    // make the decision depend on what its own DNS answers.
+    if (!tls && !allowPrivate) {
+        throw new Error(`${describe(options)}: "${rawUrl}" uses plaintext ${scheme} to a non-loopback host; use ${scheme === "ws:" ? "wss:" : "https:"}, or set "allowPrivateNetwork": true for a server on your own network`);
+    }
+    let addresses;
+    try {
+        addresses = await resolveHostAddresses(host);
+    }
+    catch (error) {
+        throw new Error(`${describe(options)}: host "${host}" could not be resolved (${error instanceof Error ? error.message : String(error)})`, { cause: error });
+    }
+    if (addresses.length === 0) {
+        throw new Error(`${describe(options)}: host "${host}" resolved to no addresses`);
+    }
+    const classes = addresses.map((address) => ({
+        address,
+        cls: classifyMcpTransportAddress(address),
+    }));
+    if (!allowPrivate) {
+        const nonPublic = classes.find((entry) => entry.cls !== "public");
+        if (nonPublic) {
+            throw new Error(`${describe(options)}: host "${host}" resolves to ${nonPublic.address}, a ${nonPublic.cls} address; set "allowPrivateNetwork": true on this server if that is intended`);
+        }
+        return;
+    }
+    if (!tls && classes.some((entry) => entry.cls === "public")) {
+        throw new Error(`${describe(options)}: "${rawUrl}" uses plaintext ${scheme} to a host that resolves to a public address; allowPrivateNetwork only permits plaintext to private addresses`);
+    }
+}