Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

13.3 KB
Raw Blame
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);
  }
}