Files
PaperClipAI/server/src/__tests__/remote-http-rebinding.test.ts
T
DottaandClaude Opus 5.5 267983356c feat(mcp): speak stateless MCP 2026-07-28 to provider servers, keep older servers working (#21140)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use apps through Paperclip's MCP client. The client calls
each provider's remote (Streamable HTTP) or local (stdio) MCP server.
> - The client spoke only protocol 2025-06-18. It always did the
`initialize` handshake and it sent client capabilities only in that
handshake.
> - MCP 2026-07-28 removes the handshake and sessions. Every request
carries its version, capabilities and client identity in `_meta`.
Servers that only speak 2026-07-28 reject the old requests, and they
never see that Paperclip renders MCP Apps views.
> - Public servers already speak it: DeepWiki and Context7 answer
`server/discover` with 2026-07-28 today.
> - This pull request makes the client negotiate the version per server.
It speaks stateless MCP to 2026-07-28 servers and keeps the handshake
for 2025-11-25 and older servers.
> - The benefit is that new and old providers both work, and a tool call
to a stateless server is one HTTP request with no handshake.

## Linked Issues or Issue Description

Refs #21119 (MCP Apps host). This PR sends its MCP Apps capability to
stateless servers too.

**Subsystem affected**
Server: the MCP client in `server/src/services/mcp-http.ts`, catalog
discovery, the tool gateway (`tools/call`, context reads, stdio), and
the remote MCP OAuth flow.

**Problem or motivation**
The client used protocol 2025-06-18 only. MCP 2026-07-28 makes MCP
stateless: no `initialize`, no `Mcp-Session-Id`, per-request `_meta`,
`server/discover`, `resultType` with multi round-trip requests (MRTR),
cacheable lists, required `Mcp-Method`/`Mcp-Name` headers, and RFC 9207
`iss` validation. Servers that speak only 2026-07-28 cannot be used.
Paperclip advertised MCP Apps support only in `initialize`, so stateless
servers never saw it.

**Proposed solution**
Probe each server once with `server/discover`, pick the newest mutually
supported version, and save it on the connection. Send stateless
requests to modern servers and keep the handshake for legacy servers.
Tool calls use the saved version and never probe. The saved version is
checked again only when a request built from it is refused.

**Alternatives considered**
Inline negotiation (send each request in modern shape first and fall
back on `400`) adds a failed request to every call to a legacy session
server. Probing on every tool call adds a round trip before each tool
runs. Saving the negotiated version keeps tool calls at one request.

**Roadmap alignment**
MCP protocol currency for the Apps and connections substrate. It follows
the MCP Apps host work in #21119.

**Additional context**
Spec:
https://modelcontextprotocol.io/specification/2026-07-28/changelog. Out
of scope (separate work): the Tasks extension, Skills over MCP,
`subscriptions/listen`, progress and cancellation, icons,
enterprise-managed authorization.

## What Changed

- `mcp-http.ts`: `negotiateMcpProtocolVersion` probes with
`server/discover`. A `DiscoverResult` or a modern error
(`-32020`/`-32021`/`-32022`) means a modern server. Anything else means
a legacy server, which gets `initialize`. A `401`/`403` keeps the
challenge for OAuth discovery. The era is remembered per connection and
endpoint.
- `mcpHttpRequestInit` builds every request. It always sends
`Mcp-Method` and `Mcp-Name` (Base64 sentinel when unsafe). For modern
versions it adds `_meta` (`protocolVersion`, `clientCapabilities` with
`extensions["io.modelcontextprotocol/ui"]` and URL elicitation,
`clientInfo`) and `Mcp-Param-*` headers from `x-mcp-header`.
- Legacy `initialize` now requests 2025-11-25 and advertises the MCP
Apps extension.
- Catalog refresh saves `config.mcpProtocolVersion`. It drops tools with
invalid `x-mcp-header` annotations. It reuses a fresh `tools/list`
result (`ttlMs`, `cacheScope`). It probes again when the saved version
is refused, and it negotiates again after a credential refresh.
- `tools/call`: a saved modern version is called directly (no probe, no
handshake). A modern rejection of a legacy-shaped call, or `-32022`,
gets one retry with a negotiated version. The server rejected the first
request before it ran, so the retry cannot repeat a side effect. A
remembered legacy server that refuses `initialize` is probed again.
- MRTR: `input_required` with URL requests becomes the existing provider
link flow (`provider_interaction_required`). The next identical call
sends `requestState` and `inputResponses`. Form, sampling and roots
requests stop with `provider_input_required` and a plain message. A
missing `resultType` means `complete`.
- Context reads (`resources/*`, `prompts/*`) use the saved version,
cache fresh results, and stop on `input_required`. The error code is
kept, so resource not found (`-32602` or `-32002`) is visible.
- stdio: probe with `server/discover` (2 s limit). Restart a server that
exits on the probe. Send `_meta` to modern servers.
- OAuth: refuse a callback without `iss` when the server advertises
`authorization_response_iss_parameter_supported`. Check `iss` before
acting on a provider error. Send `application_type: "native"` for
localhost callbacks and `web` otherwise. Issuer-bound clients and the
CIMD-first order already existed.
- Docs: `doc/connections/MCP-PROTOCOL-VERSIONS.md`, linked from
`doc/connections/README.md`.

## Verification

- New suite `server/src/__tests__/mcp-protocol-versions.test.ts` (19
tests) uses a fake 2026-07-28 server and a fake legacy session server.
It covers discovery, `_meta`, headers, version fallback, `-32022`,
`resultType`, MRTR link and retry, form stop, cache TTL, legacy flow,
and recovery when a saved legacy server moves to 2026-07-28. Embedded
Postgres runs the end-to-end cases.
- New OAuth tests in `generic-mcp-connection.test.ts`: `iss` required
when advertised, `iss` checked on provider errors, `native` for
localhost, and a stateless server listed again after a revoked token.
- Red/green: with the master service code, all 21 new protocol and OAuth
tests fail. With this change they pass. The token-refresh regression
test fails without its fix and passes with it.
- Existing suites: 12 touched files, 1088 tests pass. `tsc --noEmit`
passes for `server`. Updated expectations count the one-time
`server/discover` probe, and the Calendly DCR test now expects `native`
for its localhost callback.
- `pnpm verify` exits 2 (a doc is a global CI input), so CI supplies the
broad coverage.
- Live check with the changed client, without credentials:
- DeepWiki (`mcp.deepwiki.com/mcp`): discover 200 → 2026-07-28, no
session, `tools/list` 200 (3 tools).
- Context7 (`mcp.context7.com/mcp`): discover 200 → 2026-07-28, no
session, `tools/list` 200 (2 tools).
- GitMCP (`gitmcp.io/docs`): discover 400 → `initialize` (2025-03-26) →
session → `tools/list` 200 (5 tools).
- Circleback (`circleback.ai/api/mcp`): discover 401 with its
`WWW-Authenticate` challenge kept for sign-in.

## Risks

- A legacy server that is not saved as session-required gets one extra
request (`server/discover`) the first time it is refreshed. Then the
version is saved. Saved session-required connections are not probed.
- DCR from a localhost callback now registers a `native` client. This is
what the spec asks for. Existing registrations are reused.
- An authorization server that advertises `iss` support but does not
send `iss` now fails sign-in with a clear message. The spec requires
this.
- MRTR answers are kept in memory for 30 minutes. After a restart the
server asks again, and the user sees the link again.
- No schema change. `config.mcpProtocolVersion` is a new key in the
existing JSON config.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code
with tool use (shell, file edits, web fetch of the MCP spec), extended
reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 14:34:26 -06:00

652 lines
27 KiB
TypeScript

import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
import { connect as netConnect, createServer as netCreateServer, Socket, type AddressInfo } from "node:net";
import { gzipSync } from "node:zlib";
import { afterEach, describe, expect, it } from "vitest";
import { guardedRemoteHttpFetch, type RemoteHttpSocketFactory } from "../services/remote-http-fetch.js";
import { readRemoteConnectionFailure } from "../services/remote-connection-failure.js";
import { isExpectedMcpConnectionFailure, retainMcpConnectionFailure, withMcpConnectionFailure } from "../services/mcp-connection-failure.js";
import { HttpError } from "../errors.js";
import { initializeMcpHttpSession } from "../services/mcp-http.js";
/**
* PAP-17098 — DNS-rebinding regression coverage for outbound MCP/OAuth calls.
*
* The vulnerability was a TOCTOU: the guard resolved a hostname, approved it,
* and then handed the *hostname* to global `fetch`, which resolved it a second
* time. A name server the attacker controls can answer with a public address for
* the first lookup and a loopback/private/link-local address for the second,
* pointing the connection at an internal service or the cloud metadata endpoint.
*
* These tests model that name server deterministically: `lookup` returns a public
* address on its first call and `127.0.0.1` on every call after it. Nothing here
* touches real DNS or the real network — `socketFactory` stands in for the
* network so a "public" address is a loopback listener that reports itself as
* public, exactly as it would look to the kernel.
*/
const PUBLIC_ADDRESS = "93.184.216.34";
const REBIND_HOST = "mcp.rebind.test";
type TestServer = {
server: Server;
port: number;
requests: Array<{ url: string; host: string | undefined }>;
connections: number;
};
const openServers: Server[] = [];
const openSockets: Socket[] = [];
afterEach(async () => {
for (const socket of openSockets.splice(0)) socket.destroy();
await Promise.all(openServers.splice(0).map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
});
async function startServer(handler?: (req: IncomingMessage, res: ServerResponse) => void): Promise<TestServer> {
const requests: TestServer["requests"] = [];
const state = { connections: 0 };
const server = createServer((req, res) => {
requests.push({ url: req.url ?? "", host: req.headers.host });
if (handler) {
handler(req, res);
return;
}
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify({ ok: true }));
});
server.on("connection", () => {
state.connections += 1;
});
openServers.push(server);
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = (server.address() as AddressInfo).port;
return {
server,
port,
requests,
get connections() {
return state.connections;
},
};
}
function guardError(message: string, code: string) {
return Object.assign(new Error(message), { code });
}
/**
* A stand-in for the network: routes whatever address the transport dialled to a
* loopback listener, and reports `remoteAddress` as the dialled address so the
* peer check sees what the kernel would have seen.
*/
function routingSocketFactory(routes: Record<string, number>): {
factory: RemoteHttpSocketFactory;
dialled: string[];
sockets: Socket[];
} {
const dialled: string[] = [];
const sockets: Socket[] = [];
const factory: RemoteHttpSocketFactory = (target) => {
dialled.push(target.address);
const port = routes[target.address];
if (port === undefined) throw new Error(`test network has no route to ${target.address}`);
const socket = netConnect({ host: "127.0.0.1", port });
openSockets.push(socket);
sockets.push(socket);
Object.defineProperty(socket, "remoteAddress", { get: () => target.address, configurable: true });
return socket;
};
return { factory, dialled, sockets };
}
/** Waits for the socket bookkeeping the transport does after it rejects. */
async function flush(): Promise<void> {
await new Promise((resolve) => setTimeout(resolve, 50));
}
/** A name server that answers public first and loopback afterwards. */
function rebindingLookup(): { lookup: () => Promise<Array<{ address: string; family: number }>>; calls: () => number } {
let calls = 0;
return {
lookup: async () => {
calls += 1;
return calls === 1
? [{ address: PUBLIC_ADDRESS, family: 4 }]
: [{ address: "127.0.0.1", family: 4 }];
},
calls: () => calls,
};
}
describe("guarded remote HTTP fetch (PAP-17098 DNS rebinding)", () => {
it("sends a stable default User-Agent and preserves an explicit caller value", async () => {
const seen: Array<string | undefined> = [];
const upstream = await startServer((req, res) => {
seen.push(req.headers["user-agent"]);
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify({ ok: true }));
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const options = {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
error: guardError,
};
await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, options);
await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {
headers: { "user-agent": "Caller/2.0" },
}, options);
expect(seen).toEqual(["Paperclip/1.0", "Caller/2.0"]);
});
it("turns a platform-fetch DNS cause into the stable DNS code", async () => {
const cause = Object.assign(new Error("getaddrinfo ENOTFOUND missing.invalid"), {
code: "ENOTFOUND",
});
const unpinnedFetch = (async () => {
throw Object.assign(new TypeError("fetch failed"), { cause });
}) as typeof fetch;
const failure = await guardedRemoteHttpFetch("https://8.8.8.8/mcp", {}, {
allowPrivateNetwork: true,
unpinnedFetch,
error: guardError,
}).catch((error) => error);
expect(failure).toMatchObject({
code: "remote_http_dns_failed",
message: "Remote MCP connection hostname could not be resolved",
});
expect(readRemoteConnectionFailure(failure)).toBe("dns_failure");
});
it("pins the connection to the approved address so a rebind never reaches loopback", async () => {
const upstream = await startServer();
const internal = await startServer();
const dns = rebindingLookup();
const network = routingSocketFactory({
[PUBLIC_ADDRESS]: upstream.port,
"127.0.0.1": internal.port,
});
const response = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: dns.lookup,
socketFactory: network.factory,
error: guardError,
});
await expect(response.json()).resolves.toEqual({ ok: true });
// One resolution, and the connection went to the address that resolution
// approved. The rebind answer is never consulted, so it cannot win a race.
expect(dns.calls()).toBe(1);
expect(network.dialled).toEqual([PUBLIC_ADDRESS]);
expect(upstream.requests).toHaveLength(1);
expect(internal.connections).toBe(0);
expect(internal.requests).toHaveLength(0);
});
it("keeps the original Host header even though it dialled an IP address", async () => {
const upstream = await startServer();
const dns = rebindingLookup();
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, { method: "POST", body: "{}" }, {
allowPrivateNetwork: false,
lookup: dns.lookup,
socketFactory: network.factory,
error: guardError,
});
expect(upstream.requests[0]?.host).toBe(REBIND_HOST);
expect(upstream.requests[0]?.url).toBe("/mcp");
});
it("sends the hostname as TLS SNI rather than the pinned address", async () => {
// The handshake is never completed: capturing the ClientHello is enough to
// prove SNI carries the configured hostname, and needs no test certificate.
const clientHello = new Promise<Buffer>((resolve) => {
const server = createServer();
openServers.push(server);
server.on("connection", (socket) => {
socket.once("data", (chunk: Buffer) => {
resolve(chunk);
socket.destroy();
});
});
server.listen(0, "127.0.0.1", () => {
const port = (server.address() as AddressInfo).port;
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: port });
void guardedRemoteHttpFetch(`https://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
error: guardError,
}).catch(() => {});
});
});
const hello = await clientHello;
expect(hello.includes(REBIND_HOST)).toBe(true);
expect(hello.includes(PUBLIC_ADDRESS)).toBe(false);
});
it("rejects a peer that turns out to be loopback without writing a request", async () => {
const internal = await startServer();
// A rebind below DNS: resolution approved a public address, but the socket
// lands on loopback anyway. The peer check has to catch it, and has to catch
// it before any request byte is written.
const factory: RemoteHttpSocketFactory = () => {
const socket = netConnect({ host: "127.0.0.1", port: internal.port });
openSockets.push(socket);
return socket;
};
await expect(guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: factory,
error: guardError,
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
expect(internal.requests).toHaveLength(0);
});
it("rejects a hostname whose only resolution is link-local metadata", async () => {
const internal = await startServer();
const network = routingSocketFactory({ "169.254.169.254": internal.port });
await expect(guardedRemoteHttpFetch("http://metadata.rebind.test/latest/meta-data/", {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: "169.254.169.254", family: 4 }],
socketFactory: network.factory,
error: guardError,
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
expect(network.dialled).toEqual([]);
expect(internal.requests).toHaveLength(0);
});
it("rejects a hostname that resolves to a mix of public and private addresses", async () => {
await expect(guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [
{ address: PUBLIC_ADDRESS, family: 4 },
{ address: "10.1.2.3", family: 4 },
],
socketFactory: () => {
throw new Error("must not dial");
},
error: guardError,
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
});
it("does not follow redirects, so the caller re-runs the guard on the next hop", async () => {
const upstream = await startServer((_req, res) => {
res.writeHead(302, { location: "http://127.0.0.1:9/internal" });
res.end();
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const response = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
error: guardError,
});
expect(response.status).toBe(302);
expect(response.headers.get("location")).toBe("http://127.0.0.1:9/internal");
});
it("carries an MCP Streamable HTTP exchange, SSE framing included", async () => {
// The pinned transport replaces `fetch` on the tools/call path, so an MCP
// JSON-RPC reply delivered as a single SSE event has to survive it intact.
const upstream = await startServer((req, res) => {
const chunks: Buffer[] = [];
req.on("data", (chunk: Buffer) => chunks.push(chunk));
req.on("end", () => {
const request = JSON.parse(Buffer.concat(chunks).toString("utf8")) as { method: string };
res.writeHead(200, { "content-type": "text/event-stream" });
res.end(`event: message\ndata: ${JSON.stringify({ jsonrpc: "2.0", id: "1", result: { echo: request.method } })}\n\n`);
});
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const response = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {
method: "POST",
headers: { accept: "application/json, text/event-stream", "content-type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: "1", method: "tools/call", params: {} }),
}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
error: guardError,
});
expect(response.headers.get("content-type")).toBe("text/event-stream");
await expect(response.text()).resolves.toContain('"echo":"tools/call"');
});
it("decodes a compressed response body the way fetch would", async () => {
const upstream = await startServer((_req, res) => {
res.writeHead(200, { "content-type": "application/json", "content-encoding": "gzip" });
res.end(gzipSync(Buffer.from(JSON.stringify({ token_endpoint: "https://auth.example/token" }), "utf8")));
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const response = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/.well-known/oauth-authorization-server`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
error: guardError,
});
await expect(response.json()).resolves.toEqual({ token_endpoint: "https://auth.example/token" });
expect(response.headers.get("content-encoding")).toBeNull();
});
it("gives up on a server that accepts the connection and never answers", async () => {
// Platform `fetch` applied undici's headersTimeout for free. The OAuth
// callers pass no AbortSignal, so the pinned transport has to own the
// deadline or a silent server would hold the request open forever.
const upstream = await startServer(() => {
/* accept the request and never respond */
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const failure = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
responseTimeoutMs: 150,
error: guardError,
}).catch((error) => error);
expect(failure).toMatchObject({ code: "remote_http_response_timeout" });
expect(readRemoteConnectionFailure(failure)).toBe("connection_timeout");
// The deadline has to hand back the socket, not just the request handler:
// a bounded call that still leaks a descriptor per silent peer is the same
// exhaustion bug wearing a timer.
expect(upstream.requests).toHaveLength(1);
await flush();
expect(network.sockets.map((socket) => socket.destroyed)).toEqual([true]);
});
it("gives up on a peer that dribbles response headers forever", async () => {
// This is why the headers deadline is a hard timer rather than
// `req.setTimeout`: an idle timeout never fires against this peer, because
// every trickled header line resets it.
const raw = netCreateServer((socket) => {
socket.write("HTTP/1.1 200 OK\r\n");
const beat = setInterval(() => socket.write("x-pad: keepalive\r\n"), 25);
const stop = () => clearInterval(beat);
socket.on("close", stop);
socket.on("error", stop);
});
await new Promise<void>((resolve) => raw.listen(0, "127.0.0.1", resolve));
const port = (raw.address() as AddressInfo).port;
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: port });
try {
await expect(guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
responseTimeoutMs: 150,
error: guardError,
})).rejects.toMatchObject({ code: "remote_http_response_timeout" });
await flush();
expect(network.sockets.map((socket) => socket.destroyed)).toEqual([true]);
} finally {
await new Promise<void>((resolve) => raw.close(() => resolve()));
}
});
it("gives up on a response body that stalls midway", async () => {
const upstream = await startServer((_req, res) => {
res.writeHead(200, { "content-type": "application/json" });
res.write('{"partial":');
// never finishes the body
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const response = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
responseTimeoutMs: 150,
error: guardError,
});
expect(response.status).toBe(200);
const failure = await response.text().catch((error) => error);
expect(failure).toMatchObject({ code: "remote_http_response_timeout" });
expect(readRemoteConnectionFailure(failure)).toBe("connection_timeout");
await flush();
expect(network.sockets.map((socket) => socket.destroyed)).toEqual([true]);
});
it("preserves the owned body timeout through the MCP initialization wrapper", async () => {
const upstream = await startServer((_req, res) => {
res.writeHead(200, { "content-type": "application/json" });
res.write('{"jsonrpc":"2.0",');
});
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const failure = await initializeMcpHttpSession({
requestId: "owned-deadline",
send: (init) => withMcpConnectionFailure(() => guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, init, {
allowPrivateNetwork: false,
lookup: async () => [{ address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: network.factory,
responseTimeoutMs: 150,
error: guardError,
})),
}).catch((error) => error);
expect(failure).toMatchObject({ name: "McpHttpInitializationError", stage: "initialize", status: null,
message: "Remote MCP initialization returned an invalid response" });
expect(failure.response).toBeUndefined();
expect(isExpectedMcpConnectionFailure(retainMcpConnectionFailure(failure, new HttpError(502, failure.message)))).toBe(true);
await flush();
// One socket for the version probe, one for the handshake; both are released.
expect(network.sockets.map((socket) => socket.destroyed)).toEqual([true, true]);
});
it.each([
["EMFILE", "ECONNREFUSED", false],
["ERR_SSL_UNKNOWN_PROTOCOL", "deadline", false],
["ECONNRESET", "ECONNREFUSED", true],
["ETIMEDOUT", "deadline", true],
] as const)("keeps every failed address relevant to reporting: %s then %s", async (firstCode, lastCode, expected) => {
const first = Object.assign(new Error("first address failed"), { code: firstCode });
const last = Object.assign(new Error("last address failed"), { code: lastCode });
const addresses = ["93.184.216.35", PUBLIC_ADDRESS];
const dialled: string[] = [];
const failure = await withMcpConnectionFailure(() => guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => addresses.map((address) => ({ address, family: 4 })),
socketFactory: ({ address }) => {
dialled.push(address);
const socket = new Socket();
openSockets.push(socket);
if (dialled.length === 1 || lastCode !== "deadline") {
queueMicrotask(() => socket.emit("error", dialled.length === 1 ? first : last));
}
return socket;
},
connectTimeoutMs: 5,
error: guardError,
})).catch((error) => error);
expect(dialled).toEqual(addresses);
if (lastCode === "deadline") expect(failure.message).toBe("Timed out trying to connect to the remote MCP endpoint");
else expect(failure).toBe(last);
expect(isExpectedMcpConnectionFailure(retainMcpConnectionFailure(failure, new HttpError(502, failure.message)))).toBe(expected);
expect(openSockets.every((socket) => socket.destroyed)).toBe(true);
});
it("falls over to the next approved address when the first is unreachable", async () => {
// Pinning must not cost the failover `fetch` gave a multi-homed host: one
// dead A record should not take the connection down with it.
const upstream = await startServer();
const dead = await startServer();
// Close the listener so the address is routable but refuses connections.
await new Promise<void>((resolve) => dead.server.close(() => resolve()));
const network = routingSocketFactory({
"93.184.216.35": dead.port,
[PUBLIC_ADDRESS]: upstream.port,
});
const response = await guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [
{ address: "93.184.216.35", family: 4 },
{ address: PUBLIC_ADDRESS, family: 4 },
],
socketFactory: network.factory,
error: guardError,
});
await expect(response.json()).resolves.toEqual({ ok: true });
expect(network.dialled).toEqual(["93.184.216.35", PUBLIC_ADDRESS]);
});
it("keeps a successful fallback unchanged even after an unknown first-address failure", async () => {
const upstream = await startServer();
const network = routingSocketFactory({ [PUBLIC_ADDRESS]: upstream.port });
const dialled: string[] = [];
const response = await withMcpConnectionFailure(() => guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [{ address: "93.184.216.35", family: 4 }, { address: PUBLIC_ADDRESS, family: 4 }],
socketFactory: (target) => {
dialled.push(target.address);
if (target.address === PUBLIC_ADDRESS) return network.factory(target);
const socket = new Socket();
openSockets.push(socket);
queueMicrotask(() => socket.emit("error", Object.assign(new Error("local limit"), { code: "EMFILE" })));
return socket;
},
error: guardError,
}));
expect(dialled).toEqual(["93.184.216.35", PUBLIC_ADDRESS]);
await expect(response.json()).resolves.toEqual({ ok: true });
expect(readRemoteConnectionFailure(response)).toBeNull();
expect(upstream.requests).toHaveLength(1);
});
it("fails closed instead of falling over when a peer fails the address check", async () => {
// Failover covers unreachable addresses only. A peer that answers from an
// unapproved address is the rebinding defence firing, and must not be
// retried past.
const internal = await startServer();
const upstream = await startServer();
const dialled: string[] = [];
const factory: RemoteHttpSocketFactory = (target) => {
dialled.push(target.address);
const socket = netConnect({ host: "127.0.0.1", port: internal.port });
openSockets.push(socket);
return socket;
};
await expect(guardedRemoteHttpFetch(`http://${REBIND_HOST}/mcp`, {}, {
allowPrivateNetwork: false,
lookup: async () => [
{ address: "93.184.216.35", family: 4 },
{ address: PUBLIC_ADDRESS, family: 4 },
],
socketFactory: factory,
error: guardError,
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
expect(dialled).toEqual(["93.184.216.35"]);
expect(internal.requests).toHaveLength(0);
expect(upstream.requests).toHaveLength(0);
});
it("still refuses a private IP literal before any transport runs", async () => {
await expect(guardedRemoteHttpFetch("http://169.254.169.254/latest/meta-data/", {}, {
allowPrivateNetwork: false,
error: guardError,
unpinnedFetch: async () => {
throw new Error("must not fetch");
},
socketFactory: () => {
throw new Error("must not dial");
},
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
});
it("uses platform fetch for a public IP literal, where nothing can be re-resolved", async () => {
const calls: string[] = [];
const response = await guardedRemoteHttpFetch("https://93.184.216.34/mcp", { method: "POST" }, {
allowPrivateNetwork: false,
error: guardError,
unpinnedFetch: async (input, init) => {
calls.push(`${init?.method} ${String(input)} ${init?.redirect}`);
return new Response("{}", { status: 200 });
},
socketFactory: () => {
throw new Error("must not dial");
},
});
expect(response.status).toBe(200);
expect(calls).toEqual(["POST https://93.184.216.34/mcp manual"]);
});
it("uses platform fetch for an allowed private IP literal", async () => {
const calls: string[] = [];
const response = await guardedRemoteHttpFetch("http://127.0.0.1:9/mcp", {}, {
allowPrivateNetwork: true,
error: guardError,
unpinnedFetch: async (input) => {
calls.push(String(input));
return new Response("{}", { status: 200 });
},
socketFactory: () => {
throw new Error("must not dial");
},
});
expect(response.status).toBe(200);
expect(calls).toEqual(["http://127.0.0.1:9/mcp"]);
});
it("never invokes platform fetch for a link-local literal in private mode", async () => {
const calls: string[] = [];
await expect(guardedRemoteHttpFetch("http://169.254.169.254/latest/meta-data/", {}, {
allowPrivateNetwork: true,
error: guardError,
unpinnedFetch: async (input) => {
calls.push(String(input));
return new Response("{}", { status: 200 });
},
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
expect(calls).toEqual([]);
});
it("pins an allowed private hostname and rejects a link-local peer before request bytes", async () => {
const internal = await startServer();
const factory: RemoteHttpSocketFactory = () => {
const socket = netConnect({ host: "127.0.0.1", port: internal.port });
openSockets.push(socket);
Object.defineProperty(socket, "remoteAddress", { get: () => "169.254.169.254", configurable: true });
return socket;
};
await expect(guardedRemoteHttpFetch("http://lan-service.example/mcp", {}, {
allowPrivateNetwork: true,
lookup: async () => [{ address: "10.0.0.8", family: 4 }],
socketFactory: factory,
error: guardError,
unpinnedFetch: async () => {
throw new Error("hostnames must remain pinned");
},
})).rejects.toMatchObject({ code: "remote_http_private_endpoint" });
expect(internal.requests).toHaveLength(0);
});
});