Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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; |