Enable/disable IP resolution. Defaults to true when present.

When true, read the client IP from the proxy header instead of request.ip. Requires a trusted reverse proxy. Default: false.

WARNING: on its own this trusts the header's LEFTMOST entry, which is safe only behind a proxy that OVERWRITES the header. The standard nginx idiom appends instead, in which case the leftmost entry is whatever the client sent — set IpSecurityOptions.trustedProxies or IpSecurityOptions.proxyHops so the client is resolved from the right. Note that with false, clientIp is undefined on all first-party adapters (see the module note).

The header name to read when trustProxy is true. Default: X-Forwarded-For.

With neither IpSecurityOptions.trustedProxies nor IpSecurityOptions.proxyHops supplied, the LEFTMOST address is taken — which is the entry a client controls under an appending proxy (see those two options).

Addresses of the proxies in front of this application, as literal addresses or CIDR blocks. When supplied, the header is walked RIGHT to LEFT and the first entry that is not one of these is the client.

This is the standard algorithm, and what Express trust proxy and Fastify trustProxy offer. It matters because the common nginx idiom (proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for) APPENDS the peer address rather than overwriting the header — so with a request sent as X-Forwarded-For: 7.7.7.7 the proxy forwards 7.7.7.7, 198.51.100.9, and the leftmost default resolves the value the caller chose. Rate limits and IP allowlists keyed on that are keyed on attacker input.

Mutually exclusive with IpSecurityOptions.proxyHops; supplying both throws at middleware construction. Omitted, resolution stays leftmost, unchanged from before 0.5.0.

The number of proxies in front of this application, when they cannot be addressed by IP (a managed load balancer on a rotating address). The nth entry FROM THE RIGHT is the client: 1 skips the immediate peer's contribution, 2 skips two, and so on.

A header carrying fewer entries than proxyHops resolves to undefined rather than to whatever entry happens to be leftmost — a short header means the request did not traverse the expected chain, and guessing would reintroduce the spoof this option exists to close.

0 is the rightmost entry (no hop skipped). A value that is not a non-negative integer throws at middleware construction rather than silently resolving undefined on every request, which is what a negative, a fraction, or the NaN that Number() yields for an unset environment variable would otherwise do.

Mutually exclusive with IpSecurityOptions.trustedProxies.