Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

fix(network): pair guarded fetch with its Undici dispatcher

Seth Wilson72e459dfbcbf
diff --git a/src/utils/ssrf-dispatch.test.ts b/src/utils/ssrf-dispatch.test.ts
new file mode 100644
index 00000000..8468f32d
--- /dev/null
+++ b/src/utils/ssrf-dispatch.test.ts
@@ -0,0 +1,126 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+// Exercise the real guardedFetch transport against a local server without
+// public network access. Only this isolated test module enables the existing
+// private-fetch override; production validation is covered by ssrf.test.ts.
+const originalPrivateFetch = vi.hoisted(() => {
+ const previous = process.env.MERCURY_ALLOW_PRIVATE_FETCH;
+ process.env.MERCURY_ALLOW_PRIVATE_FETCH = '1';
+ return previous;
+});
+vi.mock('node:dns', () => ({
+ lookup: vi.fn((_hostname: string, options: { all?: boolean }, callback: (...args: unknown[]) => void) => {
+ if (options?.all) callback(null, [{ address: '127.0.0.1', family: 4 }]);
+ else callback(null, '127.0.0.1', 4);
+ }),
+}));
+
+import { lookup } from 'node:dns';
+import { createGuardedFetch, guardedFetch } from './ssrf.js';
+
+let server: Server;
+let base: string;
+let requests = 0;
+
+beforeAll(async () => {
+ server = createServer((req, res) => {
+ requests++;
+ if (req.url === '/redirect') return void res.writeHead(302, { location: '/echo' }).end();
+ if (req.url === '/private') return void res.writeHead(302, { location: 'http://127.0.0.1/private' }).end();
+ if (req.url === '/loop') return void res.writeHead(302, { location: '/loop' }).end();
+ if (req.url === '/pending') return; // cancelled by the test's AbortSignal
+ if (req.url === '/stream') {
+ res.writeHead(200, { 'content-type': 'text/plain' });
+ res.write('first chunk');
+ return; // cancelled through the response body
+ }
+ let body = '';
+ req.on('data', (chunk) => { body += chunk; });
+ req.on('end', () => res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({
+ method: req.method, body, auth: req.headers.authorization ?? null, contentType: req.headers['content-type'] ?? null,
+ })));
+ });
+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+ base = `http://mercury-fixture.test:${(server.address() as AddressInfo).port}`;
+});
+
+afterAll(async () => {
+ server.closeAllConnections();
+ await new Promise<void>((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
+ if (originalPrivateFetch === undefined) delete process.env.MERCURY_ALLOW_PRIVATE_FETCH;
+ else process.env.MERCURY_ALLOW_PRIVATE_FETCH = originalPrivateFetch;
+});
+
+describe('guarded Fetch transport compatibility', () => {
+ it('follows validated redirects in the web-content fetch path', async () => {
+ const response = await guardedFetch(`${base}/redirect`, new AbortController().signal, { authorization: 'Bearer fixture' });
+ expect(response.url).toBe(`${base}/echo`);
+ expect(await response.json()).toMatchObject({ method: 'GET', auth: 'Bearer fixture' });
+ });
+
+ it('validates each redirect and retains the redirect bound', async () => {
+ await expect(guardedFetch(`${base}/private`, new AbortController().signal)).rejects.toThrow(/private\/internal/);
+ await expect(guardedFetch(`${base}/loop`, new AbortController().signal)).rejects.toThrow('too many redirects');
+ });
+
+ it('pins the validated hostname without a second DNS lookup', async () => {
+ vi.mocked(lookup).mockClear();
+ const url = base.replace('mercury-fixture.test', 'pinned-fixture.test');
+ const response = await createGuardedFetch({ allowPrivate: true })(`${url}/echo`);
+ expect(await response.json()).toMatchObject({ method: 'GET' });
+ expect(lookup).toHaveBeenCalledTimes(1);
+ expect(lookup).toHaveBeenCalledWith('pinned-fixture.test', { all: true }, expect.any(Function));
+ });
+
+ it('accepts native Headers and FormData without losing multipart fields', async () => {
+ const form = new FormData();
+ form.append('note', 'multipart fixture');
+ form.append('file', new Blob(['file fixture'], { type: 'text/plain' }), 'fixture.txt');
+ const response = await createGuardedFetch({ allowPrivate: true })(`${base}/echo`, {
+ method: 'POST', headers: new Headers({ authorization: 'Bearer fixture' }), body: form,
+ });
+ const output = await response.json() as { body: string; contentType: string; auth: string };
+ expect(output.auth).toBe('Bearer fixture');
+ expect(output.contentType).toMatch(/^multipart\/form-data; boundary=/);
+ expect(output.body).toContain('name="note"');
+ expect(output.body).toContain('multipart fixture');
+ expect(output.body).toContain('filename="fixture.txt"');
+ expect(output.body).toContain('file fixture');
+ });
+
+ it('forwards a native streaming request body', async () => {
+ const body = new ReadableStream({ start(controller) { controller.enqueue(new TextEncoder().encode('streamed input')); controller.close(); } });
+ const init: RequestInit & { duplex: 'half' } = { method: 'POST', body, duplex: 'half' };
+ const response = await createGuardedFetch({ allowPrivate: true })(`${base}/echo`, init);
+ expect(await response.json()).toMatchObject({ body: 'streamed input' });
+ });
+
+ it('rejects pre-aborted requests without sending them', async () => {
+ const before = requests;
+ const controller = new AbortController();
+ controller.abort();
+ await expect(createGuardedFetch({ allowPrivate: true })(`${base}/echo`, { signal: controller.signal })).rejects.toMatchObject({ name: 'AbortError' });
+ expect(requests).toBe(before);
+ });
+
+ it('aborts an in-flight request before headers arrive', async () => {
+ const controller = new AbortController();
+ const started = new Promise<void>((resolve) => server.once('request', () => resolve()));
+ const pending = createGuardedFetch({ allowPrivate: true })(`${base}/pending`, { signal: controller.signal });
+ const rejected = expect(pending).rejects.toMatchObject({ name: 'AbortError' });
+ await started;
+ controller.abort();
+ await rejected;
+ });
+
+ it('cancels an unread streaming response body and releases the connection', async () => {
+ const closed = new Promise<void>((resolve) => server.once('request', (_req, res) => res.once('close', resolve)));
+ const response = await createGuardedFetch({ allowPrivate: true })(`${base}/stream`);
+ await response.body!.cancel();
+ await closed;
+ const next = await createGuardedFetch({ allowPrivate: true })(`${base}/echo`);
+ expect(await next.json()).toMatchObject({ method: 'GET' });
+ });
+});
diff --git a/src/utils/ssrf.ts b/src/utils/ssrf.ts
index f0c4c26c..0fc2a690 100644
--- a/src/utils/ssrf.ts
+++ b/src/utils/ssrf.ts
@@ -15,7 +15,7 @@
import { lookup } from 'node:dns';
import { isIP } from 'node:net';
-import { Agent } from 'undici';
+import { Agent, fetch as undiciFetch } from 'undici';
const DEFAULT_HEADERS = {
'User-Agent': 'Mercury-Agent/0.1.0',
@@ -188,7 +188,17 @@ const guardedAgent = new Agent({
},
});
-type FetchInitWithDispatcher = RequestInit & { dispatcher?: unknown };
+type FetchInitWithDispatcher = RequestInit & { dispatcher: Agent };
+
+// A dispatcher and fetch must speak the same Undici protocol. Node's bundled
+// fetch can be newer than our dependency (Node 26 uses the new handler API),
+// so passing this package's Agent to global fetch fails before any request.
+// Keep the existing web Fetch API types at the boundary: the package and Node
+// ship separately versioned declarations for the same request/response APIs.
+const fetchWithDispatcher = undiciFetch as unknown as (
+ input: URL,
+ init: FetchInitWithDispatcher,
+) => Promise<Response>;
/** Fetch with SSRF validation on the initial URL AND every redirect hop. */
export async function guardedFetch(rawUrl: string, signal: AbortSignal, headers?: Record<string, string>): Promise<Response> {
@@ -204,7 +214,7 @@ export async function guardedFetch(rawUrl: string, signal: AbortSignal, headers?
headers: headers ?? DEFAULT_HEADERS,
dispatcher: guardedAgent,
};
- const resp = await fetch(url, init);
+ const resp = await fetchWithDispatcher(url, init);
if (resp.status >= 300 && resp.status < 400) {
const location = resp.headers.get('location');
if (location) {
@@ -269,7 +279,7 @@ export function createGuardedFetch(options: { allowPrivate?: boolean; privateHin
if (pinned) guardedFetchPins.acquire(host, pinned);
try {
const guardedInit: FetchInitWithDispatcher = { ...init, redirect: 'manual', dispatcher: guardedFetchAgent };
- return await fetch(url, guardedInit);
+ return await fetchWithDispatcher(url, guardedInit);
} finally {
if (pinned) guardedFetchPins.release(host);
}