Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
import { lookup } from 'node:dns/promises'; // we're in a Node.js-specific module
import { isIP } from 'node:net';
import { ComposioBlockedInternalUrlError } from '../errors/SsrfErrors';
import {
createPinnedDispatcher,
hasCustomGlobalDispatcher,
pinnedHttpFetch,
} from './pinnedDispatcher.node';
/**
* SSRF guard for user-supplied URL file inputs.
*
* `composio.files.upload(url)`, Tool Router session file uploads, and automatic
* file upload during tool execution fetch arbitrary user-provided URLs. Without
* a guard, a caller (or a tool argument produced by an LLM) can point the SDK at
* internal infrastructure — loopback, RFC1918 ranges, link-local cloud-metadata
* endpoints (`169.254.169.254`), or a public URL that 3xx-redirects into internal
* space — turning the SDK into a server-side request forgery probe.
*
* This module validates the *resolved* address (not just the hostname string,
* which defeats decimal/octal/hex IP obfuscation) before every fetch, and
* follows redirects manually so each hop is re-validated.
*
* The address that was validated is also the address connected to: `fetch` gets
* a dispatcher pinned to it (see {@link createPinnedDispatcher}), so the
* hostname is never resolved a second time. Without that, a name could resolve
* to a public address during validation and rebind to an internal one before
* the connect — a TOCTOU window the Python guard closes the same way.
*
* Residual: a hop whose effective dispatcher is a configured route — a
* caller-supplied `init.dispatcher`, a non-stock global dispatcher (a
* `ProxyAgent` or `EnvHttpProxyAgent` installed via `setGlobalDispatcher`), or
* the runtime's env-proxy mode (automatic on Bun, opt-in via
* `NODE_USE_ENV_PROXY` on Node) — keeps only the
* pre-flight validation. Pinning would dial the validated address instead of
* the proxy, and the proxy resolves the hostname itself where the SDK cannot
* see or pin that resolution. The Python guard carries the same residual for
* the same reason (`_proxy_applies`).
*/
const MAX_REDIRECTS = 5;
/**
* The Fetch standard's "redirect status" set. A 3xx outside it is not a
* redirect to follow even when it carries a `location` — `304 Not Modified`
* and `305 Use Proxy` most of all, and following those would replay the
* request against a target the caller never asked for. The Python guard
* follows the same set (`_REDIRECT_STATUS_CODES`).
*/
const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
/**
* Headers that describe a request body, so they have to go when the body does:
* the Fetch standard's "request-body-header name" set, plus the two the Python
* guard also drops because `requests` recomputes them from the body it sends.
*/
const BODY_HEADERS = [
'content-encoding',
'content-language',
'content-length',
'content-location',
'content-type',
'transfer-encoding',
];
/**
* The method the hop after a redirect uses, or `null` to replay as-is. A
* returned method also means the request body goes.
*
* These are the Fetch standard's redirect rules, which following redirects by
* hand (`redirect: 'manual'`) means `fetch` never applies for us: `303` points
* at a result URL that has no use for the original body, so every method loses
* it and everything but `HEAD` becomes a `GET`; `301`/`302` do the same to a
* `POST` only; `307`/`308` replay both. Without this, a `303` answering an
* upload would PUT the payload again at a URL that expects a GET. The Python
* guard applies the same rules in `safe_request`.
*/
const redirectRewrite = (status: number, method: string): string | null => {
if (status === 303) return method === 'HEAD' ? 'HEAD' : 'GET';
if ((status === 301 || status === 302) && method === 'POST') return 'GET';
return null;
};
/**
* Headers that carry a credential for the origin the request was addressed
* to, so they must not follow a redirect to a different origin. The Fetch
* standard strips `Authorization` on a cross-origin redirect; `Cookie` and
* `Proxy-Authorization` go with it the way `requests` and curl drop them on a
* host change. `redirect: 'manual'` means `fetch` never applies that rule for
* us either. The Python guard drops the same three (`_CREDENTIAL_HEADERS`).
*/
const CREDENTIAL_HEADERS = ['authorization', 'cookie', 'proxy-authorization'];
const applyRedirectSemantics = (
init: RequestInit,
status: number,
fromUrl: string,
toUrl: string
): RequestInit => {
const method = redirectRewrite(status, (init.method ?? 'GET').toUpperCase());
const crossOrigin = new URL(fromUrl).origin !== new URL(toUrl).origin;
if (method === null && !crossOrigin) return init;
const headers = new Headers(init.headers);
if (method !== null) for (const name of BODY_HEADERS) headers.delete(name);
if (crossOrigin) for (const name of CREDENTIAL_HEADERS) headers.delete(name);
if (method === null) return { ...init, headers };
return { ...init, method, body: undefined, headers };
};
/**
* Whether the runtime would route `url` through an env proxy the SDK cannot
* see into. Bun honors proxy environment variables automatically. Node's
* built-in `fetch` requires the `NODE_USE_ENV_PROXY` opt-in (Node >= 24), so
* a bare env-var check on Node would drop pinning for users whose fetch never
* proxied.
*
* `NO_PROXY=*` is the one bypass honored precisely (nothing is proxied, so
* pinning is safe again); per-host `NO_PROXY` entries are treated
* conservatively as proxied rather than parsed.
*/
const envProxyApplies = (url: URL, isBun: boolean): boolean => {
const useEnvProxy =
isBun || ['1', 'true'].includes((process.env.NODE_USE_ENV_PROXY ?? '').toLowerCase());
if (!useEnvProxy) return false;
if ((process.env.NO_PROXY ?? process.env.no_proxy ?? '') === '*') return false;
const schemeVar = url.protocol === 'https:' ? 'HTTPS_PROXY' : 'HTTP_PROXY';
return Boolean(process.env[schemeVar] ?? process.env[schemeVar.toLowerCase()]);
};
const ipv4ToLong = (ip: string): number => {
const [a, b, c, d] = ip.split('.').map(Number);
return (((a << 24) >>> 0) | (b << 16) | (c << 8) | d) >>> 0;
};
// Address blocks that must never be reachable from a user-supplied URL.
// (RFC1918 private, loopback, link-local, CGNAT, TEST-NET, benchmarking,
// multicast, and reserved ranges.)
const IPV4_BLOCKED_CIDRS: ReadonlyArray<readonly [string, number]> = [
['0.0.0.0', 8], // "this" network / unspecified
['10.0.0.0', 8], // private
['100.64.0.0', 10], // carrier-grade NAT
['127.0.0.0', 8], // loopback
['169.254.0.0', 16], // link-local (incl. cloud metadata 169.254.169.254)
['172.16.0.0', 12], // private
['192.0.0.0', 24], // IETF protocol assignments
['192.0.2.0', 24], // TEST-NET-1
['192.88.99.0', 24], // 6to4 relay anycast (deprecated, RFC 7526)
['192.168.0.0', 16], // private
['198.18.0.0', 15], // benchmarking
['198.51.100.0', 24], // TEST-NET-2
['203.0.113.0', 24], // TEST-NET-3
['224.0.0.0', 4], // multicast
['240.0.0.0', 4], // reserved (incl. 255.255.255.255 broadcast)
];
const isBlockedIpv4Long = (long: number): boolean =>
IPV4_BLOCKED_CIDRS.some(([base, bits]) => {
const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
return (long & mask) === (ipv4ToLong(base) & mask);
});
/**
* Expand an IPv6 string into its 8 16-bit groups, converting any trailing
* dotted-quad (e.g. `::ffff:1.2.3.4`) into hex groups first. Returns `null` when
* the input cannot be parsed.
*/
const expandIpv6 = (ip: string): number[] | null => {
let addr = ip;
const v4Match = addr.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
if (v4Match) {
const long = ipv4ToLong(v4Match[2]);
addr = `${v4Match[1]}${((long >>> 16) & 0xffff).toString(16)}:${(long & 0xffff).toString(16)}`;
}
const halves = addr.split('::');
if (halves.length > 2) return null;
const head = halves[0] ? halves[0].split(':') : [];
const tail = halves.length === 2 ? (halves[1] ? halves[1].split(':') : []) : [];
let groups: string[];
if (halves.length === 2) {
const missing = 8 - head.length - tail.length;
if (missing < 0) return null;
groups = [...head, ...Array(missing).fill('0'), ...tail];
} else {
groups = head;
}
if (groups.length !== 8) return null;
return groups.map(g => parseInt(g || '0', 16));
};
const isBlockedIpv6 = (ip: string): boolean => {
const h = expandIpv6(ip);
if (!h) return true; // fail closed on anything we cannot parse
// :: (unspecified) and ::1 (loopback)
if (h.every(x => x === 0)) return true;
if (h.slice(0, 7).every(x => x === 0) && h[7] === 1) return true;
// Addresses that embed an IPv4 address in their low 32 bits must be validated
// against the IPv4 blocklist, otherwise `::127.0.0.1` / `::169.254.169.254`
// (and mapped/NAT64 forms) would pass as "public" IPv6 and reach internal
// targets. Covers:
// - IPv4-mapped ::ffff:0:0/96 (h[5] === 0xffff)
// - IPv4-compatible ::/96 (deprecated, h[5] === 0) — incl. ::a.b.c.d
// - NAT64 64:ff9b::/96
const highBitsZero = h[0] === 0 && h[1] === 0 && h[2] === 0 && h[3] === 0 && h[4] === 0;
const isMappedOrCompat = highBitsZero && (h[5] === 0xffff || h[5] === 0);
const isNat64 =
h[0] === 0x0064 && h[1] === 0xff9b && h[2] === 0 && h[3] === 0 && h[4] === 0 && h[5] === 0;
if (isMappedOrCompat || isNat64) {
return isBlockedIpv4Long((((h[6] << 16) >>> 0) | h[7]) >>> 0);
}
// Transition and tunnel ranges. Each one either carries an arbitrary IPv4
// address in its low bits or is reserved, so a public-looking literal here
// can still name internal space: `2002:7f00:1::` is 6to4 for `127.0.0.1`.
// Blocking the whole range rather than decoding it matches the Python guard,
// where `ipaddress.is_global` already rejects all of them.
if (h[0] === 0x2001 && (h[1] & 0xfe00) === 0) return true; // IETF protocol assignments 2001::/23 (incl. Teredo)
if (h[0] === 0x2001 && h[1] === 0x0db8) return true; // documentation 2001:db8::/32
if (h[0] === 0x2002) return true; // 6to4 2002::/16
if (h[0] === 0x0064 && h[1] === 0xff9b && h[2] === 0x0001) return true; // local-use NAT64 64:ff9b:1::/48
if (h[0] === 0x0100 && h[1] === 0 && h[2] === 0 && h[3] === 0) return true; // discard-only 100::/64
if ((h[0] & 0xfe00) === 0xfc00) return true; // unique local fc00::/7
if ((h[0] & 0xffc0) === 0xfe80) return true; // link-local fe80::/10
if ((h[0] & 0xffc0) === 0xfec0) return true; // site-local fec0::/10 (deprecated)
if ((h[0] & 0xff00) === 0xff00) return true; // multicast ff00::/8
return false;
};
/**
* True when `ip` is a private, loopback, link-local, or otherwise
* non-publicly-routable address. Fails closed (returns `true`) for anything that
* is not a valid IPv4/IPv6 literal.
*/
export const isBlockedIp = (ip: string): boolean => {
const family = isIP(ip);
if (family === 4) return isBlockedIpv4Long(ipv4ToLong(ip));
if (family === 6) return isBlockedIpv6(ip);
return true;
};
/**
* Validate a single URL: it must be http(s), its host must resolve, and every
* resolved address must be publicly routable. Throws
* {@link ComposioBlockedInternalUrlError} otherwise.
*
* @returns the validated addresses to connect to, in resolver order. Callers
* must connect to *those* rather than let the client resolve the hostname
* again; see {@link ssrfSafeFetch}.
*/
export const assertSafeFetchTarget = async (rawUrl: string): Promise<string[]> => {
let url: URL;
try {
url = new URL(rawUrl);
} catch {
throw new ComposioBlockedInternalUrlError('Refusing to fetch a malformed URL', { url: rawUrl });
}
if (url.protocol !== 'http:' && url.protocol !== 'https:') {
throw new ComposioBlockedInternalUrlError(
`Refusing to fetch a non-http(s) URL (scheme "${url.protocol}")`,
{ url: rawUrl }
);
}
const host = url.hostname.replace(/^\[|\]$/g, '');
let resolved: Array<{ address: string }>;
try {
resolved = await lookup(host, { all: true, verbatim: true });
} catch {
throw new ComposioBlockedInternalUrlError(`Could not resolve host "${host}"`, { url: rawUrl });
}
if (resolved.length === 0) {
throw new ComposioBlockedInternalUrlError(`Could not resolve host "${host}"`, { url: rawUrl });
}
for (const { address } of resolved) {
if (isBlockedIp(address)) {
throw new ComposioBlockedInternalUrlError(
`Refusing to fetch "${host}" — it resolves to a private, loopback, or link-local address`,
{ url: rawUrl, resolvedIp: address }
);
}
}
// Every answer was validated, so all of them are safe to connect to, and
// resolver order is the system's own address preference.
return resolved.map(({ address }) => address);
};
/**
* Drop-in replacement for `fetch` that blocks SSRF. Validates the target, then
* connects to the address it validated, and re-validates and re-pins every
* redirect hop (redirects are followed manually up to {@link MAX_REDIRECTS}).
* Intermediate redirect bodies are cancelled; non-redirect responses are
* returned unchanged. Each hop carries the method, body, and credential headers
* the Fetch standard says it should — see {@link applyRedirectSemantics}.
*
* A hop whose effective dispatcher is a configured route (caller-supplied
* `init.dispatcher`, non-stock global dispatcher, env-proxy mode) is *not*
* pinned — see the module residual above.
*/
export const ssrfSafeFetch = async (
rawUrl: string,
init: RequestInit = {},
maxRedirects: number = MAX_REDIRECTS
): Promise<Response> => {
let currentUrl = rawUrl;
// Rebound per hop: a redirect can drop the method and body (see
// `applyRedirectSemantics`), and the following hops must send what is left.
let currentInit = init;
for (let hop = 0; hop <= maxRedirects; hop++) {
const addresses = await assertSafeFetchTarget(currentUrl);
const isBun = typeof process.versions.bun === 'string';
// Pinning replaces the connect target; through a configured route that
// would dial the validated origin instead of the route's next hop (the
// proxy), so those hops keep the pre-flight check only.
const callerDispatcher = (currentInit as RequestInit & { dispatcher?: unknown }).dispatcher;
const respectConfiguredRoute =
callerDispatcher !== undefined ||
envProxyApplies(new URL(currentUrl), isBun) ||
hasCustomGlobalDispatcher();
const dispatcher =
respectConfiguredRoute || isBun ? undefined : await createPinnedDispatcher(addresses);
let response: Response;
try {
if (isBun && !respectConfiguredRoute) {
response = await pinnedHttpFetch(
currentUrl,
{ ...currentInit, redirect: 'manual' },
addresses
);
} else {
// `dispatcher` is a Node-only extension to `RequestInit`.
response = await fetch(
currentUrl,
(dispatcher === undefined
? { ...currentInit, redirect: 'manual' }
: { ...currentInit, redirect: 'manual', dispatcher }) as RequestInit
);
}
} catch (error) {
if (dispatcher !== undefined) {
await dispatcher.close().catch(() => undefined);
}
throw error;
}
// `close()` is graceful: it waits for the in-flight request — including a
// body still being streamed to the caller — before releasing the socket.
if (dispatcher !== undefined) {
void dispatcher.close().catch(() => undefined);
}
const isRedirect =
REDIRECT_STATUS_CODES.has(response.status) && response.headers.has('location');
if (!isRedirect) {
return response;
}
// Only `location` is read from a redirect, so release its body explicitly rather
// than leaving it to the garbage collector (mirrors `readResponseBodyWithLimit`).
await response.body?.cancel().catch(() => undefined);
const nextUrl = new URL(response.headers.get('location')!, currentUrl).toString();
currentInit = applyRedirectSemantics(currentInit, response.status, currentUrl, nextUrl);
currentUrl = nextUrl;
}
throw new ComposioBlockedInternalUrlError(
`Refusing to fetch: too many redirects (max ${maxRedirects})`,
{ url: rawUrl }
);
};
/**
* {@link ssrfSafeFetch} for call sites that must keep working on every runtime.
*
* `ssrfSafeFetch` fails closed in edge runtimes, which is right for a URL the
* caller chose to upload — the alternative is fetching it unvalidated — but not
* for Tool Router session file transfers, where refusing would remove a working
* feature from Workers rather than close a hole reachable there. On Node this
* is the full guard; only the edge build differs.
*/
export const ssrfSafeFetchWhereSupported = ssrfSafeFetch;