@wrongstack/mcp 0.320.1 → 1.0.0

package/dist/client.d.ts

@@ -23,6 +23,12 @@ export interface MCPClientOptions {
      * without storing them in config.json or being scrubbed by the secret filter.
      */
     passthroughEnv?: string[] | undefined;
+    /**
+     * Resolution-bound private-network policy for HTTP transports. Default:
+     * private/LAN targets are blocked at dial time (DNS-rebinding safe); the
+     * flag opts this server in. See MCPServerConfig.allowPrivateNetworks.
+     */
+    allowPrivateNetworks?: boolean | undefined;
 }
 import type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult } from './contracts.js';
 export type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult };
@@ -56,6 +62,7 @@ export declare class MCPClient {
      */
     private readonly pending;
     private rxBuffer;
+    private rxBufferBytes;
     private _tools;
     /** Server-declared handshake metadata. Populated for stdio in the first protocol slice. */
     private _serverMetadata?;

package/dist/index.js

@@ -516,8 +516,8 @@ async function resolvePinnedAddress(url, options) {
     );
     return { address: hostname, family: literalFamily };
   }
-  const lookup2 = options.lookup ?? ((host) => dns.lookup(host, { all: true }));
-  const records = await lookup2(hostname);
+  const lookup3 = options.lookup ?? ((host) => dns.lookup(host, { all: true }));
+  const records = await lookup3(hostname);
   if (records.length === 0)
     throw new Error(`MCP OAuth discovery DNS returned no addresses for ${hostname}`);
   for (const record3 of records) {
@@ -1256,10 +1256,13 @@ var SSEReader = class {
 // src/transport-base.ts
 import * as https2 from "node:https";
 import { ConfigError as ConfigError2 } from "@wrongstack/core/types";
+import { Agent as UndiciAgent, fetch as undiciFetch } from "undici";
 
 // src/transport-security.ts
+import * as dns2 from "node:dns/promises";
 import * as net2 from "node:net";
 import { ConfigError } from "@wrongstack/core/types";
+import { isPrivateIPv4 as isPrivateIPv42, isPrivateIPv6 as isPrivateIPv62 } from "@wrongstack/core/utils";
 function isTlsUnsafeAllowed() {
   return process.env["WRONGSTACK_UNSAFE_MCP_TLS"] === "1";
 }
@@ -1315,9 +1318,108 @@ function validateTransportUrl(rawUrl) {
     }
   }
 }
+var ALLOW_MCP_PRIVATE_NETWORKS = process.env["WRONGSTACK_MCP_ALLOW_PRIVATE"] === "1";
+if (ALLOW_MCP_PRIVATE_NETWORKS && !process.env["CI"]) {
+  console.warn(
+    "[WrongStack] WARNING: WRONGSTACK_MCP_ALLOW_PRIVATE=1 is active \u2014\n  MCP HTTP transports may dial private/LAN addresses (10.x, 192.168.x,\n  172.16-31.x, ULA) when a server config sets allowPrivateNetworks. Link-local/IMDS targets stay blocked."
+  );
+}
+function classifyTransportAddress(address, family) {
+  if (family === 4) {
+    const v4 = address.toLowerCase();
+    if (v4.startsWith("169.254.")) return "blocked";
+    if (v4.startsWith("127.")) return "loopback";
+    return isPrivateIPv42(address) ? "private" : "public";
+  }
+  if (family === 6) {
+    const v6 = address.toLowerCase();
+    if (v6 === "::1") return "loopback";
+    if (/^fe[89ab]/.test(v6) || v6 === "fd00:ec2::254") return "blocked";
+    if (v6.startsWith("::ffff:")) {
+      const tail = v6.slice("::ffff:".length);
+      if (tail.includes(".")) return classifyTransportAddress(tail, 4);
+      const hextets = tail.split(":");
+      if (hextets.length === 2) {
+        const high = Number.parseInt(hextets[0], 16);
+        const low = Number.parseInt(hextets[1], 16);
+        if (Number.isFinite(high) && Number.isFinite(low)) {
+          return classifyTransportAddress(
+            `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`,
+            4
+          );
+        }
+      }
+      return "blocked";
+    }
+    return isPrivateIPv62(v6) ? "private" : "public";
+  }
+  return "blocked";
+}
+function assertTransportAddressAllowed(address, family, hostname, allowPrivateNetworks) {
+  const classification = classifyTransportAddress(address, family);
+  if (classification === "blocked") {
+    throw new ConfigError({
+      message: `MCP transport: resolved address "${address}" for "${hostname}" is link-local/IMDS \u2014 never a valid MCP target`,
+      code: "CONFIG_INVALID",
+      context: { hostname, address }
+    });
+  }
+  if (classification === "private" && !allowPrivateNetworks) {
+    throw new ConfigError({
+      message: `MCP transport: "${hostname}" resolved to private address ${address}. Private/LAN targets are blocked by default; if this server really runs on your private network, set allowPrivateNetworks: true on its config (or WRONGSTACK_MCP_ALLOW_PRIVATE=1 globally).`,
+      code: "CONFIG_INVALID",
+      context: { hostname, address }
+    });
+  }
+}
+function transportPinnedLookup(options) {
+  const lookup3 = options.lookup ?? (async (host) => dns2.lookup(host, { all: true }));
+  return (hostname, connectOptions, callback) => {
+    lookup3(hostname).then((records) => {
+      if (records.length === 0) {
+        callback(
+          Object.assign(new Error(`MCP transport: no addresses for "${hostname}"`), {
+            code: "ENOTFOUND"
+          })
+        );
+        return;
+      }
+      for (const record3 of records) {
+        assertTransportAddressAllowed(
+          record3.address,
+          record3.family,
+          hostname,
+          options.allowPrivateNetworks
+        );
+      }
+      const wanted = connectOptions?.family;
+      const filtered = wanted === 4 || wanted === 6 ? records.filter((record3) => record3.family === wanted) : records;
+      const list = filtered.length > 0 ? filtered : records;
+      if (connectOptions?.all) {
+        callback(
+          null,
+          list.map((record3) => ({ address: record3.address, family: record3.family }))
+        );
+        return;
+      }
+      const first = list[0];
+      callback(null, first.address, first.family);
+    }).catch((error) => callback(error));
+  };
+}
 
 // src/transport-base.ts
 var MAX_TRANSPORT_REDIRECTS = 5;
+var nativeGlobalFetch = globalThis.fetch;
+var pinnedAgents = /* @__PURE__ */ new Set();
+var pinnedAgentsCleanupRegistered = false;
+if (!pinnedAgentsCleanupRegistered) {
+  pinnedAgentsCleanupRegistered = true;
+  process.on("beforeExit", () => {
+    for (const agent of pinnedAgents) agent.destroy();
+    pinnedAgents.clear();
+  });
+}
 function makeAbortError(method) {
   const err = new Error(`MCP request "${method}" aborted by client`);
   err.name = "AbortError";
@@ -1355,6 +1457,10 @@ var BaseHTTPTransport = class {
   authorizationResource;
   /** Per-request TLS agent — created once from HttpTransportOptions.tls */
   tlsAgent;
+  tlsOptions;
+  allowPrivateNetworks;
+  lookup;
+  pinnedAgent;
   tools = [];
   serverMetadata;
   abortController;
@@ -1390,6 +1496,9 @@ var BaseHTTPTransport = class {
         rejectUnauthorized: opts.tls.rejectUnauthorized
       });
     }
+    this.tlsOptions = opts.tls;
+    this.allowPrivateNetworks = opts.allowPrivateNetworks === true || ALLOW_MCP_PRIVATE_NETWORKS;
+    this.lookup = opts.lookup;
   }
   getState() {
     return this.state;
@@ -1415,7 +1524,9 @@ var BaseHTTPTransport = class {
       let currentUrl = typeof input === "string" ? input : String(input);
       let hopHeaders = headers;
       for (let hop = 0; hop < MAX_TRANSPORT_REDIRECTS; hop++) {
-        const res = await fetch(currentUrl, { ...init, headers: hopHeaders, redirect: "manual" });
+        const fetchOpts = { ...init, headers: hopHeaders, redirect: "manual" };
+        this.applyPinnedDispatcher(fetchOpts);
+        const res = await this.dispatcherFetch()(currentUrl, fetchOpts);
         if (res.status !== 301 && res.status !== 302 && res.status !== 303 && res.status !== 307 && res.status !== 308) {
           return res;
         }
@@ -1510,12 +1621,48 @@ var BaseHTTPTransport = class {
       }
     }
   }
+  dispatcherFetch() {
+    return globalThis.fetch === nativeGlobalFetch ? undiciFetch : globalThis.fetch;
+  }
+  pinnedDispatcher() {
+    if (!this.pinnedAgent) {
+      const tls = this.tlsOptions;
+      this.pinnedAgent = new UndiciAgent({
+        allowH2: false,
+        connect: {
+          ...tls ? { ca: tls.ca, rejectUnauthorized: tls.rejectUnauthorized } : {},
+          lookup: transportPinnedLookup({
+            allowPrivateNetworks: this.allowPrivateNetworks,
+            lookup: this.lookup
+          })
+        }
+      });
+      pinnedAgents.add(this.pinnedAgent);
+    }
+    return this.pinnedAgent;
+  }
+  applyPinnedDispatcher(fetchOpts) {
+    fetchOpts.dispatcher = this.pinnedDispatcher();
+  }
+  /**
+   * Destroy this transport's pinned Agent and its connection pool. Idempotent.
+   * Subclasses call it from close(); the process-exit sweep is the backstop.
+   */
+  releasePinnedDispatcher() {
+    if (!this.pinnedAgent) return;
+    pinnedAgents.delete(this.pinnedAgent);
+    this.pinnedAgent.destroy();
+    this.pinnedAgent = void 0;
+  }
   /**
    * Apply the pinned TLS agent (if configured) to a `RequestInit` object.
    * Uses `HttpDispatcher` from `@wrongstack/core`'s dispatcher-types shim,
    * which declares `https.Agent` compatible with `RequestInit.dispatcher`.
    * Verified safe: https.Agent implements the `dispatch(req, opts)` method
    * that fetch requires at runtime.
+   *
+   * Superseded at fetch time by `applyPinnedDispatcher`, whose Agent embeds
+   * these same TLS options plus the resolution-bound lookup.
    */
   applyTlsAgent(fetchOpts) {
     if (this.tlsAgent) {
@@ -1851,6 +1998,7 @@ var SSETransport = class extends BaseHTTPTransport {
         });
         throw makeAbortError(method);
       }
+      this.markDisconnected();
       throw err;
     } finally {
       timeoutSignal.dispose();
@@ -1934,12 +2082,14 @@ var SSETransport = class extends BaseHTTPTransport {
         });
         throw makeAbortError(method);
       }
+      this.markDisconnected();
       throw err;
     } finally {
       timeoutSignal.dispose();
     }
   }
   async close() {
+    this.releasePinnedDispatcher();
     if (this.state === "disconnected") return;
     this.readerDone = true;
     this.readLoopAbort?.abort();
@@ -1955,10 +2105,16 @@ var SSETransport = class extends BaseHTTPTransport {
     this.disconnectHandlers.splice(0, this.disconnectHandlers.length);
     this.state = "disconnected";
   }
+  markDisconnected() {
+    if (this.state === "connected") {
+      this.state = "disconnected";
+      this.notifyDisconnect();
+    }
+  }
 };
 
 // src/transport-streamable.ts
-var StreamableHTTPTransport = class extends BaseHTTPTransport {
+var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTransport {
   _nextId = 1;
   sessionId;
   constructor(opts) {
@@ -2090,6 +2246,9 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
     try {
       const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
       if (!res.ok) {
+        if (_StreamableHTTPTransport.SESSION_FATAL_HTTP_STATUSES.has(res.status)) {
+          this.markDisconnected();
+        }
         throw new Error(`HTTP ${res.status}: ${res.statusText}`);
       }
       if (method.startsWith("notifications/")) {
@@ -2137,6 +2296,9 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
     try {
       const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
       if (!res.ok) {
+        if (_StreamableHTTPTransport.SESSION_FATAL_HTTP_STATUSES.has(res.status)) {
+          this.markDisconnected();
+        }
         throw new Error(`HTTP ${res.status}: ${res.statusText}`);
       }
       if (method.startsWith("notifications/")) {
@@ -2182,11 +2344,26 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
     };
   }
   async close() {
+    this.releasePinnedDispatcher();
     if (this.state === "disconnected") return;
     this.state = "disconnected";
     this.abortController?.abort();
     this.disconnectHandlers.splice(0, this.disconnectHandlers.length);
   }
+  /**
+   * HTTP statuses that mean the streamable-http session itself is gone
+   * (auth rejected, session id unknown or expired). Only these tear the
+   * connection down on the request path; transient faults (5xx, network
+   * resets) surface as call errors and keep the session alive so the next
+   * request can succeed — the contract pinned by http-fault-soak.test.ts.
+   */
+  static SESSION_FATAL_HTTP_STATUSES = /* @__PURE__ */ new Set([401, 403, 404, 410]);
+  markDisconnected() {
+    if (this.state === "connected") {
+      this.state = "disconnected";
+      this.notifyDisconnect();
+    }
+  }
 };
 
 // src/client.ts
@@ -2214,6 +2391,7 @@ var MCPClient = class _MCPClient {
    */
   pending = /* @__PURE__ */ new Map();
   rxBuffer = "";
+  rxBufferBytes = 0;
   _tools = [];
   /** Server-declared handshake metadata. Populated for stdio in the first protocol slice. */
   _serverMetadata;
@@ -2298,6 +2476,7 @@ var MCPClient = class _MCPClient {
       throw new Error('MCP stdio transport requires "command"');
     }
     this.rxBuffer = "";
+    this.rxBufferBytes = 0;
     const extraEnv = { ...this.opts.env };
     if (this.opts.passthroughEnv) {
       for (const name of this.opts.passthroughEnv) {
@@ -2399,7 +2578,8 @@ var MCPClient = class _MCPClient {
       headers: this.opts.headers,
       startupTimeoutMs: this.opts.startupTimeoutMs,
       requestTimeoutMs: this.opts.requestTimeoutMs,
-      authorizationProvider: this.opts.authorizationProvider
+      authorizationProvider: this.opts.authorizationProvider,
+      allowPrivateNetworks: this.opts.allowPrivateNetworks
     };
     this.sseTransport = new SSETransport(httpOpts);
     this.sseTransport.onDisconnect(() => {
@@ -2449,7 +2629,8 @@ var MCPClient = class _MCPClient {
       headers: this.opts.headers,
       startupTimeoutMs: this.opts.startupTimeoutMs,
       requestTimeoutMs: this.opts.requestTimeoutMs,
-      authorizationProvider: this.opts.authorizationProvider
+      authorizationProvider: this.opts.authorizationProvider,
+      allowPrivateNetworks: this.opts.allowPrivateNetworks
     };
     this.httpTransport = new StreamableHTTPTransport(httpOpts);
     this.httpTransport.onDisconnect(() => {
@@ -2809,9 +2990,11 @@ var MCPClient = class _MCPClient {
   }
   onData(s) {
     this.rxBuffer += s;
-    if (this.rxBuffer.length > _MCPClient.MAX_RX_BUFFER_BYTES) {
-      const truncated = this.rxBuffer.length;
+    this.rxBufferBytes += Buffer.byteLength(s, "utf8");
+    if (this.rxBufferBytes > _MCPClient.MAX_RX_BUFFER_BYTES) {
+      const truncated = this.rxBufferBytes;
       this.rxBuffer = "";
+      this.rxBufferBytes = 0;
       this.failPending(
         `MCP "${this.opts.name}" rx buffer overflow (${truncated} bytes without a newline) \u2014 closing connection`
       );
@@ -2827,6 +3010,7 @@ var MCPClient = class _MCPClient {
       idx = this.rxBuffer.indexOf("\n", start);
     }
     if (start > 0) {
+      this.rxBufferBytes -= Buffer.byteLength(this.rxBuffer.slice(0, start), "utf8");
       this.rxBuffer = this.rxBuffer.slice(start);
     }
   }
@@ -3144,6 +3328,8 @@ function buildConfig(input, base) {
   if (allowedTools !== void 0) cfg.allowedTools = allowedTools;
   const permission = input.permission ?? base?.permission;
   if (permission !== void 0) cfg.permission = permission;
+  const allowPrivateNetworks = input.allowPrivateNetworks ?? base?.allowPrivateNetworks;
+  if (allowPrivateNetworks !== void 0) cfg.allowPrivateNetworks = allowPrivateNetworks;
   const enabled = input.enabled ?? base?.enabled;
   if (enabled !== void 0) cfg.enabled = enabled;
   const lazy = input.lazy ?? base?.lazy;
@@ -3374,13 +3560,26 @@ function manifestConfigHash(cfg) {
     transport: cfg.transport,
     command: cfg.command ?? null,
     args: cfg.args ?? null,
-    url: cfg.url ?? null
+    url: cfg.url ?? null,
+    env: sortedEntries(cfg.env),
+    headers: sortedEntries(cfg.headers),
+    passthroughEnv: passthroughEntries(cfg.passthroughEnv)
   });
   return createHash2("sha256").update(basis).digest("hex").slice(0, 16);
 }
+function sortedEntries(values) {
+  return values ? Object.entries(values).sort(([left], [right]) => left.localeCompare(right)) : null;
+}
+function passthroughEntries(names) {
+  return names ? [...new Set(names)].sort().map((name) => [name, process.env[name] ?? null]) : null;
+}
 function manifestFile(cacheDir, name) {
   const safe = name.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return path.join(cacheDir, "mcp-tools", `${safe}.json`);
+  if (safe === name && name === name.toLowerCase()) {
+    return path.join(cacheDir, "mcp-tools", `${safe}.json`);
+  }
+  const identity = createHash2("sha256").update(name).digest("hex");
+  return path.join(cacheDir, "mcp-tools", `${safe}-${identity}.json`);
 }
 async function readManifest(cacheDir, name, configHash) {
   const manifest = await readCapabilityManifest(cacheDir, name, configHash);
@@ -3826,6 +4025,7 @@ async function attemptConnectSlot(ctx, slot) {
         headers: slot.cfg.headers,
         startupTimeoutMs: slot.cfg.startupTimeoutMs,
         requestTimeoutMs: slot.cfg.requestTimeoutMs,
+        allowPrivateNetworks: slot.cfg.allowPrivateNetworks,
         passthroughEnv: slot.cfg.passthroughEnv,
         authorizationProvider: ctx.authorizationProviderFactory?.(slot.cfg)
       });
@@ -5013,6 +5213,7 @@ function serveStdio(server, opts = {}) {
   const stdin = opts.stdin ?? process.stdin;
   const stdout = opts.stdout ?? process.stdout;
   let buffer = "";
+  let bufferBytes = 0;
   let closed = false;
   let bufferTooLarge = false;
   let writeChain = Promise.resolve();
@@ -5037,10 +5238,13 @@ function serveStdio(server, opts = {}) {
   };
   const onData = (chunk) => {
     if (bufferTooLarge) return;
-    buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    if (buffer.length > HTTP_BODY_CAP) {
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    buffer += text;
+    bufferBytes += Buffer.byteLength(text, "utf8");
+    if (bufferBytes > HTTP_BODY_CAP) {
       bufferTooLarge = true;
       buffer = "";
+      bufferBytes = 0;
       console.error(
         JSON.stringify({
           level: "error",
@@ -5082,7 +5286,10 @@ function serveStdio(server, opts = {}) {
       });
       inFlightHandlers.add(handler);
     }
-    if (start > 0) buffer = buffer.slice(start);
+    if (start > 0) {
+      bufferBytes -= Buffer.byteLength(buffer.slice(0, start), "utf8");
+      buffer = buffer.slice(start);
+    }
   };
   let resolveDone;
   const done = new Promise((resolve) => {
@@ -5097,6 +5304,7 @@ function serveStdio(server, opts = {}) {
     if (!bufferTooLarge && buffer.trim()) {
       const line = buffer.trim();
       buffer = "";
+      bufferBytes = 0;
       const handler = server.handleMessage(line).then((res) => {
         if (res !== null) writeLine(res);
       }).catch((err) => {
@@ -5197,11 +5405,13 @@ async function handleHttpRequest(server, req, res, token, log, boundHost) {
     return send(415, JSON.stringify({ error: "content-type must be application/json" }));
   }
   let body = "";
+  let bodyBytes = 0;
   let aborted = false;
   req.on("data", (chunk) => {
     if (aborted) return;
+    bodyBytes += chunk.byteLength;
     body += chunk.toString("utf8");
-    if (body.length > HTTP_BODY_CAP) {
+    if (bodyBytes > HTTP_BODY_CAP) {
       aborted = true;
       send(413, JSON.stringify({ error: "payload too large" }));
       req.destroy();
@@ -5422,13 +5632,14 @@ var MCPRefreshingAuthorizationProvider = class {
     return await this.refresh(state, context.signal) !== void 0;
   }
   refresh(state, signal) {
-    if (this.refreshPromise) return this.refreshPromise;
-    this.refreshPromise = this.refreshInner(state, signal).finally(() => {
-      this.refreshPromise = void 0;
-    });
-    return this.refreshPromise;
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.refreshInner(state).finally(() => {
+        this.refreshPromise = void 0;
+      });
+    }
+    return awaitWithAbort(this.refreshPromise, signal);
   }
-  async refreshInner(state, signal) {
+  async refreshInner(state) {
     const refreshToken = state.tokenSet.refreshToken;
     if (!refreshToken) {
       this.emit("reauth_required", state);
@@ -5438,8 +5649,7 @@ var MCPRefreshingAuthorizationProvider = class {
       authorizationServer: state.authorizationServer,
       clientId: state.clientId,
       resource: state.resource,
-      refreshToken,
-      signal
+      refreshToken
     });
     const next = normalizeStoredAuthorization({
       ...state,
@@ -5485,6 +5695,18 @@ function createVaultBackedMcpAuthorizationProviderFactory(options) {
     return provider;
   };
 }
+function awaitWithAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortReason(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+function abortReason(signal) {
+  return signal.reason instanceof Error ? signal.reason : new Error("MCP token refresh aborted");
+}
 function emptyFile() {
   return { version: TOKEN_STORE_VERSION, updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(), entries: [] };
 }

package/dist/manage.d.ts

@@ -6,6 +6,7 @@ type TransportInput = 'stdio' | 'sse' | 'streamable-http' | 'http';
 export interface McpServerInput {
     name: string;
     transport?: TransportInput | string | undefined;
+    allowPrivateNetworks?: boolean | undefined;
     description?: string | undefined;
     enabled?: boolean | undefined;
     command?: string | undefined;

package/dist/manifest-cache.d.ts

@@ -13,6 +13,9 @@ export declare function manifestConfigHash(cfg: {
     command?: string | undefined;
     args?: string[] | undefined;
     url?: string | undefined;
+    env?: Record<string, string> | undefined;
+    headers?: Record<string, string> | undefined;
+    passthroughEnv?: string[] | undefined;
 }): string;
 /**
  * Read a server's cached tools. Returns null when there is no cache or when the

package/dist/transport-base.d.ts

@@ -2,6 +2,7 @@ import * as https from 'node:https';
 import { type MCPAuthorizationProvider } from './authorization.js';
 import type { ConnectionState, MCPTool } from './contracts.js';
 import type { MCPServerMetadata } from './protocol.js';
+import { type TransportDnsLookup } from './transport-security.js';
 export interface HttpTransportOptions {
     name: string;
     url: string;
@@ -27,6 +28,21 @@ export interface HttpTransportOptions {
         ca?: string | undefined;
         rejectUnauthorized?: boolean | undefined;
     };
+    /**
+     * Resolution-bound private-network policy. Default: the transport resolves
+     * the configured hostname itself and refuses dial-time addresses outside
+     * the public internet — link-local/IMDS always, other private/LAN ranges
+     * unless this flag is set. The configured hostname is still used for the
+     * Host header and TLS SNI, so certificate validation is unaffected, and
+     * plaintext http:// remains loopback-only (validateTransportUrl).
+     */
+    allowPrivateNetworks?: boolean | undefined;
+    /**
+     * DNS seam for tests and hosts with custom resolvers. Production callers
+     * omit it: dns.lookup(hostname, { all: true }) runs and every returned
+     * record is policy-checked before the dial.
+     */
+    lookup?: TransportDnsLookup | undefined;
 }
 /**
  * Abort error whose `name` is `'AbortError'` so the core executor's
@@ -52,6 +68,10 @@ export declare abstract class BaseHTTPTransport {
     protected readonly authorizationResource: string;
     /** Per-request TLS agent — created once from HttpTransportOptions.tls */
     protected readonly tlsAgent?: https.Agent | undefined;
+    private readonly tlsOptions;
+    private readonly allowPrivateNetworks;
+    private readonly lookup;
+    private pinnedAgent;
     protected readonly tools: MCPTool[];
     protected serverMetadata?: MCPServerMetadata | undefined;
     protected abortController?: AbortController | undefined;
@@ -76,12 +96,23 @@ export declare abstract class BaseHTTPTransport {
     protected notifyDisconnect(): void;
     protected notifyResourcesChanged(): void;
     protected notifyPromptsChanged(): void;
+    private dispatcherFetch;
+    private pinnedDispatcher;
+    private applyPinnedDispatcher;
+    /**
+     * Destroy this transport's pinned Agent and its connection pool. Idempotent.
+     * Subclasses call it from close(); the process-exit sweep is the backstop.
+     */
+    protected releasePinnedDispatcher(): void;
     /**
      * Apply the pinned TLS agent (if configured) to a `RequestInit` object.
      * Uses `HttpDispatcher` from `@wrongstack/core`'s dispatcher-types shim,
      * which declares `https.Agent` compatible with `RequestInit.dispatcher`.
      * Verified safe: https.Agent implements the `dispatch(req, opts)` method
      * that fetch requires at runtime.
+     *
+     * Superseded at fetch time by `applyPinnedDispatcher`, whose Agent embeds
+     * these same TLS options plus the resolution-bound lookup.
      */
     protected applyTlsAgent(fetchOpts: RequestInit): void;
     /** Generate the next JSON-RPC request id. Subclasses provide the counter. */

package/dist/transport-security.d.ts

@@ -10,4 +10,52 @@ export declare function isTlsUnsafeAllowed(): boolean;
  * the most obvious attack vectors.
  */
 export declare function validateTransportUrl(rawUrl: string): void;
+/** Global escape hatch, mirroring the fetch tool's WRONGSTACK_FETCH_ALLOW_PRIVATE. */
+export declare const ALLOW_MCP_PRIVATE_NETWORKS: boolean;
+/** One resolved DNS record for an MCP transport hostname. */
+export interface TransportDnsRecord {
+    address: string;
+    family: number;
+}
+/** DNS seam: production uses dns.lookup(host, { all: true }); tests inject. */
+export type TransportDnsLookup = (hostname: string) => Promise<readonly TransportDnsRecord[]>;
+/** Policy verdict for one resolved address. */
+export type TransportAddressClass = 'loopback' | 'private' | 'blocked' | 'public';
+/**
+ * Classify one resolved address under MCP transport policy:
+ *  - `blocked`  — link-local / IMDS (169.254/16, fe80::/10, fd00:ec2::254);
+ *                 never a valid MCP target, regardless of opt-in.
+ *  - `loopback` — 127/8, ::1; the documented local topology, always allowed.
+ *  - `private`  — other private/reserved ranges (10/8, 172.16/12, 192.168/16,
+ *                 CGNAT, ULA, ...); allowed only with allowPrivateNetworks.
+ *  - `public`   — no dial-time restriction beyond the string-level checks.
+ */
+export declare function classifyTransportAddress(address: string, family: number): TransportAddressClass;
+/**
+ * Refuse `address` unless the transport policy allows dialing it:
+ * link-local/IMDS always throws; other private ranges throw unless opted in
+ * via allowPrivateNetworks. `hostname` is the configured name the address was
+ * resolved from, kept for error context.
+ */
+export declare function assertTransportAddressAllowed(address: string, family: number, hostname: string, allowPrivateNetworks: boolean): void;
+/** Node-style DNS callback for undici Agent connect options. */
+type NodeLookupCallback = (err: NodeJS.ErrnoException | null, address?: string | readonly TransportDnsRecord[], family?: number) => void;
+export interface PinnedLookupOptions {
+    allowPrivateNetworks: boolean;
+    /** Test/host seam. Production omits it: dns.lookup(all: true). */
+    lookup?: TransportDnsLookup | undefined;
+}
+/**
+ * The lookup installed into the pinned undici Agent's connect options. It is
+ * the single DNS resolution the TCP dial performs: every returned record is
+ * classified and refused BEFORE the socket connects, so there is no rebinding
+ * window between validation and connect. Mirrors tools/_fetch-guard.ts
+ * guardedLookup with MCP policy (loopback allowed, link-local never, opt-in
+ * for other private ranges).
+ */
+export declare function transportPinnedLookup(options: PinnedLookupOptions): (hostname: string, connectOptions: {
+    family?: number | undefined;
+    all?: boolean | undefined;
+}, callback: NodeLookupCallback) => void;
+export {};
 //# sourceMappingURL=transport-security.d.ts.map

package/dist/transport-sse.d.ts

@@ -27,5 +27,6 @@ export declare class SSETransport extends BaseHTTPTransport {
         signal?: AbortSignal | undefined;
     }): Promise<JsonRpcResponse>;
     close(): Promise<void>;
+    private markDisconnected;
 }
 //# sourceMappingURL=transport-sse.d.ts.map

package/dist/transport-streamable.d.ts

@@ -23,5 +23,14 @@ export declare class StreamableHTTPTransport extends BaseHTTPTransport {
         signal?: AbortSignal | undefined;
     }): Promise<ToolCallResult>;
     close(): Promise<void>;
+    /**
+     * HTTP statuses that mean the streamable-http session itself is gone
+     * (auth rejected, session id unknown or expired). Only these tear the
+     * connection down on the request path; transient faults (5xx, network
+     * resets) surface as call errors and keep the session alive so the next
+     * request can succeed — the contract pinned by http-fault-soak.test.ts.
+     */
+    private static readonly SESSION_FATAL_HTTP_STATUSES;
+    private markDisconnected;
 }
 //# sourceMappingURL=transport-streamable.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/mcp",
-  "version": "0.320.1",
+  "version": "1.0.0",
   "license": "MIT",
   "description": "WrongStack Model Context Protocol client and registry: stdio, SSE, and streamable HTTP transports.",
   "repository": {
@@ -26,7 +26,8 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@wrongstack/core": "0.320.1"
+    "@wrongstack/core": "1.0.0",
+    "undici": "^8.10.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",