Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

6.6 KB
Raw Blame
import { FastifyRequest } from "fastify";
import { lookupAsn, type AsnLookup } from "../../db/geolocation/asn.js";
import { getIpAddress } from "../../utils.js";
import { isDatacenterAsn } from "./botBlocking/datacenterAsns.js";

/**
 * ASN-aware client IP resolution β€” the durable successor to `getIpAddress`.
 *
 * The problem `getIpAddress` can't solve: no static header precedence is correct
 * for both topologies at once.
 *
 *   - Direct Cloudflare path  β€” `CF-Connecting-IP` is the real visitor and is
 *     non-spoofable; the forwarded headers are client-controllable noise.
 *   - First-party proxy path  β€” a customer fronts Rybbit with CloudFront / Fastly
 *     / nginx, so `CF-Connecting-IP` is the *proxy's* egress node and the visitor
 *     only survives in `X-Forwarded-For` / `X-Real-IP`.
 *
 * `getIpAddress` resolves this by always preferring the forwarded headers, which
 * fixes proxied customers but lets a direct visitor spoof their own geo.
 *
 * This variant removes that exposure by detecting the topology from the edge IP:
 * if `CF-Connecting-IP` belongs to a hosting/datacenter ASN, a first-party proxy
 * is in front, so we trust the forwarded visitor IP. Otherwise the edge IP is a
 * residential/business visitor and is authoritative β€” forwarded headers are
 * ignored, so they can't be spoofed.
 *
 * Wired as the default client-IP resolver for tracking ingestion, identify,
 * session replay, and feature-flag evaluation. When no Cloudflare edge is present
 * it delegates to `getIpAddress` (the simple header-precedence primitive).
 * Requires `GeoLite2-ASN.mmdb` (the same DB Layer-4 bot detection uses); see the
 * fallback note on `isProxiedEdge` below for the DB-missing behaviour.
 */

/** First non-empty `X-Forwarded-For` entry, or null. */
function firstForwardedFor(request: FastifyRequest): string | null {
  const forwardedFor = request.headers["x-forwarded-for"];
  if (forwardedFor && typeof forwardedFor === "string") {
    const ips = forwardedFor
      .split(",")
      .map(ip => ip.trim())
      .filter(Boolean);
    if (ips.length > 0) return ips[0];
  }
  return null;
}

function realIpHeader(request: FastifyRequest): string | null {
  const realIp = request.headers["x-real-ip"];
  return realIp && typeof realIp === "string" ? realIp.trim() : null;
}

function cfConnectingIp(request: FastifyRequest): string | null {
  const cfIp = request.headers["cf-connecting-ip"];
  return cfIp && typeof cfIp === "string" ? cfIp.trim() : null;
}

/**
 * Cloudflare sets this documented synthetic IP as `CF-Connecting-IP` on
 * cross-zone Worker subrequests β€” the topology produced by the first-party
 * Worker proxy pattern in our docs (visitor β†’ customer's Worker β†’ our zone).
 * Non-spoofable on the direct path: Cloudflare always overwrites
 * `CF-Connecting-IP` at the edge, so only a real Worker subrequest presents it.
 * https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-connecting-ip
 */
const CF_WORKER_SUBREQUEST_IP = "2a06:98c0:3600::103";

/**
 * Whether the connecting edge IP belongs to hosting/datacenter infrastructure β€”
 * positive evidence that a first-party proxy sits in front of our edge.
 *
 * The Cloudflare Worker subrequest IP is recognised unconditionally so the
 * documented Worker proxy setup keeps working even when the ASN DB is missing.
 *
 * Fallback semantics matter: if the ASN DB is unavailable, `lookupAsn` returns
 * null and this returns `false` β€” i.e. unknown edges are treated as direct and
 * `CF-Connecting-IP` wins. That is the safe default for the (vast) direct
 * majority, but it means proxied customers regress to seeing their proxy IP when
 * the DB is missing. If that trade-off is wrong for your deployment, default this
 * to `true` on a null lookup instead (favouring proxied correctness over
 * direct-path anti-spoofing).
 */
function isProxiedEdge(ip: string, asnLookup: AsnLookup): boolean {
  if (ip.toLowerCase() === CF_WORKER_SUBREQUEST_IP) return true;
  return isDatacenterAsn(asnLookup(ip)?.asn);
}

export interface ResolveClientIpOptions {
  /**
   * Site-level declaration that a first-party proxy fronts this site's traffic.
   * Skips ASN topology inference entirely: forwarded headers are trusted
   * unconditionally, exactly like the pre-ASN `getIpAddress` precedence.
   */
  firstPartyProxy?: boolean;
  /**
   * ASN resolver to infer the topology with. Tracking ingestion passes the
   * request-scoped one so the edge IP is looked up once for the whole request.
   */
  lookupAsn?: AsnLookup;
  /** Injectable for tests so branching can be exercised without the MaxMind DB. */
  proxiedEdge?: (ip: string) => boolean;
}

export function resolveClientIp(request: FastifyRequest, options: ResolveClientIpOptions = {}): string {
  const asnLookup = options.lookupAsn ?? lookupAsn;
  const proxiedEdge = options.proxiedEdge ?? (ip => isProxiedEdge(ip, asnLookup));
  const realIp = realIpHeader(request);
  const xffFirst = firstForwardedFor(request);
  const cfIp = cfConnectingIp(request);

  if (options.firstPartyProxy) {
    return realIp ?? xffFirst ?? cfIp ?? getIpAddress(request);
  }

  if (cfIp) {
    if (proxiedEdge(cfIp)) {
      // First-party proxy in front: trust the forwarded visitor IP, fall back to
      // the edge IP only if the proxy forwarded nothing.
      return realIp ?? xffFirst ?? cfIp;
    }
    // Direct visitor: the edge IP is authoritative and non-spoofable. Ignore
    // forwarded headers entirely.
    return cfIp;
  }

  // No Cloudflare edge (e.g. self-hosted behind nginx): there's no edge IP to
  // corroborate, so defer to plain header precedence (X-Real-IP, then
  // X-Forwarded-For, then the socket IP).
  return getIpAddress(request);
}

/**
 * Every IP this request could plausibly belong to, resolved or not: the
 * Cloudflare edge IP, X-Real-IP, every X-Forwarded-For hop, and the socket.
 *
 * For IP *exclusion* only β€” where over-matching is the desired failure mode
 * (worst case, a stray event from someone sharing an IP with the site owner is
 * dropped). Never use this for identity, geo, or anything spoofing-sensitive.
 */
export function collectCandidateClientIps(
  request: FastifyRequest,
  extra: Array<string | null | undefined> = []
): string[] {
  const forwardedFor = request.headers["x-forwarded-for"];
  const forwardedEntries =
    forwardedFor && typeof forwardedFor === "string"
      ? forwardedFor
          .split(",")
          .map(ip => ip.trim())
          .filter(Boolean)
      : [];

  const candidates = [
    ...extra,
    cfConnectingIp(request),
    realIpHeader(request),
    ...forwardedEntries,
    request.ip,
  ].filter((ip): ip is string => Boolean(ip));

  return [...new Set(candidates)];
}