πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
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)];
}