Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 421 lines 17.4 KB
Raw
1 import { lookup } from 'node:dns/promises'; // we're in a Node.js-specific module
2 import { isIP } from 'node:net';
3 import { ComposioBlockedInternalUrlError } from '../errors/SsrfErrors';
4 import {
5 createPinnedDispatcher,
6 hasCustomGlobalDispatcher,
7 pinnedHttpFetch,
8 } from './pinnedDispatcher.node';
9
10 /**
11 * SSRF guard for user-supplied URL file inputs.
12 *
13 * `composio.files.upload(url)`, Tool Router session file uploads, and automatic
14 * file upload during tool execution fetch arbitrary user-provided URLs. Without
15 * a guard, a caller (or a tool argument produced by an LLM) can point the SDK at
16 * internal infrastructure — loopback, RFC1918 ranges, link-local cloud-metadata
17 * endpoints (`169.254.169.254`), or a public URL that 3xx-redirects into internal
18 * space — turning the SDK into a server-side request forgery probe.
19 *
20 * This module validates the *resolved* address (not just the hostname string,
21 * which defeats decimal/octal/hex IP obfuscation) before every fetch, and
22 * follows redirects manually so each hop is re-validated.
23 *
24 * The address that was validated is also the address connected to: `fetch` gets
25 * a dispatcher pinned to it (see {@link createPinnedDispatcher}), so the
26 * hostname is never resolved a second time. Without that, a name could resolve
27 * to a public address during validation and rebind to an internal one before
28 * the connect — a TOCTOU window the Python guard closes the same way.
29 *
30 * By default, a hop whose effective dispatcher is a configured route — a
31 * caller-supplied `init.dispatcher`, a non-stock global dispatcher (a
32 * `ProxyAgent` or `EnvHttpProxyAgent` installed via `setGlobalDispatcher`), or
33 * the runtime's env-proxy mode (automatic on Bun, opt-in via
34 * `NODE_USE_ENV_PROXY` on Node) — keeps only the
35 * pre-flight validation. Pinning would dial the validated address instead of
36 * the proxy, and the proxy resolves the hostname itself where the SDK cannot
37 * see or pin that resolution. The Python guard carries the same residual for
38 * the same reason (`_proxy_applies`). Callers that cannot accept that residual
39 * can set `requirePinnedConnection`, which fails closed before fetching.
40 */
41
42 const MAX_REDIRECTS = 5;
43
44 export interface SsrfSafeFetchOptions {
45 /** Maximum number of redirects to follow. Defaults to 5. */
46 maxRedirects?: number;
47 /**
48 * Refuse a request when a configured dispatcher or environment proxy means
49 * the connection cannot be pinned to the address validated by the guard.
50 */
51 requirePinnedConnection?: boolean;
52 }
53
54 /**
55 * The Fetch standard's "redirect status" set. A 3xx outside it is not a
56 * redirect to follow even when it carries a `location` — `304 Not Modified`
57 * and `305 Use Proxy` most of all, and following those would replay the
58 * request against a target the caller never asked for. The Python guard
59 * follows the same set (`_REDIRECT_STATUS_CODES`).
60 */
61 const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
62
63 /**
64 * Headers that describe a request body, so they have to go when the body does:
65 * the Fetch standard's "request-body-header name" set, plus the two the Python
66 * guard also drops because `requests` recomputes them from the body it sends.
67 */
68 const BODY_HEADERS = [
69 'content-encoding',
70 'content-language',
71 'content-length',
72 'content-location',
73 'content-type',
74 'transfer-encoding',
75 ];
76
77 /**
78 * The method the hop after a redirect uses, or `null` to replay as-is. A
79 * returned method also means the request body goes.
80 *
81 * These are the Fetch standard's redirect rules, which following redirects by
82 * hand (`redirect: 'manual'`) means `fetch` never applies for us: `303` points
83 * at a result URL that has no use for the original body, so every method loses
84 * it and everything but `HEAD` becomes a `GET`; `301`/`302` do the same to a
85 * `POST` only; `307`/`308` replay both. Without this, a `303` answering an
86 * upload would PUT the payload again at a URL that expects a GET. The Python
87 * guard applies the same rules in `safe_request`.
88 */
89 const redirectRewrite = (status: number, method: string): string | null => {
90 if (status === 303) return method === 'HEAD' ? 'HEAD' : 'GET';
91 if ((status === 301 || status === 302) && method === 'POST') return 'GET';
92 return null;
93 };
94
95 /**
96 * Headers that carry a credential for the origin the request was addressed
97 * to, so they must not follow a redirect to a different origin. The Fetch
98 * standard strips `Authorization` on a cross-origin redirect; `Cookie` and
99 * `Proxy-Authorization` go with it the way `requests` and curl drop them on a
100 * host change. `redirect: 'manual'` means `fetch` never applies that rule for
101 * us either. The Python guard drops the same three (`_CREDENTIAL_HEADERS`).
102 */
103 const CREDENTIAL_HEADERS = ['authorization', 'cookie', 'proxy-authorization'];
104
105 const applyRedirectSemantics = (
106 init: RequestInit,
107 status: number,
108 fromUrl: string,
109 toUrl: string
110 ): RequestInit => {
111 const method = redirectRewrite(status, (init.method ?? 'GET').toUpperCase());
112 const crossOrigin = new URL(fromUrl).origin !== new URL(toUrl).origin;
113 if (method === null && !crossOrigin) return init;
114
115 const headers = new Headers(init.headers);
116 if (method !== null) for (const name of BODY_HEADERS) headers.delete(name);
117 if (crossOrigin) for (const name of CREDENTIAL_HEADERS) headers.delete(name);
118 if (method === null) return { ...init, headers };
119 return { ...init, method, body: undefined, headers };
120 };
121
122 /**
123 * Whether the runtime would route `url` through an env proxy the SDK cannot
124 * see into. Bun honors proxy environment variables automatically. Node's
125 * built-in `fetch` requires the `NODE_USE_ENV_PROXY` opt-in (Node >= 24), so
126 * a bare env-var check on Node would drop pinning for users whose fetch never
127 * proxied.
128 *
129 * `NO_PROXY=*` is the one bypass honored precisely (nothing is proxied, so
130 * pinning is safe again); per-host `NO_PROXY` entries are treated
131 * conservatively as proxied rather than parsed.
132 */
133 const envProxyApplies = (url: URL, isBun: boolean): boolean => {
134 const useEnvProxy =
135 isBun || ['1', 'true'].includes((process.env.NODE_USE_ENV_PROXY ?? '').toLowerCase());
136 if (!useEnvProxy) return false;
137 if ((process.env.NO_PROXY ?? process.env.no_proxy ?? '') === '*') return false;
138 const schemeVar = url.protocol === 'https:' ? 'HTTPS_PROXY' : 'HTTP_PROXY';
139 return Boolean(process.env[schemeVar] ?? process.env[schemeVar.toLowerCase()]);
140 };
141
142 const ipv4ToLong = (ip: string): number => {
143 const [a, b, c, d] = ip.split('.').map(Number);
144 return (((a << 24) >>> 0) | (b << 16) | (c << 8) | d) >>> 0;
145 };
146
147 // Address blocks that must never be reachable from a user-supplied URL.
148 // (RFC1918 private, loopback, link-local, CGNAT, TEST-NET, benchmarking,
149 // multicast, and reserved ranges.)
150 const IPV4_BLOCKED_CIDRS: ReadonlyArray<readonly [string, number]> = [
151 ['0.0.0.0', 8], // "this" network / unspecified
152 ['10.0.0.0', 8], // private
153 ['100.64.0.0', 10], // carrier-grade NAT
154 ['127.0.0.0', 8], // loopback
155 ['169.254.0.0', 16], // link-local (incl. cloud metadata 169.254.169.254)
156 ['172.16.0.0', 12], // private
157 ['192.0.0.0', 24], // IETF protocol assignments
158 ['192.0.2.0', 24], // TEST-NET-1
159 ['192.88.99.0', 24], // 6to4 relay anycast (deprecated, RFC 7526)
160 ['192.168.0.0', 16], // private
161 ['198.18.0.0', 15], // benchmarking
162 ['198.51.100.0', 24], // TEST-NET-2
163 ['203.0.113.0', 24], // TEST-NET-3
164 ['224.0.0.0', 4], // multicast
165 ['240.0.0.0', 4], // reserved (incl. 255.255.255.255 broadcast)
166 ];
167
168 const isBlockedIpv4Long = (long: number): boolean =>
169 IPV4_BLOCKED_CIDRS.some(([base, bits]) => {
170 const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
171 return (long & mask) === (ipv4ToLong(base) & mask);
172 });
173
174 /**
175 * Expand an IPv6 string into its 8 16-bit groups, converting any trailing
176 * dotted-quad (e.g. `::ffff:1.2.3.4`) into hex groups first. Returns `null` when
177 * the input cannot be parsed.
178 */
179 const expandIpv6 = (ip: string): number[] | null => {
180 let addr = ip;
181 const v4Match = addr.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
182 if (v4Match) {
183 const long = ipv4ToLong(v4Match[2]);
184 addr = `${v4Match[1]}${((long >>> 16) & 0xffff).toString(16)}:${(long & 0xffff).toString(16)}`;
185 }
186
187 const halves = addr.split('::');
188 if (halves.length > 2) return null;
189
190 const head = halves[0] ? halves[0].split(':') : [];
191 const tail = halves.length === 2 ? (halves[1] ? halves[1].split(':') : []) : [];
192
193 let groups: string[];
194 if (halves.length === 2) {
195 const missing = 8 - head.length - tail.length;
196 if (missing < 0) return null;
197 groups = [...head, ...Array(missing).fill('0'), ...tail];
198 } else {
199 groups = head;
200 }
201
202 if (groups.length !== 8) return null;
203 return groups.map(g => parseInt(g || '0', 16));
204 };
205
206 const isBlockedIpv6 = (ip: string): boolean => {
207 const h = expandIpv6(ip);
208 if (!h) return true; // fail closed on anything we cannot parse
209
210 // :: (unspecified) and ::1 (loopback)
211 if (h.every(x => x === 0)) return true;
212 if (h.slice(0, 7).every(x => x === 0) && h[7] === 1) return true;
213
214 // Addresses that embed an IPv4 address in their low 32 bits must be validated
215 // against the IPv4 blocklist, otherwise `::127.0.0.1` / `::169.254.169.254`
216 // (and mapped/NAT64 forms) would pass as "public" IPv6 and reach internal
217 // targets. Covers:
218 // - IPv4-mapped ::ffff:0:0/96 (h[5] === 0xffff)
219 // - IPv4-compatible ::/96 (deprecated, h[5] === 0) — incl. ::a.b.c.d
220 // - NAT64 64:ff9b::/96
221 const highBitsZero = h[0] === 0 && h[1] === 0 && h[2] === 0 && h[3] === 0 && h[4] === 0;
222 const isMappedOrCompat = highBitsZero && (h[5] === 0xffff || h[5] === 0);
223 const isNat64 =
224 h[0] === 0x0064 && h[1] === 0xff9b && h[2] === 0 && h[3] === 0 && h[4] === 0 && h[5] === 0;
225 if (isMappedOrCompat || isNat64) {
226 return isBlockedIpv4Long((((h[6] << 16) >>> 0) | h[7]) >>> 0);
227 }
228
229 // Transition and tunnel ranges. Each one either carries an arbitrary IPv4
230 // address in its low bits or is reserved, so a public-looking literal here
231 // can still name internal space: `2002:7f00:1::` is 6to4 for `127.0.0.1`.
232 // Blocking the whole range rather than decoding it matches the Python guard,
233 // where `ipaddress.is_global` already rejects all of them.
234 if (h[0] === 0x2001 && (h[1] & 0xfe00) === 0) return true; // IETF protocol assignments 2001::/23 (incl. Teredo)
235 if (h[0] === 0x2001 && h[1] === 0x0db8) return true; // documentation 2001:db8::/32
236 if (h[0] === 0x2002) return true; // 6to4 2002::/16
237 if (h[0] === 0x0064 && h[1] === 0xff9b && h[2] === 0x0001) return true; // local-use NAT64 64:ff9b:1::/48
238 if (h[0] === 0x0100 && h[1] === 0 && h[2] === 0 && h[3] === 0) return true; // discard-only 100::/64
239
240 if ((h[0] & 0xfe00) === 0xfc00) return true; // unique local fc00::/7
241 if ((h[0] & 0xffc0) === 0xfe80) return true; // link-local fe80::/10
242 if ((h[0] & 0xffc0) === 0xfec0) return true; // site-local fec0::/10 (deprecated)
243 if ((h[0] & 0xff00) === 0xff00) return true; // multicast ff00::/8
244
245 return false;
246 };
247
248 /**
249 * True when `ip` is a private, loopback, link-local, or otherwise
250 * non-publicly-routable address. Fails closed (returns `true`) for anything that
251 * is not a valid IPv4/IPv6 literal.
252 */
253 export const isBlockedIp = (ip: string): boolean => {
254 const family = isIP(ip);
255 if (family === 4) return isBlockedIpv4Long(ipv4ToLong(ip));
256 if (family === 6) return isBlockedIpv6(ip);
257 return true;
258 };
259
260 /**
261 * Validate a single URL: it must be http(s), its host must resolve, and every
262 * resolved address must be publicly routable. Throws
263 * {@link ComposioBlockedInternalUrlError} otherwise.
264 *
265 * @returns the validated addresses to connect to, in resolver order. Callers
266 * must connect to *those* rather than let the client resolve the hostname
267 * again; see {@link ssrfSafeFetch}.
268 */
269 export const assertSafeFetchTarget = async (rawUrl: string): Promise<string[]> => {
270 let url: URL;
271 try {
272 url = new URL(rawUrl);
273 } catch {
274 throw new ComposioBlockedInternalUrlError('Refusing to fetch a malformed URL', { url: rawUrl });
275 }
276
277 if (url.protocol !== 'http:' && url.protocol !== 'https:') {
278 throw new ComposioBlockedInternalUrlError(
279 `Refusing to fetch a non-http(s) URL (scheme "${url.protocol}")`,
280 { url: rawUrl }
281 );
282 }
283
284 const host = url.hostname.replace(/^\[|\]$/g, '');
285
286 let resolved: Array<{ address: string }>;
287 try {
288 resolved = await lookup(host, { all: true, verbatim: true });
289 } catch {
290 throw new ComposioBlockedInternalUrlError(`Could not resolve host "${host}"`, { url: rawUrl });
291 }
292
293 if (resolved.length === 0) {
294 throw new ComposioBlockedInternalUrlError(`Could not resolve host "${host}"`, { url: rawUrl });
295 }
296
297 for (const { address } of resolved) {
298 if (isBlockedIp(address)) {
299 throw new ComposioBlockedInternalUrlError(
300 `Refusing to fetch "${host}" — it resolves to a private, loopback, or link-local address`,
301 { url: rawUrl, resolvedIp: address }
302 );
303 }
304 }
305
306 // Every answer was validated, so all of them are safe to connect to, and
307 // resolver order is the system's own address preference.
308 return resolved.map(({ address }) => address);
309 };
310
311 /**
312 * Drop-in replacement for `fetch` that blocks SSRF. Validates the target, then
313 * connects to the address it validated, and re-validates and re-pins every
314 * redirect hop (redirects are followed manually up to {@link MAX_REDIRECTS}).
315 * Intermediate redirect bodies are cancelled; non-redirect responses are
316 * returned unchanged. Each hop carries the method, body, and credential headers
317 * the Fetch standard says it should — see {@link applyRedirectSemantics}.
318 *
319 * By default, a hop whose effective dispatcher is a configured route
320 * (caller-supplied `init.dispatcher`, non-stock global dispatcher, env-proxy
321 * mode) is *not* pinned. Set `requirePinnedConnection` to fail closed instead.
322 */
323 export const ssrfSafeFetch = async (
324 rawUrl: string,
325 init: RequestInit = {},
326 optionsOrMaxRedirects: SsrfSafeFetchOptions | number = {}
327 ): Promise<Response> => {
328 const options =
329 typeof optionsOrMaxRedirects === 'number'
330 ? { maxRedirects: optionsOrMaxRedirects }
331 : optionsOrMaxRedirects;
332 const maxRedirects = options.maxRedirects ?? MAX_REDIRECTS;
333 let currentUrl = rawUrl;
334 // Rebound per hop: a redirect can drop the method and body (see
335 // `applyRedirectSemantics`), and the following hops must send what is left.
336 let currentInit = init;
337
338 for (let hop = 0; hop <= maxRedirects; hop++) {
339 const addresses = await assertSafeFetchTarget(currentUrl);
340 const isBun = typeof process.versions.bun === 'string';
341
342 // Pinning replaces the connect target; through a configured route that
343 // would dial the validated origin instead of the route's next hop (the
344 // proxy), so those hops keep the pre-flight check only.
345 const callerDispatcher = (currentInit as RequestInit & { dispatcher?: unknown }).dispatcher;
346 const respectConfiguredRoute =
347 callerDispatcher !== undefined ||
348 envProxyApplies(new URL(currentUrl), isBun) ||
349 hasCustomGlobalDispatcher();
350
351 if (options.requirePinnedConnection && respectConfiguredRoute) {
352 throw new ComposioBlockedInternalUrlError(
353 'Refusing to fetch through a configured network route because the validated address cannot be pinned',
354 { url: currentUrl }
355 );
356 }
357
358 const dispatcher =
359 respectConfiguredRoute || isBun ? undefined : await createPinnedDispatcher(addresses);
360
361 let response: Response;
362 try {
363 if (isBun && !respectConfiguredRoute) {
364 response = await pinnedHttpFetch(
365 currentUrl,
366 { ...currentInit, redirect: 'manual' },
367 addresses
368 );
369 } else {
370 // `dispatcher` is a Node-only extension to `RequestInit`.
371 response = await fetch(
372 currentUrl,
373 (dispatcher === undefined
374 ? { ...currentInit, redirect: 'manual' }
375 : { ...currentInit, redirect: 'manual', dispatcher }) as RequestInit
376 );
377 }
378 } catch (error) {
379 if (dispatcher !== undefined) {
380 await dispatcher.close().catch(() => undefined);
381 }
382 throw error;
383 }
384
385 // `close()` is graceful: it waits for the in-flight request — including a
386 // body still being streamed to the caller — before releasing the socket.
387 if (dispatcher !== undefined) {
388 void dispatcher.close().catch(() => undefined);
389 }
390
391 const isRedirect =
392 REDIRECT_STATUS_CODES.has(response.status) && response.headers.has('location');
393 if (!isRedirect) {
394 return response;
395 }
396
397 // Only `location` is read from a redirect, so release its body explicitly rather
398 // than leaving it to the garbage collector (mirrors `readResponseBodyWithLimit`).
399 await response.body?.cancel().catch(() => undefined);
400
401 const nextUrl = new URL(response.headers.get('location')!, currentUrl).toString();
402 currentInit = applyRedirectSemantics(currentInit, response.status, currentUrl, nextUrl);
403 currentUrl = nextUrl;
404 }
405
406 throw new ComposioBlockedInternalUrlError(
407 `Refusing to fetch: too many redirects (max ${maxRedirects})`,
408 { url: rawUrl }
409 );
410 };
411
412 /**
413 * {@link ssrfSafeFetch} for call sites that must keep working on every runtime.
414 *
415 * `ssrfSafeFetch` fails closed in edge runtimes, which is right for a URL the
416 * caller chose to upload — the alternative is fetching it unvalidated — but not
417 * for Tool Router session file transfers, where refusing would remove a working
418 * feature from Workers rather than close a hole reachable there. On Node this
419 * is the full guard; only the edge build differs.
420 */
421 export const ssrfSafeFetchWhereSupported = ssrfSafeFetch;