OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
import dns from 'node:dns/promises';
import net from 'node:net';
import ipaddr from 'ipaddr.js';
// The bare `undici` specifier resolves to Bun's built-in shim, whose `Agent`
// is an empty class (no `close()`, and the `dispatcher` option is not honoured).
// The subpath bypasses the shim and loads the npm package, which is the one
// whose connection pinning this guard relies on.
import { Agent, fetch as undiciFetch } from 'undici/index.js';
/**
* SSRF guard for the endpoints that fetch user-supplied URLs (the favicon/OG
* proxy and the public site checker).
*
* Two things have to be true for the guard to hold:
*
* 1. Every address a hostname resolves to must be publicly routable. Checking
* only the first A record lets an attacker publish a second AAAA record.
* 2. The socket must connect to the address we validated. Resolving and then
* handing the hostname to `fetch` re-resolves it, so a DNS rebind between
* the two lookups reaches the internal target anyway. We pin the validated
* address into the connection instead.
*
* Redirects are followed manually so every hop goes through the same checks.
*/
export class BlockedUrlError extends Error {
constructor(message: string) {
super(message);
this.name = 'BlockedUrlError';
}
}
/**
* ipaddr.js range names that are not publicly routable. `unicast` is the only
* range we accept; this list is spelled out so the intent is reviewable.
*/
const BLOCKED_RANGES = new Set([
'unspecified', // 0.0.0.0/8, ::
'broadcast', // 255.255.255.255
'multicast', // 224.0.0.0/4, ff00::/8
'linkLocal', // 169.254.0.0/16 (cloud metadata), fe80::/10
'loopback', // 127.0.0.0/8, ::1
'private', // 10/8, 172.16/12, 192.168/16
'uniqueLocal', // fc00::/7
'carrierGradeNat', // 100.64.0.0/10
'reserved', // 192.0.0.0/24, 198.18/15, 240/4, 2001::/32, ...
'benchmarking',
'as112',
'amt',
'rfc6052', // 64:ff9b::/96
'rfc6145',
'teredo',
'6to4', // 2002::/16
]);
export function isBlockedIp(ip: string): boolean {
let parsed: ipaddr.IPv4 | ipaddr.IPv6;
try {
parsed = ipaddr.parse(ip);
} catch {
// Unparseable means we cannot prove it is safe.
return true;
}
// ::ffff:127.0.0.1 and friends must be judged as the IPv4 address they carry.
if (parsed.kind() === 'ipv6') {
const v6 = parsed as ipaddr.IPv6;
if (v6.isIPv4MappedAddress()) {
return isBlockedIp(v6.toIPv4Address().toString());
}
}
return BLOCKED_RANGES.has(parsed.range());
}
/**
* Resolve a hostname, rejecting it entirely if any address is non-public.
*/
async function resolvePublicAddresses(hostname: string): Promise<string[]> {
// WHATWG URL keeps the brackets around IPv6 literals ("[::1]").
const host =
hostname.startsWith('[') && hostname.endsWith(']')
? hostname.slice(1, -1)
: hostname;
// A bare IP in the URL never hits DNS, so check it directly.
if (net.isIP(host)) {
if (isBlockedIp(host)) {
throw new BlockedUrlError(`Refusing to connect to ${host}`);
}
return [host];
}
let addresses: { address: string }[];
try {
// `lookup` rather than `resolve4`/`resolve6` so /etc/hosts and the system
// resolver are honoured the same way the real connection would.
addresses = await dns.lookup(host, { all: true, verbatim: true });
} catch {
throw new BlockedUrlError(`Could not resolve ${host}`);
}
if (addresses.length === 0) {
throw new BlockedUrlError(`Could not resolve ${host}`);
}
for (const { address } of addresses) {
if (isBlockedIp(address)) {
throw new BlockedUrlError(
`Refusing to connect to ${host} (resolves to a non-public address)`
);
}
}
return addresses.map((entry) => entry.address);
}
/**
* Validate a URL's scheme and destination without fetching it. Use this to
* guard non-fetch outbound connections (raw TCP, TLS handshakes).
* Throws {@link BlockedUrlError} when the URL must not be requested.
*/
export async function assertPublicUrl(url: URL): Promise<string[]> {
if (url.protocol !== 'http:' && url.protocol !== 'https:') {
throw new BlockedUrlError('Only http/https URLs are allowed');
}
return resolvePublicAddresses(url.hostname);
}
/** Validate a bare hostname (no URL available), e.g. before a TLS probe. */
export async function assertPublicHostname(
hostname: string
): Promise<string[]> {
return resolvePublicAddresses(hostname);
}
/**
* A `lookup` that resolves every hostname to the validated `addresses`, so a
* socket cannot end up anywhere other than an address we just checked. Shared
* by the undici dispatcher below and by clients whose transport we don't own
* (the AWS SDK), which otherwise re-resolve the hostname themselves and can be
* steered elsewhere by a DNS answer that changes after the check (rebinding).
*
* The whole validated list is handed over rather than only the first entry:
* dual-stack hosts often list IPv6 first, and pinning to that alone fails on
* machines without an IPv6 route. Happy-eyeballs picks a reachable one.
*
* Signature-compatible with both `net.LookupFunction` and undici's connect
* `lookup`; the two type it slightly differently, so call sites cast.
*/
export function createPinnedLookup(addresses: string | string[]) {
const list = Array.isArray(addresses) ? addresses : [addresses];
const [first] = list;
if (!first) {
throw new BlockedUrlError('No validated address to pin');
}
const entries = list.map((address) => ({
address,
family: net.isIPv6(address) ? 6 : 4,
}));
const firstFamily = entries[0]!.family;
return (
_hostname: string,
options: { all?: boolean },
callback: (
err: null,
addressOrList: string | { address: string; family: number }[],
family?: number
) => void
) => {
if (options.all) {
callback(null, entries);
return;
}
callback(null, first, firstFamily);
};
}
/**
* A dispatcher that only ever connects to one of `addresses`, so the socket
* cannot end up somewhere other than an address we just validated.
*/
export function createPinnedAgent(addresses: string | string[]): Agent {
return new Agent({
connect: {
// undici types this as net.LookupFunction; the shared implementation is
// signature-compatible but typed loosely so node's Agent can use it too.
lookup: createPinnedLookup(addresses) as unknown as net.LookupFunction,
},
});
}
export interface SafeFetchOptions {
headers?: Record<string, string>;
method?: string;
/** Request body, for the POST callers (webhook delivery). */
body?: string;
/** Abort the whole chain after this many milliseconds. */
timeoutMs?: number;
maxRedirects?: number;
/**
* When false, a 3xx is returned as-is instead of being followed. Callers
* that walk the chain themselves still get per-hop validation and pinning.
*/
followRedirects?: boolean;
/** Reject responses whose body exceeds this many bytes. */
maxBytes?: number;
/** Caller-owned cancellation, combined with the timeout above. */
signal?: AbortSignal;
}
export interface SafeFetchResult {
status: number;
headers: Headers;
body: Buffer;
finalUrl: string;
/** Every URL that was requested, in order, with the status it returned. */
chain: { url: string; status: number }[];
}
const DEFAULT_MAX_REDIRECTS = 5;
const DEFAULT_TIMEOUT_MS = 10_000;
const DEFAULT_MAX_BYTES = 5_000_000;
const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
async function readBodyWithLimit(
body: ReadableStream<Uint8Array> | null,
maxBytes: number
): Promise<Buffer> {
if (!body) {
return Buffer.alloc(0);
}
const chunks: Uint8Array[] = [];
let total = 0;
const reader = body.getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) {
break;
}
if (!value) {
continue;
}
total += value.byteLength;
if (total > maxBytes) {
throw new BlockedUrlError('Response exceeded the size limit');
}
chunks.push(value);
}
} finally {
reader.releaseLock();
await body.cancel().catch(() => {
// best effort
});
}
return Buffer.concat(chunks);
}
export interface SafeFetchStreamResult {
status: number;
headers: Headers;
/** The live response body. Consume it, then call {@link close}. */
body: ReadableStream<Uint8Array> | null;
finalUrl: string;
chain: { url: string; status: number }[];
/** Release the pinned connection. Safe to call more than once. */
close: () => Promise<void>;
}
function combineSignals(
timeoutSignal: AbortSignal,
callerSignal?: AbortSignal
): AbortSignal {
return callerSignal
? AbortSignal.any([timeoutSignal, callerSignal])
: timeoutSignal;
}
/**
* Walk the redirect chain, resolving/validating/pinning every hop.
*
* Returns the final response together with the agent that owns its connection.
* The caller must close that agent once it is done with the body - which is
* what lets the streaming variant hand the body out without buffering it.
*/
async function walkToFinalResponse(
input: string | URL,
options: SafeFetchOptions,
signal: AbortSignal
): Promise<{
response: Awaited<ReturnType<typeof undiciFetch>>;
agent: Agent;
finalUrl: string;
chain: { url: string; status: number }[];
}> {
const followRedirects = options.followRedirects ?? true;
const maxRedirects = followRedirects
? (options.maxRedirects ?? DEFAULT_MAX_REDIRECTS)
: 0;
const chain: { url: string; status: number }[] = [];
let current = input instanceof URL ? input : new URL(input);
for (let hop = 0; ; hop++) {
const addresses = await assertPublicUrl(current);
const agent = createPinnedAgent(addresses);
let response: Awaited<ReturnType<typeof undiciFetch>>;
try {
response = await undiciFetch(current, {
method: options.method ?? 'GET',
headers: options.headers,
body: options.body,
signal,
// Handled below so every hop is re-validated.
redirect: 'manual',
dispatcher: agent,
});
} catch (error) {
await agent.close().catch(() => {
// best effort
});
throw error;
}
const status = response.status;
const location = response.headers.get('location');
chain.push({ url: current.toString(), status });
if (!(followRedirects && REDIRECT_STATUS.has(status) && location)) {
return { response, agent, finalUrl: current.toString(), chain };
}
// A redirect hop is discarded entirely; the next one is validated afresh.
await response.body?.cancel().catch(() => {
// best effort
});
await agent.close().catch(() => {
// best effort
});
if (hop >= maxRedirects) {
throw new BlockedUrlError('Too many redirects');
}
try {
current = new URL(location, current);
} catch {
throw new BlockedUrlError('Invalid redirect location');
}
}
}
/**
* `fetch` with SSRF protection: every hop is resolved, checked and pinned to
* the validated address, and the body is read under a size cap.
* Throws {@link BlockedUrlError} if any hop points somewhere non-public.
*/
export async function safeFetch(
input: string | URL,
options: SafeFetchOptions = {}
): Promise<SafeFetchResult> {
const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
const controller = new AbortController();
const timeout = setTimeout(
() => controller.abort(),
options.timeoutMs ?? DEFAULT_TIMEOUT_MS
);
try {
const { response, agent, finalUrl, chain } = await walkToFinalResponse(
input,
options,
combineSignals(controller.signal, options.signal)
);
try {
const body = await readBodyWithLimit(
response.body as ReadableStream<Uint8Array> | null,
maxBytes
);
return {
status: response.status,
headers: response.headers as unknown as Headers,
body,
finalUrl,
chain,
};
} finally {
await agent.close().catch(() => {
// best effort
});
}
} finally {
clearTimeout(timeout);
}
}
/**
* Same guarantees as {@link safeFetch}, but hands back the live body instead of
* buffering it. For callers that stream large responses through a parser and
* cannot hold them in memory (the importer's remote CSV reader).
*
* `timeoutMs` bounds the connection and redirect walk only - once the caller
* owns the stream, a long download is legitimate, so cancellation after that
* point is the caller's job via `options.signal`.
*/
export async function safeFetchStream(
input: string | URL,
options: SafeFetchOptions = {}
): Promise<SafeFetchStreamResult> {
const controller = new AbortController();
const timeout = setTimeout(
() => controller.abort(),
options.timeoutMs ?? DEFAULT_TIMEOUT_MS
);
try {
const { response, agent, finalUrl, chain } = await walkToFinalResponse(
input,
options,
combineSignals(controller.signal, options.signal)
);
let closed = false;
return {
status: response.status,
headers: response.headers as unknown as Headers,
body: response.body as ReadableStream<Uint8Array> | null,
finalUrl,
chain,
close: async () => {
if (closed) {
return;
}
closed = true;
await response.body?.cancel().catch(() => {
// best effort
});
await agent.close().catch(() => {
// best effort
});
},
};
} finally {
clearTimeout(timeout);
}
}