Skip to content

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

6.0 KB
Raw Blame
/** Both header orders are configurable per deployment; the parsed lists arrive as `config.ipHeaders`. */
import type { IpHeaderConfig } from '../config';

// Order matters: client-forwarded headers (set explicitly by SDKs/upstream
// servers) must come before infrastructure headers like `cf-connecting-ip`.
// Otherwise, when our API sits behind Cloudflare (orange cloud), Cloudflare
// rewrites `cf-connecting-ip` to the SDK server's IP — losing the original
// end-user IP that the SDK forwarded in `x-client-ip` / `openpanel-client-ip`.
export const DEFAULT_IP_HEADER_ORDER = [
  'openpanel-client-ip',
  'true-client-ip',
  'x-client-ip',
  'cf-connecting-ip',
  'x-forwarded-for',
  'x-real-ip',
  'fastly-client-ip',
  'x-cluster-client-ip',
  'x-appengine-user-ip',
  'do-connecting-ip',
  'x-nf-client-connection-ip',
  'x-forwarded',
  'forwarded',
];

function isPublicIp(ip: string): boolean {
  // Handle IPv4-mapped IPv6 addresses (e.g., ::ffff:127.0.0.1)
  if (ip.startsWith('::ffff:')) {
    const ipv4Part = ip.substring(7);
    return isPublicIp(ipv4Part);
  }

  // IPv6 loopback
  if (ip === '::1') {
    return false;
  }

  // IPv6 private ranges (fc00::/7 and fe80::/10)
  if (
    ip.startsWith('fc00:') ||
    ip.startsWith('fd00:') ||
    ip.startsWith('fe80:')
  ) {
    return false;
  }

  // IPv4 loopback (127.0.0.0/8)
  if (ip.startsWith('127.')) {
    return false;
  }

  // 10.0.0.0/8
  if (ip.startsWith('10.')) {
    return false;
  }
  // 172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
  if (ip.startsWith('172.')) {
    const parts = ip.split('.');
    if (parts.length >= 2) {
      const secondOctet = Number.parseInt(parts[1] || '0', 10);
      if (secondOctet >= 16 && secondOctet <= 31) {
        return false;
      }
    }
  }
  // 192.168.0.0/16
  if (ip.startsWith('192.168.')) {
    return false;
  }
  // 169.254.0.0/16 (link-local)
  if (ip.startsWith('169.254.')) {
    return false;
  }

  return true;
}

function isValidIp(ip: string): boolean {
  const ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;
  const ipv6 = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
  return isPublicIp(ip) && (ipv4.test(ip) || ipv6.test(ip));
}

export function getClientIpFromHeaders(
  config: IpHeaderConfig,
  headers: Record<string, string | string[] | undefined> | Headers,
  overrideHeaderName?: string
): {
  ip: string;
  header: string;
} {
  let headerOrder = config.attributionOrder ?? DEFAULT_IP_HEADER_ORDER;

  if (overrideHeaderName) {
    headerOrder = [overrideHeaderName];
  }

  for (const headerName of headerOrder) {
    let value: string | null = null;

    if (headers instanceof Headers) {
      value = headers.get(headerName);
    } else {
      const headerValue = headers[headerName];
      if (Array.isArray(headerValue)) {
        value = headerValue[0] || null;
      } else {
        value = headerValue || null;
      }
    }

    if (!value) {
      continue;
    }

    // x-forwarded-for is comma separated; take the first entry.
    if (headerName === 'x-forwarded-for') {
      const firstIp = value.split(',')[0]?.trim();
      if (firstIp && isValidIp(firstIp)) {
        return { ip: firstIp, header: headerName };
      }
    }
    // Handle forwarded header (RFC 7239)
    else if (headerName === 'forwarded') {
      const match = value.match(/for=(?:"?\[?([^\]"]+)\]?"?)/i);
      const ip = match?.[1];
      if (ip && isValidIp(ip)) {
        return { ip, header: headerName };
      }
    } else if (isValidIp(value)) {
      return { ip: value, header: headerName };
    }
  }

  return { ip: '', header: '' };
}

/**
 * Headers that may be trusted for *security* decisions (rate limiting,
 * blocking, abuse tracking).
 *
 * `getClientIpFromHeaders` above deliberately prefers client-forwarded
 * headers (`openpanel-client-ip`, `x-client-ip`, `x-forwarded-for`) because an
 * SDK running on a customer's server forwards the end-user IP that way. That
 * trust is correct for analytics attribution and fatal for rate limiting:
 * anyone can send `x-client-ip: <random>` on every request and get an endless
 * supply of fresh buckets.
 *
 * This order only contains headers written by infrastructure we sit behind.
 * Cloudflare overwrites `cf-connecting-ip` on every request, so a forged value
 * never survives the edge. `x-real-ip` is written by the reverse proxy for
 * self-hosters running without Cloudflare.
 */
export const TRUSTED_IP_HEADER_ORDER = [
  'cf-connecting-ip',
  'x-real-ip',
  'x-forwarded-for',
];

/**
 * Resolve the client IP for security decisions. Never returns an IP a client
 * could have picked for itself.
 *
 * The order can be narrowed per deployment with `TRUSTED_IP_HEADER_ORDER`
 * (comma separated) - set it to the single header your edge guarantees.
 */
export function getTrustedIpFromHeaders(
  config: IpHeaderConfig,
  headers: Record<string, string | string[] | undefined> | Headers,
  socketIp?: string
): { ip: string; header: string } {
  const headerOrder = config.trustedOrder ?? TRUSTED_IP_HEADER_ORDER;

  for (const headerName of headerOrder) {
    let value: string | null = null;

    if (headers instanceof Headers) {
      value = headers.get(headerName);
    } else {
      const headerValue = headers[headerName];
      value =
        (Array.isArray(headerValue) ? headerValue[0] : headerValue) || null;
    }

    if (!value) {
      continue;
    }

    // A proxy chain appends as it goes, so the *last* entry is the one written
    // by the hop closest to us - the only entry a client cannot forge. This is
    // the opposite of what `getClientIpFromHeaders` wants, which is why the two
    // functions do not share this branch.
    const candidate =
      headerName === 'x-forwarded-for'
        ? value.split(',').pop()?.trim()
        : value.trim();

    if (candidate && isValidIp(candidate)) {
      return { ip: candidate, header: headerName };
    }
  }

  // Direct connection (local dev, or an edge that strips everything). The
  // socket address is by definition not client-controlled, so it is safe to
  // use even when private.
  if (socketIp) {
    return { ip: socketIp, header: 'socket' };
  }

  return { ip: '', header: '' };
}