The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
/**
* SSRF-safe outbound fetch.
*
* Wraps `fetch` with three protections against attacker-controlled URLs:
* 1. Scheme allowlist: only `http:` and `https:` are permitted.
* 2. Host check: the hostname is resolved (IPv4 + IPv6 via Google DoH) and
* every returned address is checked against a deny-list of private,
* loopback, link-local, cloud-metadata, multicast, and reserved ranges.
* 3. Manual redirect handling: each hop's `Location` is re-validated, so a
* whitelisted host cannot bounce us into an internal IP.
*
* `safeFetch` uses DoH because the Edge runtime has no `node:dns`. The DoH
* check and the connect use separate lookups, so a DNS server that answers
* differently each time can still pass it. On the Node runtime, use
* `safeFetchNode` from `safe-fetch-node.ts`, which checks the IPs at connect time.
*/
import { DubApiError } from "@/lib/api/errors";
import { IPV4_REGEX, isPrivateIp } from "@/lib/api/is-private-ip";
const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
const DEFAULT_TIMEOUT_MS = 5000;
const DEFAULT_MAX_REDIRECTS = 5;
/** Returns the IP literal if `hostname` is one, else null. */
function ipLiteralFromHostname(hostname: string): string | null {
if (IPV4_REGEX.test(hostname)) return hostname;
if (hostname.startsWith("[") && hostname.endsWith("]")) {
return hostname.slice(1, -1);
}
return null;
}
// DoH response codes. Any other status (SERVFAIL, REFUSED, ...) is a failed lookup.
const DNS_NOERROR = 0;
const DNS_NXDOMAIN = 3;
type DohResult = { ips: string[] } | { error: string };
/**
* Resolves A and AAAA records. Returns an error if either lookup fails, so the
* caller can fail closed instead of checking only one address family.
*/
async function resolveHostnameToIps(
hostname: string,
signal: AbortSignal,
): Promise<DohResult> {
const query = async (type: "A" | "AAAA"): Promise<DohResult> => {
try {
const res = await fetch(
`https://dns.google/resolve?name=${encodeURIComponent(hostname)}&type=${type}`,
{ signal },
);
if (!res.ok) {
return { error: `${type} lookup returned HTTP ${res.status}` };
}
const data = (await res.json()) as {
Status?: number;
Answer?: { data: string; type: number }[];
};
if (data.Status !== DNS_NOERROR && data.Status !== DNS_NXDOMAIN) {
return { error: `${type} lookup returned DNS status ${data.Status}` };
}
// Type 1 = A, type 28 = AAAA. Ignore CNAME / other intermediate records.
const wantedType = type === "A" ? 1 : 28;
return {
ips: (data.Answer ?? [])
.filter((a) => a.type === wantedType)
.map((a) => a.data),
};
} catch (error) {
const reason = error instanceof Error ? error.message : String(error);
return { error: `${type} lookup failed: ${reason}` };
}
};
// Retry a failed lookup once, so a short DoH error does not reject a valid host.
const queryWithRetry = async (type: "A" | "AAAA") => {
const result = await query(type);
return "error" in result && !signal.aborted ? query(type) : result;
};
const [a, aaaa] = await Promise.all([
queryWithRetry("A"),
queryWithRetry("AAAA"),
]);
if ("error" in a) return a;
if ("error" in aaaa) return aaaa;
return { ips: [...a.ips, ...aaaa.ips] };
}
async function assertUrlIsSafe(
url: URL,
signal: AbortSignal,
resolveHostnames: boolean,
): Promise<void> {
if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
throw new DubApiError({
code: "unprocessable_entity",
message: `URL protocol "${url.protocol}" is not allowed.`,
});
}
const literal = ipLiteralFromHostname(url.hostname);
if (literal !== null) {
if (isPrivateIp(literal)) {
throw new DubApiError({
code: "unprocessable_entity",
message: "URL resolves to a disallowed IP address.",
});
}
return;
}
// The transport checks the resolved IPs itself when it connects.
if (!resolveHostnames) return;
const result = await resolveHostnameToIps(url.hostname, signal);
if (signal.aborted) {
throw new Error("Request timed out");
}
// Keep the same message prefix for both cases, and add the reason when the DoH lookup failed.
if ("error" in result) {
throw new DubApiError({
code: "unprocessable_entity",
message: `Could not resolve hostname: ${url.hostname} (${result.error})`,
});
}
const { ips } = result;
if (ips.length === 0) {
throw new DubApiError({
code: "unprocessable_entity",
message: `Could not resolve hostname: ${url.hostname}`,
});
}
if (ips.some((ip) => isPrivateIp(ip))) {
throw new DubApiError({
code: "unprocessable_entity",
message: "URL resolves to a disallowed IP address.",
});
}
}
type SafeFetchOptions = {
/** Total timeout across all redirect hops. Defaults to 5000ms. */
timeoutMs?: number;
/**
* Max number of redirects to follow. Defaults to 5. Set to 0 to return a
* redirect response as is, like `redirect: "manual"`.
*/
maxRedirects?: number;
};
type SafeFetchTransport = {
fetch: (url: string, init: RequestInit) => Promise<Response>;
/**
* False when `fetch` checks every resolved IP at connect time, so the DoH
* check is not needed. IP literals are always checked here, because no DNS
* lookup runs for them.
*/
resolveHostnames: boolean;
};
export type SafeFetch = (
url: string,
init?: RequestInit,
opts?: SafeFetchOptions,
) => Promise<Response>;
/** Builds a `safeFetch` on top of another transport. Used by `safeFetchNode`. */
export function createSafeFetch(transport: SafeFetchTransport): SafeFetch {
return (url, init, opts) => safeFetchWith(transport, url, init, opts);
}
export const safeFetch = createSafeFetch({
fetch: (url, init) => fetch(url, init),
resolveHostnames: true,
});
async function safeFetchWith(
transport: SafeFetchTransport,
url: string,
init?: RequestInit,
opts: SafeFetchOptions = {},
): Promise<Response> {
const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
let currentUrl: URL;
try {
currentUrl = new URL(url);
} catch {
throw new DubApiError({
code: "unprocessable_entity",
message: `Invalid URL: ${url}`,
});
}
// One deadline covers the DNS checks and the requests of every hop.
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
return await fetchWithRedirects(
transport,
currentUrl,
init,
maxRedirects,
controller.signal,
);
} finally {
clearTimeout(timer);
}
}
async function fetchWithRedirects(
transport: SafeFetchTransport,
url: URL,
init: RequestInit | undefined,
maxRedirects: number,
signal: AbortSignal,
): Promise<Response> {
let currentUrl = url;
let currentInit: RequestInit = { ...init };
let hops = 0;
while (true) {
await assertUrlIsSafe(currentUrl, signal, transport.resolveHostnames);
const response = await transport.fetch(currentUrl.toString(), {
...currentInit,
redirect: "manual",
signal,
});
const isRedirect = response.status >= 300 && response.status < 400;
const location = response.headers.get("location");
if (!isRedirect || !location || maxRedirects === 0) {
return response;
}
// We do not read the redirect body, so release its connection.
await response.body?.cancel().catch(() => {});
if (hops >= maxRedirects) {
throw new Error("Too many redirects");
}
let nextUrl: URL;
try {
nextUrl = new URL(location, currentUrl);
} catch {
throw new DubApiError({
code: "unprocessable_entity",
message: `Invalid redirect location: ${location}`,
});
}
currentInit = initForRedirect(
currentInit,
response.status,
currentUrl,
nextUrl,
);
currentUrl = nextUrl;
hops += 1;
}
}
const REQUEST_BODY_HEADERS = [
"content-encoding",
"content-language",
"content-location",
"content-type",
];
const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
/**
* Builds the request for the next redirect hop with the rules that `fetch`
* uses when it follows redirects: 303 (and 301/302 after a POST) switch to a
* GET without a body, and credentials are not sent to another origin.
*/
function initForRedirect(
init: RequestInit,
status: number,
from: URL,
to: URL,
): RequestInit {
const method = (init.method ?? "GET").toUpperCase();
const switchToGet =
(status === 303 && method !== "GET" && method !== "HEAD") ||
((status === 301 || status === 302) && method === "POST");
const crossOrigin = from.origin !== to.origin;
if (!switchToGet && !crossOrigin) return init;
const headers = new Headers(init.headers);
if (switchToGet) {
REQUEST_BODY_HEADERS.forEach((name) => headers.delete(name));
}
if (crossOrigin) {
CREDENTIAL_HEADERS.forEach((name) => headers.delete(name));
}
return {
...init,
headers,
...(switchToGet && { method: "GET", body: undefined }),
};
}