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 { isIP } from 'node:net'; |
| 2 | import { request as httpRequest } from 'node:http'; |
| 3 | import { request as httpsRequest } from 'node:https'; |
| 4 | import { Readable } from 'node:stream'; |
| 5 | import type { Agent } from 'undici'; |
| 6 | |
| 7 | /** |
| 8 | * The `globalThis` symbols that hold the process-wide dispatcher `fetch` falls |
| 9 | * back to. Every undici in the process shares them — including the one inside |
| 10 | * the Node runtime — and `setGlobalDispatcher` writes both, so reading them |
| 11 | * directly sees the same dispatcher the runtime's own `fetch` would use. |
| 12 | * |
| 13 | * Read rather than imported: importing `undici` installs a dispatcher of its |
| 14 | * own as an import side effect (see {@link loadUndici}), which is exactly what |
| 15 | * this module must not do at load time. |
| 16 | */ |
| 17 | const GLOBAL_DISPATCHER_SYMBOLS = [ |
| 18 | Symbol.for('undici.globalDispatcher.1'), |
| 19 | Symbol.for('undici.globalDispatcher.2'), |
| 20 | ] as const; |
| 21 | |
| 22 | /** |
| 23 | * `undici`, imported on first use rather than at module load. |
| 24 | * |
| 25 | * Importing it runs `if (getGlobalDispatcher() === undefined) setGlobalDispatcher(new Agent())` |
| 26 | * as a side effect, which would hand every unrelated `fetch` in the host |
| 27 | * application this package's undici instead of the runtime's own — a global |
| 28 | * change no caller asked for by importing `@composio/core`. Deferring the |
| 29 | * import to the first pinned request keeps that side effect on the code path |
| 30 | * that actually needs undici, and behind the `hasCustomGlobalDispatcher` check |
| 31 | * that reads the slot's true, pre-import state. |
| 32 | * |
| 33 | * A process that does make a pinned request still ends up on this package's |
| 34 | * `Agent` if nothing had claimed the slot yet. That much is not reversible: |
| 35 | * undici defines the slot non-configurable and writable, so it cannot be |
| 36 | * cleared back to empty — assigning `undefined` leaves the runtime's own |
| 37 | * `fetch` asserting on a missing dispatcher. |
| 38 | */ |
| 39 | let undici: Promise<typeof import('undici')> | undefined; |
| 40 | const loadUndici = (): Promise<typeof import('undici')> => (undici ??= import('undici')); |
| 41 | |
| 42 | const lookupPinnedAddresses = ( |
| 43 | addresses: ReadonlyArray<string>, |
| 44 | options: { all?: boolean }, |
| 45 | callback: ( |
| 46 | error: NodeJS.ErrnoException | null, |
| 47 | address: string | Array<{ address: string; family: number }>, |
| 48 | family?: number |
| 49 | ) => void |
| 50 | ) => { |
| 51 | if (options.all) { |
| 52 | callback( |
| 53 | null, |
| 54 | addresses.map(address => ({ address, family: isIP(address) })) |
| 55 | ); |
| 56 | return; |
| 57 | } |
| 58 | |
| 59 | const [address] = addresses; |
| 60 | callback(null, address, isIP(address)); |
| 61 | }; |
| 62 | |
| 63 | const knownBodyLength = (body: BodyInit | null | undefined): number | undefined => { |
| 64 | if (body === null || body === undefined) return undefined; |
| 65 | if (typeof body === 'string') return new TextEncoder().encode(body).byteLength; |
| 66 | if (body instanceof URLSearchParams) return new TextEncoder().encode(body.toString()).byteLength; |
| 67 | if (body instanceof ArrayBuffer) return body.byteLength; |
| 68 | if (ArrayBuffer.isView(body)) return body.byteLength; |
| 69 | if (body instanceof Blob) return body.size; |
| 70 | return undefined; |
| 71 | }; |
| 72 | |
| 73 | /** |
| 74 | * A `fetch` dispatcher that connects to `addresses` instead of resolving the |
| 75 | * hostname again. |
| 76 | * |
| 77 | * The SSRF guard resolves a hostname to decide whether a URL is safe to fetch. |
| 78 | * `fetch` would then resolve that hostname a second time when it opens the |
| 79 | * socket, and the two answers need not match: a short-TTL record can answer |
| 80 | * with a public address for the check and an internal one for the connect |
| 81 | * (DNS rebinding). Pinning the connect to the address that was validated |
| 82 | * removes the second lookup, so there is nothing left to rebind. |
| 83 | * |
| 84 | * Only the connect target is replaced. The request still carries the original |
| 85 | * hostname in `Host` and offers it as TLS SNI, so certificate verification is |
| 86 | * unchanged — connecting by IP with the IP as SNI would fail against every |
| 87 | * origin whose certificate names a hostname. |
| 88 | * |
| 89 | * The dispatcher is handed to the runtime's own `fetch`, so callers that stub |
| 90 | * `globalThis.fetch` keep working. That does tie the `undici` major to the one |
| 91 | * Node's `fetch` speaks — undici 8 dispatchers are rejected by the Node |
| 92 | * versions this package supports — which is why the dependency is pinned to |
| 93 | * `^7`, and why `pinnedDispatcher.node.test.ts` exercises a real socket on |
| 94 | * every Node version in CI rather than mocking the transport. |
| 95 | */ |
| 96 | export const createPinnedDispatcher = async (addresses: ReadonlyArray<string>): Promise<Agent> => { |
| 97 | const { Agent } = await loadUndici(); |
| 98 | |
| 99 | return new Agent({ |
| 100 | connect: { |
| 101 | lookup: (_hostname, options, callback) => { |
| 102 | // Node calls a lookup in one of two shapes and picks between them at |
| 103 | // connect time: `(err, addresses)` when it is doing Happy Eyeballs, |
| 104 | // and `(err, address, family)` otherwise — when `autoSelectFamily` is |
| 105 | // off, or a `family`/`localAddress` was requested. Answering in the |
| 106 | // wrong shape is rejected as an invalid address, which would fail |
| 107 | // every pinned fetch in such a process. |
| 108 | lookupPinnedAddresses(addresses, options, callback); |
| 109 | }, |
| 110 | }, |
| 111 | }); |
| 112 | }; |
| 113 | |
| 114 | /** |
| 115 | * Fetch through the Node-compatible HTTP client while pinning DNS resolution. |
| 116 | * |
| 117 | * Bun implements the Node HTTP client and its `lookup` hook, but its native |
| 118 | * `fetch` ignores undici's `dispatcher` option. This transport preserves the |
| 119 | * original hostname for Host and TLS SNI while making the socket use an |
| 120 | * address that the SSRF guard already validated. |
| 121 | */ |
| 122 | export const pinnedHttpFetch = async ( |
| 123 | rawUrl: string, |
| 124 | init: RequestInit, |
| 125 | addresses: ReadonlyArray<string> |
| 126 | ): Promise<Response> => { |
| 127 | const normalized = new Request(rawUrl, init); |
| 128 | const url = new URL(rawUrl); |
| 129 | const request = url.protocol === 'https:' ? httpsRequest : httpRequest; |
| 130 | const headers = new Headers(normalized.headers); |
| 131 | const bodyLength = knownBodyLength(init.body); |
| 132 | if (bodyLength !== undefined && !headers.has('content-length')) { |
| 133 | headers.set('content-length', String(bodyLength)); |
| 134 | } |
| 135 | |
| 136 | return new Promise<Response>((resolve, reject) => { |
| 137 | const outgoing = request( |
| 138 | url, |
| 139 | { |
| 140 | method: normalized.method, |
| 141 | headers: Object.fromEntries(headers.entries()), |
| 142 | signal: normalized.signal, |
| 143 | lookup: (_hostname, options, callback) => |
| 144 | lookupPinnedAddresses(addresses, options, callback), |
| 145 | }, |
| 146 | incoming => { |
| 147 | const headers = new Headers(); |
| 148 | for (let index = 0; index < incoming.rawHeaders.length; index += 2) { |
| 149 | headers.append(incoming.rawHeaders[index], incoming.rawHeaders[index + 1]); |
| 150 | } |
| 151 | |
| 152 | const status = incoming.statusCode ?? 500; |
| 153 | const body = [101, 103, 204, 205, 304].includes(status) |
| 154 | ? null |
| 155 | : (Readable.toWeb(incoming) as ReadableStream<Uint8Array>); |
| 156 | resolve( |
| 157 | new Response(body, { |
| 158 | status, |
| 159 | statusText: incoming.statusMessage, |
| 160 | headers, |
| 161 | }) |
| 162 | ); |
| 163 | } |
| 164 | ); |
| 165 | |
| 166 | outgoing.once('error', reject); |
| 167 | |
| 168 | void (async () => { |
| 169 | try { |
| 170 | if (normalized.body) { |
| 171 | const reader = normalized.body.getReader(); |
| 172 | while (true) { |
| 173 | const { done, value } = await reader.read(); |
| 174 | if (done) break; |
| 175 | if (!outgoing.write(value)) { |
| 176 | await new Promise<void>(resolveDrain => outgoing.once('drain', resolveDrain)); |
| 177 | } |
| 178 | } |
| 179 | } |
| 180 | outgoing.end(); |
| 181 | } catch (error) { |
| 182 | outgoing.destroy(error instanceof Error ? error : new Error(String(error))); |
| 183 | } |
| 184 | })(); |
| 185 | }); |
| 186 | }; |
| 187 | |
| 188 | /** |
| 189 | * Whether the process-wide dispatcher `fetch` falls back to (when a request |
| 190 | * carries no `dispatcher` of its own) is something other than a stock `Agent`. |
| 191 | * |
| 192 | * A `ProxyAgent`, `EnvHttpProxyAgent`, or custom dispatcher installed through |
| 193 | * `setGlobalDispatcher` is visible here, and pinning stands down for it: the |
| 194 | * connect would dial the validated origin instead of that route's next hop. |
| 195 | * |
| 196 | * Nothing installed yet is *not* custom. The dispatcher slot is empty until |
| 197 | * either the runtime's `fetch` or an undici import fills it, so an absent |
| 198 | * dispatcher means no caller has configured a route — treating it as custom |
| 199 | * would disable pinning for every process that had not yet made a request. |
| 200 | * |
| 201 | * Stock-ness is compared by constructor *name*, deliberately not with |
| 202 | * `instanceof Agent`: an `Agent` created by the runtime's internal undici is a |
| 203 | * different class from this package's `Agent`, so once the runtime's own |
| 204 | * `fetch` has initialized its default dispatcher, an `instanceof` check would |
| 205 | * report a stock setup as custom and silently disable pinning. |
| 206 | */ |
| 207 | export const hasCustomGlobalDispatcher = (): boolean => { |
| 208 | const slots = globalThis as unknown as Record<symbol, { constructor?: { name?: string } }>; |
| 209 | const dispatcher = GLOBAL_DISPATCHER_SYMBOLS.map(symbol => slots[symbol]).find( |
| 210 | installed => installed !== undefined |
| 211 | ); |
| 212 | |
| 213 | return dispatcher !== undefined && dispatcher.constructor?.name !== 'Agent'; |
| 214 | }; |