Files
TREK/server/src/utils/ssrfGuard.ts
T
Maurice 402a02a302 fix(docker): say what the volume-root check leaves alone, and skip the walk for a custom fsGroup
The entrypoint comment, the Helm chart README, the wiki and the ssrfGuard
note now describe what the shipped check does.
2026-11-05 14:36:22 +01:00

809 lines
35 KiB
TypeScript

import { readEnv } from '../app-config';
import { embeddedTransitionIpv4, expandIpv6 } from './ipv6';
import dns from 'node:dns/promises';
import { Agent, ProxyAgent, type Dispatcher } from 'undici';
// Frozen at import on purpose (legacy timing; tests reload the module to change it).
const ALLOW_INTERNAL_NETWORK = readEnv().net.allowInternalNetwork;
// Link-local addresses an admin listed in ALLOW_LINK_LOCAL_IPS, a rootless Podman
// host gateway being the reason (#2400). The parser never lets a cloud metadata
// address in, so the rest of 169.254.0.0/16 stays blocked. Frozen the same way.
const ALLOWED_LINK_LOCAL = new Set(readEnv().net.allowLinkLocalIps);
// HTTP_PROXY / HTTPS_PROXY / NO_PROXY (#1754). Frozen like the two above.
const PROXY = readEnv().net.proxy;
export interface SsrfResult {
allowed: boolean;
/** The first of `resolvedIps`, kept for the callers that name one address. */
resolvedIp?: string;
/**
* The addresses a connection to the name may use, IPv4 first: every address
* it resolves to, less the ones the guard never connects to. On a refusal,
* every address it resolved to.
*/
resolvedIps?: string[];
isPrivate: boolean;
error?: string;
}
/**
* Every address a name resolves to, IPv4 ahead of IPv6.
*
* One address was never enough. `dns.lookup(name)` hands back whichever record
* the resolver lists first, on Node 22 in the resolver's own order, and a
* dual-stack name whose AAAA comes first then pinned the connection to an IPv6
* that many hosts cannot reach on port 443 while the A record would have
* answered at once. Every address the guard allows goes to the socket, where
* Node tries the addresses in turn (autoSelectFamily, the default since Node
* 20), so an unreachable family costs at most one connect attempt per address
* (CONNECT_ATTEMPT_TIMEOUT_MS, 2 s, raised at startup in utils/connectAttempt.ts)
* instead of the caller's whole timeout. IPv4 leads because that is the family
* that is reachable from the containers and LXCs TREK usually runs in.
*/
async function resolveAll(hostname: string): Promise<{ address: string; family: number }[]> {
const result = await dns.lookup(hostname, { all: true });
// The promise API answers an array for `all: true`; a resolver stub in a test
// may still answer one record, which is the same thing said shorter.
const list = (Array.isArray(result) ? result : [result]).filter((entry) => typeof entry?.address === 'string');
if (list.length === 0) {
const error = new Error(`getaddrinfo ENOTFOUND ${hostname}`) as NodeJS.ErrnoException;
error.code = 'ENOTFOUND';
throw error;
}
const family = (entry: { address: string; family: number }) => entry.family || (entry.address.includes(':') ? 6 : 4);
return [...list.filter((entry) => family(entry) === 4), ...list.filter((entry) => family(entry) !== 4)].map(
(entry) => ({ address: entry.address, family: family(entry) }),
);
}
/**
* The IPv4 an IPv4-mapped (`::ffff:a.b.c.d`) or IPv4-compatible (`::a.b.c.d`)
* address stands for, or null.
*
* Taken from the hextets rather than from the text, because `::ffff:127.0.0.1`
* and `::ffff:7f00:1` are one address in two spellings and `dns.lookup` picks
* which one comes back. The prefix regexes this replaces covered the dotted
* spelling of two ranges; every other mapped address walked past them. The
* compatible form is deprecated but still parsed, and Node prints an AAAA
* record of `::a9fe:a9fe` as `::169.254.169.254`. `::` and `::1` are left to
* the IPv6 checks, being the unspecified and loopback addresses themselves.
*/
function carriedIpv4(hextets: number[]): string | null {
const g = hextets;
if (g[0] || g[1] || g[2] || g[3] || g[4]) return null;
const mapped = g[5] === 0xffff;
const compatible = g[5] === 0 && (g[6] !== 0 || g[7] > 1);
if (!mapped && !compatible) return null;
return `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
}
// Blocked whatever ALLOW_INTERNAL_NETWORK says. The only way past is naming a single
// link-local address in ALLOW_LINK_LOCAL_IPS; loopback and metadata have none.
function isAlwaysBlocked(ip: string): boolean {
// Strip IPv6 brackets
const addr = ip.startsWith('[') ? ip.slice(1, -1) : ip;
// Loopback
if (addr.startsWith('127.') || addr === '::1') return true;
// Unspecified
if (addr.startsWith('0.')) return true;
// Link-local and cloud metadata: everything the admin lane refuses, apart from
// an address listed in ALLOW_LINK_LOCAL_IPS, which isPrivateNetwork then treats
// as the internal network it is. The AWS IMDSv6 and Alibaba addresses sit in
// ULA and CGNAT space, so without this ALLOW_INTERNAL_NETWORK would open them
// to a URL any user can type.
if (isLinkLocal(addr)) return true;
const hextets = expandIpv6(addr);
if (hextets) {
// The IPv6 unspecified address. Connecting to it lands on loopback, so it
// reaches a local service without naming one, and it has enough spellings
// (`::`, `::0`, `0:0:0:0:0:0:0:0`) that only the expanded hextets settle it.
// The `0.` check above never saw any of them: they begin with a colon.
if (hextets.every((h) => h === 0)) return true;
// Loopback in any spelling, not only the `::1` a resolver prints.
if (hextets.slice(0, 7).every((h) => h === 0) && hextets[7] === 1) return true;
// fe80::/10 spans fe80: through febf:, not just the four characters 'fe80'.
if ((hextets[0] & 0xffc0) === 0xfe80) return true;
// A mapped or compatible address inherits the verdict of the IPv4 it carries.
const carried = carriedIpv4(hextets);
if (carried) return isAlwaysBlocked(carried);
}
// IPv6 transition addresses (NAT64/6to4/Teredo) embedding a hard-blocked IPv4.
const embedded = embeddedTransitionIpv4(addr);
if (embedded) return isAlwaysBlocked(embedded);
return false;
}
// Blocked unless ALLOW_INTERNAL_NETWORK=true
function isPrivateNetwork(ip: string): boolean {
const addr = ip.startsWith('[') ? ip.slice(1, -1) : ip;
// A listed link-local address is a host on this machine's own network, so it
// needs ALLOW_INTERNAL_NETWORK here like any other.
if (ALLOWED_LINK_LOCAL.has(addr)) return true;
// RFC-1918 private ranges
if (addr.startsWith('10.')) return true;
if (/^172\.(1[6-9]|2\d|3[01])\./.test(addr)) return true;
if (addr.startsWith('192.168.')) return true;
// CGNAT / Tailscale shared address space (100.64.0.0/10)
if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(addr)) return true;
// IPv6 ULA (fc00::/7)
if (/^f[cd]/i.test(addr)) return true;
// A mapped or compatible address inherits the verdict of the IPv4 it carries.
// Deciding on the hextets rather than on three `::ffff:`-prefix regexes also
// covers the hex spelling and the CGNAT range those regexes never listed.
const hextets = expandIpv6(addr);
const carried = hextets && carriedIpv4(hextets);
if (carried) return isPrivateNetwork(carried);
// IPv6 transition addresses (NAT64/6to4/Teredo) embedding a private IPv4.
const embedded = embeddedTransitionIpv4(addr);
if (embedded) return isPrivateNetwork(embedded);
return false;
}
function isInternalHostname(hostname: string): boolean {
const h = hostname.toLowerCase();
return h.endsWith('.local') || h.endsWith('.internal') || h === 'localhost';
}
export async function checkSsrf(rawUrl: string, bypassInternalIpAllowed: boolean = false): Promise<SsrfResult> {
let url: URL;
try {
url = new URL(rawUrl);
} catch {
return { allowed: false, isPrivate: false, error: 'Invalid URL' };
}
if (!['http:', 'https:'].includes(url.protocol)) {
return { allowed: false, isPrivate: false, error: 'Only HTTP and HTTPS URLs are allowed' };
}
const hostname = url.hostname.toLowerCase();
// Resolve the name to every address it has and judge each one on its own.
let resolvedIps: string[];
try {
resolvedIps = (await resolveAll(hostname)).map((entry) => entry.address);
} catch (error_) {
const code = error_ instanceof Error && 'code' in error_ ? String(error_.code) : 'unknown';
return { allowed: false, isPrivate: false, error: `Could not resolve hostname (${code})` };
}
// An address the guard never connects to is left out of the list the socket
// gets, rather than refusing the name. A LAN DNS server commonly hands out a
// host's fe80:: address next to its IPv4, and refusing the name for it locked
// out every such host (#2506). Only a name with nothing else left is refused.
const usableIps = resolvedIps.filter((ip) => !isAlwaysBlocked(ip));
if (usableIps.length === 0) {
return {
allowed: false,
isPrivate: true,
resolvedIp: resolvedIps[0],
resolvedIps,
error: 'Requests to loopback and link-local addresses are not allowed',
};
}
const resolvedIp = usableIps[0];
// A private address among the rest decides for the whole name: the socket
// may end up on any address it is handed, so a list that mixes a public and a
// private address is a private target with a public alibi.
const privateIp = usableIps.find((ip) => isPrivateNetwork(ip));
if (privateIp || isInternalHostname(hostname)) {
if (!ALLOW_INTERNAL_NETWORK || bypassInternalIpAllowed) {
return {
allowed: false,
isPrivate: true,
resolvedIp: privateIp ?? resolvedIp,
resolvedIps,
error:
'Requests to private/internal network addresses are not allowed. Set ALLOW_INTERNAL_NETWORK=true to permit this for self-hosted setups.',
};
}
return { allowed: true, isPrivate: true, resolvedIp: privateIp ?? resolvedIp, resolvedIps: usableIps };
}
return { allowed: true, isPrivate: false, resolvedIp, resolvedIps: usableIps };
}
/** Link-local / cloud-metadata addresses — never a legitimate model host. */
function isLinkLocal(ip: string): boolean {
const addr = (ip.startsWith('[') ? ip.slice(1, -1) : ip).toLowerCase();
// IPv4 link-local — AWS, GCP, Azure and OpenStack all serve credentials from 169.254.169.254.
// An address listed in ALLOW_LINK_LOCAL_IPS is the exception; those never include it.
if (addr.startsWith('169.254.')) return !ALLOWED_LINK_LOCAL.has(addr);
// IPv6 link-local fe80::/10 — the whole range (fe80: … febf:), not just the fe80: prefix.
if (/^fe[89ab][0-9a-f]:/.test(addr)) return true;
// AWS IMDSv6 sits in a fixed ULA slot (fd00:ec2::/32); block it specifically while
// leaving the rest of fc00::/7 reachable (a self-hosted model server may
// legitimately sit on a ULA address). Read off the hextets, so every spelling counts.
const hextets = expandIpv6(addr);
if (hextets && hextets[0] === 0xfd00 && hextets[1] === 0x0ec2) return true;
// Alibaba Cloud ECS metadata (100.100.100.200, and .100) lives in CGNAT space
// (100.64.0.0/10), which safeFetchLlm otherwise allows for a LAN model server —
// so block the specific metadata IPs directly rather than the whole range.
if (addr === '100.100.100.200' || addr === '100.100.100.100') return true;
// An IPv4-mapped or IPv4-compatible address, dotted or hex, is the IPv4 it
// carries. So 169.254.169.254 cannot come back as ::ffff:a9fe:a9fe, or as the
// ::169.254.169.254 Node prints for a compatible AAAA record, and an address
// listed in ALLOW_LINK_LOCAL_IPS keeps its exception in every spelling.
const carried = hextets && carriedIpv4(hextets);
if (carried) return isLinkLocal(carried);
// NAT64/6to4/Teredo embedding one of the above link-local/metadata IPs — extract
// the embedded IPv4 and re-check. A transition address to a public or LAN IPv4
// stays allowed (safeFetchLlm deliberately permits private/loopback targets).
const embedded = embeddedTransitionIpv4(addr);
if (embedded) return isLinkLocal(embedded);
return false;
}
/**
* SSRF-safe fetch for a user-configurable LLM endpoint. Unlike safeFetch() this
* deliberately ALLOWS loopback and private/LAN targets — a local Ollama on
* localhost or a model server on the LAN is the normal, supported config, so
* blocking them would break a legitimate setup. It blocks only the link-local /
* cloud-metadata range (169.254.0.0/16, fe80::/10, the AWS/Alibaba metadata IPs),
* which is never a real LLM host but is the credential-theft SSRF target.
*
* Redirects are followed MANUALLY and re-validated on every hop. Checking only the
* initial URL is not enough: a validated public endpoint can 302 to
* `http://169.254.169.254/…`, and the DNS pin does NOT cover that hop — Node's
* net.connect skips the pinned `lookup` for an IP-literal host, so a redirect to a
* literal metadata IP would connect straight through. Following manually (like
* safeFetchFollow) means each hop is re-resolved, re-checked against isLinkLocal,
* and re-pinned. An http→https upgrade or a proxy redirect between LAN hosts still
* works because the check re-runs per hop rather than locking to the first IP.
*
* `responseTimeoutMs` raises undici's own five-minute ceiling for callers that
* legitimately wait longer (see safeFetchLlm). Left unset, the caller's own
* signal governs, and a call without one waits DEFAULT_RESPONSE_TIMEOUT_MS for
* the response headers. `maxBytes` caps the body as in SafeFetchOptions.
*
* `reuseConnections` keeps the dispatcher for the next call to the same vetted
* addresses (see keptDispatcher), so a caller that asks one host many times in
* a row, the routing relay, does not pay DNS, TCP and TLS on every question.
*/
export async function safeFetchAdminConfigured(
url: string,
init?: RequestInit,
maxRedirects = 5,
responseTimeoutMs?: number,
maxBytes: number | null = DEFAULT_MAX_RESPONSE_BYTES,
reuseConnections = false,
): Promise<Response> {
let currentUrl = url;
let hopInit = init;
const headersTimeoutMs = responseTimeoutMs || init?.signal ? undefined : DEFAULT_RESPONSE_TIMEOUT_MS;
for (let hop = 0; ; hop++) {
let parsed: URL;
try {
parsed = new URL(currentUrl);
} catch {
throw new SsrfBlockedError('Invalid URL');
}
if (!['http:', 'https:'].includes(parsed.protocol)) {
throw new SsrfBlockedError('Only HTTP and HTTPS URLs are allowed');
}
let resolvedIps: string[];
try {
resolvedIps = (await resolveAll(parsed.hostname)).map((entry) => entry.address);
} catch (error_) {
const code = error_ instanceof Error && 'code' in error_ ? String(error_.code) : 'unknown';
throw new SsrfBlockedError(`Could not resolve hostname (${code})`);
}
// As in checkSsrf: a link-local or metadata address is left out of the list
// the socket gets, and only a name with nothing else left is refused. An
// fe80:: record beside an IdP's LAN address refused every OIDC login (#2506).
const usableIps = resolvedIps.filter((ip) => !isLinkLocal(ip));
if (usableIps.length === 0) {
throw new SsrfBlockedError('Requests to link-local / cloud-metadata addresses are not allowed');
}
const dispatcher = createOutboundDispatcher(
currentUrl,
usableIps,
true,
responseTimeoutMs,
headersTimeoutMs,
reuseConnections,
);
const response = await fetch(currentUrl, { ...hopInit, redirect: 'manual', dispatcher } as any);
// Only a 3xx WITH a Location header is a redirect we follow; anything else
// (2xx/4xx/5xx, or a 3xx with no Location) is the final response.
const status = typeof response.status === 'number' ? response.status : 0;
const location = status >= 300 && status < 400 ? (response.headers?.get('location') ?? null) : null;
if (!location) return capResponse(response, maxBytes);
if (hop >= maxRedirects) {
throw new SsrfBlockedError('Too many redirects');
}
let nextUrl: string;
try {
nextUrl = new URL(location, currentUrl).toString();
} catch {
throw new SsrfBlockedError('Invalid redirect location');
}
// Drain the redirect body so the connection can be reused/closed, then loop
// to re-resolve + re-check + re-pin the next hop.
void response.body?.cancel().catch(() => {});
hopInit = nextHopInit(hopInit, currentUrl, nextUrl, status);
currentUrl = nextUrl;
}
}
/**
* The original name, now the model lane specifically: the same guard as
* safeFetchAdminConfigured — an endpoint an admin configured, which may
* legitimately live on loopback or the LAN, and must still never reach
* link-local or a cloud metadata service — with LLM_TIMEOUT_MS as the response
* ceiling instead of undici's five minutes, so one setting governs the whole
* call rather than being overruled by a default nobody chose.
*
* The ceiling is read once per call rather than per hop, so a redirect chain is
* measured against one value even if the variable changes mid-chain.
*/
export function safeFetchLlm(
url: string,
init?: RequestInit,
maxRedirects = 5,
maxBytes: number | null = DEFAULT_MAX_RESPONSE_BYTES,
): Promise<Response> {
return safeFetchAdminConfigured(url, init, maxRedirects, readEnv().integrations.llmTimeoutMs, maxBytes);
}
/**
* Thrown by safeFetch() when the URL is blocked by the SSRF guard.
*/
export class SsrfBlockedError extends Error {
constructor(message: string) {
super(message);
this.name = 'SsrfBlockedError';
}
}
/**
* Thrown when a guarded response is larger than its cap: up front when the
* declared Content-Length says so, otherwise by the body read that passes it.
*/
export class ResponseTooLargeError extends Error {
constructor(readonly maxBytes: number) {
super(`Response body exceeds ${maxBytes} bytes`);
this.name = 'ResponseTooLargeError';
}
}
/**
* What a guarded response may hold when the caller does not say. Sized for the
* largest JSON a user's own server sends back (an Immich album lists every
* asset it holds), and still small enough that one answer cannot take the
* process's memory with it.
*/
export const DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
/**
* How long a guarded request waits for the response headers when the caller
* passes no signal of its own. Only the headers: the body stays under undici's
* idle timeout, so a proxied video that pauses with its player is not cut off.
*/
export const DEFAULT_RESPONSE_TIMEOUT_MS = 30_000;
export interface SafeFetchOptions {
rejectUnauthorized?: boolean;
/**
* A deadline for the whole exchange, body included. Combined with the init's
* own signal when there is one. Without either, the request waits
* DEFAULT_RESPONSE_TIMEOUT_MS for the response headers.
*/
timeoutMs?: number;
/**
* The most bytes the body may hold; DEFAULT_MAX_RESPONSE_BYTES when left out.
* `null` lifts the cap, for a caller that streams the body on without holding
* it (a proxied original) or counts the bytes itself.
*/
maxBytes?: number | null;
}
/** The caller's signal, joined with the deadline from `timeoutMs` when one is asked for. */
function deadlineSignal(
signal: AbortSignal | null | undefined,
timeoutMs: number | undefined,
): AbortSignal | undefined {
if (!timeoutMs) return signal ?? undefined;
const deadline = AbortSignal.timeout(timeoutMs);
return signal ? AbortSignal.any([signal, deadline]) : deadline;
}
/**
* The response with its body held to `maxBytes`. A declared length over the cap
* is refused before anything is read; a body without one (chunked, compressed)
* errors as soon as the bytes passing through cross it, so `json()`,
* `arrayBuffer()` or a pipe reject instead of buffering the rest. Anything that
* is not a platform Response with a stream (a test stub) is returned as it is.
*/
export function capResponse(response: Response, maxBytes: number | null): Response {
if (maxBytes === null) return response;
const declared = Number(response.headers?.get?.('content-length') ?? 0);
if (declared > maxBytes) {
void response.body?.cancel().catch(() => {});
throw new ResponseTooLargeError(maxBytes);
}
const body = response.body;
if (!(response instanceof Response) || !body || typeof body.pipeThrough !== 'function') return response;
let received = 0;
const counted = body.pipeThrough(
new TransformStream<Uint8Array, Uint8Array>({
transform(chunk, controller) {
received += chunk.byteLength;
if (received > maxBytes) controller.error(new ResponseTooLargeError(maxBytes));
else controller.enqueue(chunk);
},
}),
);
const capped = new Response(counted, {
status: response.status,
statusText: response.statusText,
headers: response.headers,
});
// A constructed Response has an empty url; callers read the final hop from it.
Object.defineProperty(capped, 'url', { value: response.url });
Object.defineProperty(capped, 'redirected', { value: response.redirected });
return capped;
}
/**
* SSRF-safe fetch wrapper. Validates the URL with checkSsrf(), then makes
* the request using a DNS-pinned dispatcher so the resolved IP cannot change
* between the check and the actual connection (DNS rebinding prevention).
*
* Pass `{ rejectUnauthorized: false }` for targets that use self-signed TLS
* certificates (e.g. a Synology NAS on a local network). The SSRF guard still
* applies — only the TLS certificate check is relaxed.
*
* Redirects are followed through safeFetchFollow, so every hop is re-checked and
* re-pinned, with safeFetchFollow's defaults: a body cap and, for a call without
* a signal, a bounded wait for the headers. It used to hand the platform a
* `redirect: 'follow'` with a dispatcher pinned to the FIRST hop only, the same shape as
* GHSA-8mw6-xphx-886m, and pinning does not help there because Node skips the
* pinned lookup for an IP-literal host. Sixteen callers ride on this, several
* with a URL out of a per-user setting (Immich, Synology, AirTrail), and one
* (pipeAsset) streams the response back to the caller, which would have made a
* redirect to an internal service readable rather than blind.
*/
export async function safeFetch(url: string, init?: RequestInit, options?: SafeFetchOptions): Promise<Response> {
return safeFetchFollow(url, init, options);
}
/**
* Headers that must not survive a hop to another origin. Following a redirect
* by hand means the platform's own protection does not apply: undici drops
* `Authorization` across origins itself (Fetch, "HTTP-redirect fetch" step 13),
* so a manual follower that replays the caller's headers verbatim is strictly
* weaker than the fetch it replaced. The list is credentials-only on purpose —
* `User-Agent` has to survive, or the goo.gl chain in maps.service resolves to
* a different page than the one its coordinates are parsed out of.
*/
const CREDENTIAL_HEADERS = [
'authorization',
'proxy-authorization',
'cookie',
'cookie2',
'x-api-key',
'api-key',
'x-auth-token',
];
/** Headers that describe the body, and go when the body does. */
const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location'];
/**
* Cross-origin per Fetch, with one carve-out: the same hostname moving from
* http to https is an upgrade, not a host change. A self-hosted IdP or ntfy
* behind a redirecting proxy does exactly that, and a strict origin compare
* would strip the credential those setups depend on.
*/
function isCrossOriginHop(from: string, to: string): boolean {
let a: URL, b: URL;
try {
a = new URL(from);
b = new URL(to);
} catch {
return true;
}
if (a.origin === b.origin) return false;
return !(a.hostname === b.hostname && a.protocol === 'http:' && b.protocol === 'https:');
}
function stripHeaders(init: RequestInit | undefined, names: string[]): RequestInit | undefined {
if (!init?.headers) return init;
const headers = new Headers(init.headers as ConstructorParameters<typeof Headers>[0]);
for (const name of names) headers.delete(name);
return { ...init, headers };
}
/**
* The init for the next hop of a manual redirect follow. Both followers below
* go through this: following by hand opts out of the platform's own rules, so
* they have to be restated once rather than forgotten twice.
*/
function nextHopInit(
init: RequestInit | undefined,
currentUrl: string,
nextUrl: string,
status: number,
keepCredentials = false,
): RequestInit | undefined {
let next = init;
if (!keepCredentials && isCrossOriginHop(currentUrl, nextUrl)) {
next = stripHeaders(next, CREDENTIAL_HEADERS);
}
// RFC 9110 15.4.4 for 303, and 15.4.2/15.4.3 plus what every client actually
// does for 301/302 on a POST: the next hop is a GET with no body. Replaying
// the body would re-POST it — a plugin's client_secret included — at a host
// the first one merely pointed at.
const method = (next?.method ?? 'GET').toUpperCase();
if (status === 303 || ((status === 301 || status === 302) && method !== 'GET' && method !== 'HEAD')) {
next = { ...stripHeaders(next, BODY_HEADERS), method: 'GET', body: undefined };
}
return next;
}
export interface SafeFetchFollowOptions extends SafeFetchOptions {
/** Maximum number of redirects to follow before giving up. Defaults to 5. */
maxRedirects?: number;
/**
* Keep credential headers across an origin change. Off by default, and no
* caller needs it today — it exists so a future one that genuinely does has
* to say so here rather than route around the guard.
*/
keepCredentialsOnRedirect?: boolean;
/**
* When true, private/internal IPs that ALLOW_INTERNAL_NETWORK would normally
* permit are still blocked (matches `checkSsrf(url, true)`). Loopback,
* link-local and cloud metadata are always blocked regardless. Defaults to false.
*/
bypassInternalIpAllowed?: boolean;
}
/**
* SSRF-safe fetch that follows redirects MANUALLY, re-validating every hop.
*
* `safeFetch()` (and a one-shot `checkSsrf()` + `fetch(redirect:'follow')`) only
* guards the INITIAL URL: a validated public URL can 302-redirect to an internal
* IP that the platform fetch would then follow unchecked (redirect TOCTOU). This
* helper instead requests with `redirect: 'manual'`, and on every 3xx it resolves
* the `Location` header against the current URL, runs `checkSsrf()` on the new
* target, and only then fetches the next hop through a dispatcher pinned to THAT
* hop's resolved IP. Each hop is therefore SSRF-checked + DNS-pinned, while
* legitimate cross-host redirects (e.g. goo.gl → maps.google.com) still resolve
* because the dispatcher is re-pinned per hop rather than locked to the first IP.
*
* The returned Response is the first non-redirect response (or the last redirect
* if the hop limit is reached). `response.url` reflects the final hop so callers
* relying on the resolved URL keep working. Its body is capped and the wait is
* bounded as SafeFetchOptions describes.
*/
export async function safeFetchFollow(
url: string,
init?: RequestInit,
options?: SafeFetchFollowOptions,
): Promise<Response> {
const maxRedirects = options?.maxRedirects ?? 5;
const rejectUnauthorized = options?.rejectUnauthorized ?? true;
const bypassInternalIpAllowed = options?.bypassInternalIpAllowed ?? false;
const maxBytes = options?.maxBytes === undefined ? DEFAULT_MAX_RESPONSE_BYTES : options.maxBytes;
// One signal for the whole chain, so a redirect does not restart the deadline.
const signal = deadlineSignal(init?.signal, options?.timeoutMs);
const headersTimeoutMs = signal ? undefined : DEFAULT_RESPONSE_TIMEOUT_MS;
let currentUrl = url;
let hopInit = signal ? { ...init, signal } : init;
for (let hop = 0; ; hop++) {
const ssrf = await checkSsrf(currentUrl, bypassInternalIpAllowed);
if (!ssrf.allowed) {
throw new SsrfBlockedError(ssrf.error ?? 'Request blocked by SSRF guard');
}
const dispatcher = createOutboundDispatcher(
currentUrl,
ssrf.resolvedIps ?? [ssrf.resolvedIp!],
rejectUnauthorized,
undefined,
headersTimeoutMs,
);
const response = await fetch(currentUrl, {
...hopInit,
redirect: 'manual',
dispatcher,
} as any);
// Only a 3xx WITH a Location header is a redirect we follow; anything else
// (2xx/4xx/5xx, or a 3xx with no Location) is the final response.
const status = typeof response.status === 'number' ? response.status : 0;
const isRedirectStatus = status >= 300 && status < 400;
const location = isRedirectStatus ? (response.headers?.get('location') ?? null) : null;
if (!location) {
return capResponse(response, maxBytes);
}
if (hop >= maxRedirects) {
throw new SsrfBlockedError('Too many redirects');
}
// Resolve relative redirects against the current URL, then loop to
// re-check + re-pin on the next iteration. Drain the body so the
// connection can be reused/closed.
let nextUrl: string;
try {
nextUrl = new URL(location, currentUrl).toString();
} catch {
throw new SsrfBlockedError('Invalid redirect location');
}
void response.body?.cancel().catch(() => {});
hopInit = nextHopInit(hopInit, currentUrl, nextUrl, status, options?.keepCredentialsOnRedirect);
currentUrl = nextUrl;
}
}
/**
* The proxy a guarded request to this URL goes through, or null (#1754).
*
* The guarded fetches below use their own dispatcher, so they never saw the
* environment proxy Node applies to everything else, and on a server that can
* only reach the internet through a proxy every place photo, link preview and
* webhook simply failed. NO_PROXY works the way curl and Node read it: `*`
* matches every host, an entry matches the host itself and its subdomains
* (a leading dot is optional), and `host:port` narrows it to one port.
*/
export function proxyFor(rawUrl: string, proxy = PROXY): string | null {
let url: URL;
try {
url = new URL(rawUrl);
} catch {
return null;
}
const target = url.protocol === 'https:' ? (proxy.https ?? proxy.http) : proxy.http;
if (!target) return null;
const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
const port = url.port || (url.protocol === 'https:' ? '443' : '80');
const bypass = proxy.noProxy.some((entry) => {
if (entry === '*') return true;
const [name, entryPort] = entry.replace(/(?:^\[)|(?:\](?=:|$))/g, '').split(/:(?=\d+$)/);
if (entryPort && entryPort !== port) return false;
const bare = name.replace(/^\*?\./, '');
return host === bare || host.endsWith(`.${bare}`);
});
return bypass ? null : target;
}
/**
* The dispatcher one guarded hop goes out through. Without a proxy it is the
* pinned agent below. With one, the proxy makes the connection, so the address
* cannot be pinned on our side: the guard has already refused a private or
* loopback target before this point, and the proxy the operator chose is the
* network boundary from there on.
*/
export function createOutboundDispatcher(
url: string,
resolved: string | readonly string[],
rejectUnauthorized = true,
responseTimeoutMs?: number,
headersTimeoutMs?: number,
reuseConnections = false,
): Dispatcher {
const proxy = proxyFor(url);
const keepAliveMs = reuseConnections ? KEPT_ALIVE_MS : undefined;
const create = (): Dispatcher =>
proxy
? new ProxyAgent({
uri: proxy,
requestTls: { rejectUnauthorized },
...dispatcherTimeouts(responseTimeoutMs, headersTimeoutMs),
...(keepAliveMs ? { keepAliveTimeout: keepAliveMs } : {}),
})
: createPinnedDispatcher(resolved, rejectUnauthorized, responseTimeoutMs, headersTimeoutMs, keepAliveMs);
if (!reuseConnections) return create();
// Through a proxy the proxy connects, so the addresses play no part in what the dispatcher does.
const addresses = proxy ? [] : typeof resolved === 'string' ? [resolved] : [...resolved];
const key = JSON.stringify([
proxy,
addresses,
rejectUnauthorized,
responseTimeoutMs ?? null,
headersTimeoutMs ?? null,
]);
return keptDispatcher(key, create);
}
/**
* Dispatchers kept for the callers that reuse their connections, by everything
* that makes one: the proxy, the vetted addresses, the TLS check and the
* timeouts. The addresses are part of the key, so the pin is as strict as a
* new agent's: a name that now resolves elsewhere gets a dispatcher of its own
* and never a connection to the old address. At most MAX_KEPT_DISPATCHERS are
* kept; the oldest is closed, after its requests finish, when one more is needed.
*/
const keptDispatchers = new Map<string, Dispatcher>();
const MAX_KEPT_DISPATCHERS = 32;
/** How long a kept connection may sit idle, where undici's own default is four seconds. */
const KEPT_ALIVE_MS = 10_000;
function keptDispatcher(key: string, create: () => Dispatcher): Dispatcher {
const kept = keptDispatchers.get(key);
if (kept) return kept;
const dispatcher = create();
keptDispatchers.set(key, dispatcher);
const [oldestKey] = keptDispatchers.keys();
if (keptDispatchers.size > MAX_KEPT_DISPATCHERS && oldestKey !== undefined) {
const oldest = keptDispatchers.get(oldestKey);
keptDispatchers.delete(oldestKey);
void oldest?.close().catch(() => {});
}
return dispatcher;
}
/**
* undici's timeouts for one dispatcher. `responseTimeoutMs` bounds both the
* wait for the headers and each pause in the body; `headersTimeoutMs` bounds
* the headers only. Neither leaves undici its five-minute defaults.
*/
function dispatcherTimeouts(
responseTimeoutMs?: number,
headersTimeoutMs?: number,
): { headersTimeout?: number; bodyTimeout?: number } {
if (responseTimeoutMs) return { headersTimeout: responseTimeoutMs, bodyTimeout: responseTimeoutMs };
if (headersTimeoutMs) return { headersTimeout: headersTimeoutMs };
return {};
}
/**
* Returns an undici Agent whose connect.lookup is pinned to the already-validated
* addresses. This prevents DNS rebinding (TOCTOU) by ensuring the outbound
* connection goes to an address we checked, not a re-resolved one.
*
* Given the vetted list, in the order `resolveAll` put it, the socket gets
* every address on it at once and never one the guard left out: Node asks for
* `all: true` and walks the list itself, moving on after its attempt timeout
* when one family does not answer.
* A caller that still names one address gets exactly the old behaviour.
* `keepAliveMs` holds an idle connection open longer than undici's default,
* for a dispatcher that is kept (keptDispatcher).
*/
export function createPinnedDispatcher(
resolved: string | readonly string[],
rejectUnauthorized = true,
responseTimeoutMs?: number,
headersTimeoutMs?: number,
keepAliveMs?: number,
): Agent {
const addresses = (typeof resolved === 'string' ? [resolved] : [...resolved]).map((address) => ({
address,
family: address.includes(':') ? 6 : 4,
}));
return new Agent({
// undici caps the wait for response headers at 5 minutes by default, and
// that cap is invisible from the call site: an AbortController set to
// fifteen still dies at five.
...dispatcherTimeouts(responseTimeoutMs, headersTimeoutMs),
...(keepAliveMs ? { keepAliveTimeout: keepAliveMs } : {}),
connect: {
rejectUnauthorized,
lookup: (_hostname: string, opts: Record<string, unknown>, callback: Function) => {
// Node asks with `all: true` when it may choose between families itself.
if (opts?.all) {
callback(null, addresses);
} else {
callback(null, addresses[0].address, addresses[0].family);
}
},
},
});
}