From 8b28667f95ea27c7641339728f497ee32dee13d4 Mon Sep 17 00:00:00 2001 From: Day Dreamer <87640074+HugoXK@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:27:09 +0800 Subject: [PATCH] fix(security): refuse a covering TRUST_PROXY and give unparseable addresses one bucket (#171) --- .../171-trust-proxy-coverage.security.md | 1 + docs/deploy.md | 14 ++ src/config.ts | 120 ++++++++++++++++++ src/lib/rateLimit.ts | 25 +++- test/rateLimit.test.ts | 79 +++++++++++- 5 files changed, 233 insertions(+), 6 deletions(-) create mode 100644 changelog.d/171-trust-proxy-coverage.security.md diff --git a/changelog.d/171-trust-proxy-coverage.security.md b/changelog.d/171-trust-proxy-coverage.security.md new file mode 100644 index 00000000..d1c49723 --- /dev/null +++ b/changelog.d/171-trust-proxy-coverage.security.md @@ -0,0 +1 @@ +A `TRUST_PROXY` whose entries together cover the whole IPv4 or IPv6 space is now refused at startup, the same way a `/0` range already was: host bits are masked, the entries are combined, and an IPv4-mapped prefix such as `::ffff:0:0/96` counts as the IPv4 range it actually trusts. An installation running such a list will not boot until the env names the proxy address or its narrow CIDR; a list that stops short of the whole space still starts. Separately, a request address that cannot be parsed - for example nine groups forwarded verbatim by a trusted hop - now falls into one shared rate-limit bucket instead of answering 500. diff --git a/docs/deploy.md b/docs/deploy.md index fefa7bc1..66f4cd74 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -778,6 +778,20 @@ because each of them trusts the caller-supplied left end of the header. A not seen, so clients behind that proxy share one rate-limit bucket until the hop is corrected. +The entries are also combined, not only checked one at a time: a list whose union +is the whole IPv4 or IPv6 space is refused, because it trusts every caller +exactly as a `/0` would. Host bits are masked before the comparison, and an +IPv4-mapped entry counts as the IPv4 range it actually trusts (proxy-addr matches +a mapped subnet of `/96` or longer against IPv4 callers), so +`0.0.0.0/1,128.0.0.0/1`, `::/1,8000::/1` and `::ffff:0:0/96` all fail with +`TRUST_PROXY: ... together cover the whole IPv4 space` (singular `covers` for a +single entry) and the service does not boot until the env names the proxy address +or its narrow CIDR. A list that stops short of the whole space - three quarters of +IPv4, a bridge gateway, a Cloudflare-sized set - is accepted. A request address +that cannot be parsed at all, such as the nine-group value a trusted hop can +forward verbatim, falls into one shared rate-limit bucket instead of answering +500. + Set `BASE_URL=https://fledge.example.com` so cookies are `Secure` and email links are absolute. diff --git a/src/config.ts b/src/config.ts index 6541fa7a..c739badf 100644 --- a/src/config.ts +++ b/src/config.ts @@ -283,9 +283,129 @@ export function parseTrustProxy(raw: string): string[] { throw new Error(`TRUST_PROXY: "${hop}" is not a trusted hop. Name the proxy address or CIDR that may append X-Forwarded-For (for example 127.0.0.1,::1). true, false, "*", "all" and a /0 range are refused because they trust the caller-supplied left end of the header.`) } } + const ranges = hops.flatMap((hop) => trustedRanges(hop)) + for (const space of ['ipv4', 'ipv6'] as const) { + const covering = coveringSubset(ranges.filter((range) => range.space === space), space === 'ipv4' ? IPV4_SPACE : IPV6_SPACE) + if (covering !== null) throw new Error(coveringMessage(covering, space === 'ipv4' ? 'IPv4' : 'IPv6')) + } return hops } +// `true`, `*`, `all` and a literal /0 are refused one entry at a time above, but +// a list whose union is the whole space trusts every caller just the same. The +// check below is numeric: host bits are masked, IPv6 uses BigInt, and an +// IPv4-mapped entry is folded into the IPv4 space because +// @fastify/proxy-addr canonicalises a mapped candidate to IPv4 and then matches +// a mapped subnet whose prefix is at least /96. +const IPV4_SPACE = 1n << 32n +const IPV6_SPACE = 1n << 128n + +interface TrustedRange { + space: 'ipv4' | 'ipv6' + start: bigint + end: bigint + label: string +} + +function parseIPv4(address: string): bigint | null { + const parts = address.split('.') + if (parts.length !== 4) return null + let value = 0n + for (const part of parts) { + if (!/^\d{1,3}$/.test(part)) return null + const octet = Number(part) + if (octet > 255) return null + value = (value << 8n) | BigInt(octet) + } + return value +} + +function parseIPv6(address: string): bigint | null { + const halves = address.replace(/%.*$/, '').split('::') + if (halves.length > 2) return null + const groupsOf = (part: string): number[] | null => { + if (part === '') return [] + const groups: number[] = [] + for (const group of part.split(':')) { + if (group.includes('.')) { + const embedded = parseIPv4(group) + if (embedded === null) return null + groups.push(Number(embedded >> 16n), Number(embedded & 0xffffn)) + continue + } + if (!/^[0-9a-f]{1,4}$/i.test(group)) return null + groups.push(Number.parseInt(group, 16)) + } + return groups + } + const head = groupsOf(halves[0] ?? '') + if (head === null) return null + if (halves.length === 1) { + if (head.length !== 8) return null + return head.reduce((value, group) => (value << 16n) | BigInt(group), 0n) + } + const tail = groupsOf(halves[1] ?? '') + if (tail === null) return null + const zeros = 8 - head.length - tail.length + if (zeros < 1) return null + const groups = [...head, ...Array(zeros).fill(0), ...tail] + return groups.reduce((value, group) => (value << 16n) | BigInt(group), 0n) +} + +function maskRange(space: 'ipv4' | 'ipv6', value: bigint, prefix: number, label: string): TrustedRange { + const bits = space === 'ipv4' ? 32n : 128n + const block = 1n << (bits - BigInt(prefix)) + const start = value & -block + return { space, start, end: start + block - 1n, label } +} + +function trustedRanges(hop: string): TrustedRange[] { + const [address = '', prefixText] = hop.split('/') + const version = isIP(address) + if (version === 4) { + const value = parseIPv4(address) + if (value === null) return [] + return [maskRange('ipv4', value, prefixText === undefined ? 32 : Number(prefixText), `"${hop}"`)] + } + if (version !== 6) return [] + const value = parseIPv6(address) + if (value === null) return [] + const prefix = prefixText === undefined ? 128 : Number(prefixText) + // A mapped prefix below the marker matches no candidate at all in + // proxy-addr (its cross-family guard only spans IPv4 when range >= 96). + if (value >> 32n !== 0xffffn) return [maskRange('ipv6', value, prefix, `"${hop}"`)] + if (prefix < 96) return [] + return [maskRange('ipv4', value & 0xffffffffn, prefix - 96, `"${hop}" (an IPv4-mapped prefix)`)] +} + +// Greedy cover from the bottom of the space. Returns the entries that reach the +// top when the union is contiguous, or null when a gap remains. Only the subset +// that does the covering is returned, so a long hop list is not echoed back. +function coveringSubset(ranges: TrustedRange[], space: bigint): TrustedRange[] | null { + const sorted = [...ranges].sort((left, right) => (left.start < right.start ? -1 : left.start > right.start ? 1 : 0)) + const covering: TrustedRange[] = [] + let cursor = 0n + let index = 0 + while (cursor < space) { + let best: TrustedRange | null = null + while (index < sorted.length && sorted[index]!.start <= cursor) { + const candidate = sorted[index]! + if (best === null || candidate.end > best.end) best = candidate + index += 1 + } + if (best === null || best.end < cursor) return null + covering.push(best) + cursor = best.end + 1n + } + return covering +} + +function coveringMessage(covering: TrustedRange[], space: 'IPv4' | 'IPv6'): string { + const labels = covering.map((range) => range.label) + const named = labels.length === 1 ? labels[0]! : `${labels.slice(0, -1).join(', ')} and ${labels[labels.length - 1]!}` + return `TRUST_PROXY: ${named} ${labels.length === 1 ? 'covers' : 'together cover'} the whole ${space} space, so the list trusts the caller-supplied left end of X-Forwarded-For. Name the proxy address or its narrow CIDR instead; a set that covers the space is refused like a /0 range.` +} + export function loadConfig(overrides: Partial = {}): Config { loadDotEnv() const rawEnv = text('NODE_ENV', 'production').toLowerCase() diff --git a/src/lib/rateLimit.ts b/src/lib/rateLimit.ts index f2c28440..12429530 100644 --- a/src/lib/rateLimit.ts +++ b/src/lib/rateLimit.ts @@ -1,25 +1,42 @@ +import { isIP } from 'node:net' + interface Bucket { count: number resetAt: number } +// One bucket for every address that cannot be parsed. Deriving a key from the +// malformed text would mint a bucket per spelling, which is an oracle for +// anyone who can influence request.ip. +export const OPAQUE_ADDRESS_KEY = 'unparseable-address' + function ipv6Groups(ip: string): string[] { const [head = '', tail = ''] = ip.split('::') const headGroups = head === '' ? [] : head.split(':') const tailGroups = tail === '' ? [] : tail.split(':') - const zeros = 8 - headGroups.length - tailGroups.length + // Floored as well as guarded by the isIP call below, so no caller can hand + // this a group count that indexes out of range. + const zeros = Math.max(0, 8 - headGroups.length - tailGroups.length) return [...headGroups, ...Array(zeros).fill('0'), ...tailGroups].map((group) => group.toLowerCase().replace(/^0+(?=.)/, '')) } // A bucket has to be keyed on an identity the client cannot mint per request. // IPv4 is exact. IPv6 keeps only its /64 prefix, because one client commonly // controls a whole /64, so the low 64 bits are free to rotate and a per-address -// key is worth nothing. +// key is worth nothing. Anything that is not an address collapses onto one key: +// a trusted hop can forward a malformed value verbatim, and a per-spelling key +// would let that value mint buckets (and answer 500 for more than eight groups). export function rateLimitKey(request: { ip: string }): string { const ip = request.ip.replace(/%.*$/, '') + const version = isIP(ip) + if (version === 4) return ip + if (version === 0) return OPAQUE_ADDRESS_KEY + // The pattern below checks digit shape only, so a spelling like + // ::ffff:1.2.3.999 matches it without being an address. Validity decides the + // fold: an invalid mapped spelling keeps the opaque key instead of minting a + // bucket per spelling. const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(ip) - if (mapped !== null) return mapped[1]! - if (!ip.includes(':')) return ip + if (mapped !== null) return isIP(mapped[1]!) === 4 ? mapped[1]! : OPAQUE_ADDRESS_KEY return `${ipv6Groups(ip).slice(0, 4).join(':')}::/64` } diff --git a/test/rateLimit.test.ts b/test/rateLimit.test.ts index 8e9dc42f..e65f2524 100644 --- a/test/rateLimit.test.ts +++ b/test/rateLimit.test.ts @@ -2,10 +2,10 @@ import test from 'node:test' import assert from 'node:assert/strict' import { readFileSync } from 'node:fs' import { buildApp } from '../src/app.js' -import { loadConfig, type Config } from '../src/config.js' +import { loadConfig, parseTrustProxy, type Config } from '../src/config.js' import { Store } from '../src/db.js' import { MockRunner } from '../src/jobs/mock.js' -import { rateLimitKey } from '../src/lib/rateLimit.js' +import { OPAQUE_ADDRESS_KEY, rateLimitKey } from '../src/lib/rateLimit.js' import { MemoryMailer, testConfig } from './helpers.js' async function withApp(run: (built: Awaited>) => Promise, overrides: Partial = {}): Promise { @@ -40,6 +40,52 @@ test('the bucket key is the client address, not a raw string a client can mint', assert.equal(rateLimitKey({ ip: '::1' }), rateLimitKey({ ip: '::ffff:0:1' })) }) +test('a malformed address cannot crash the bucket key or mint a bucket per spelling', () => { + // A trusted hop forwards the client header verbatim, so more than eight groups + // reach request.ip. It used to throw RangeError: Invalid array length. + assert.equal(typeof rateLimitKey({ ip: '1:2:3:4:5:6:7:8:9' }), 'string') + assert.equal(typeof rateLimitKey({ ip: '1:2:3:4:5:6:7:8:9:a' }), 'string') + // One constant key, not a key per malformed spelling: a derived key would be + // an oracle that mints a fresh bucket for every request. + assert.equal(rateLimitKey({ ip: '1:2:3:4:5:6:7:8:9' }), OPAQUE_ADDRESS_KEY) + assert.equal(rateLimitKey({ ip: '1:2:3:4:5:6:7:8:9:a' }), OPAQUE_ADDRESS_KEY) + assert.equal(rateLimitKey({ ip: 'not-an-address' }), OPAQUE_ADDRESS_KEY) + // The mapped pattern checks digit shape, not validity. A spelling that matches + // it but is not an address must share the opaque key, not mint one per value. + for (const spelling of ['::ffff:1.2.3.999', '::ffff:1.2.3.998', '::ffff:256.0.0.1', '::ffff:001.2.3.4']) { + assert.equal(rateLimitKey({ ip: spelling }), OPAQUE_ADDRESS_KEY, `${spelling} minted its own key`) + } + // Guards, unchanged by the fallback: the zone id is stripped and a mapped + // address stays the IPv4 address it is. + assert.equal(rateLimitKey({ ip: 'fe80::1%eth0' }), 'fe80:0:0:0::/64') + assert.equal(rateLimitKey({ ip: '::ffff:127.0.0.1' }), '127.0.0.1') +}) + +test('a trusted hop forwarding malformed mapped spellings answers too many requests, not a fresh bucket', async () => { + await withApp(async (built) => { + const statuses: number[] = [] + for (let i = 0; i < 31; i += 1) { + // Every value has a different digit shape, so a key derived from the text + // would open a new bucket for each one. + const response = await tokenLogin(built, '10.0.0.2', `::ffff:1.2.3.${999 - i}`) + statuses.push(response.statusCode) + } + assert.equal(statuses[30], 429, `the 31st malformed mapped value answered ${statuses[30]} instead of 429; statuses ${statuses.join(',')}`) + }, { trustProxy: ['10.0.0.1', '10.0.0.2'] }) +}) + +test('a nine-group address forwarded by a trusted hop answers 400, never 500', async () => { + await withApp(async (built) => { + // The two-hop shape: the inner hop forwarded the malformed value verbatim, + // so request.ip is the nine-group address and it decides the bucket. + const forwarded = await tokenLogin(built, '10.0.0.2', '1:2:3:4:5:6:7:8:9') + assert.ok(forwarded.statusCode === 400 || forwarded.statusCode === 429, `a forwarded nine-group address answered ${forwarded.statusCode} instead of 400 or 429`) + // The peer itself carries the malformed address. + const peer = await tokenLogin(built, '1:2:3:4:5:6:7:8:9') + assert.ok(peer.statusCode === 400 || peer.statusCode === 429, `a nine-group peer answered ${peer.statusCode} instead of 400 or 429`) + }, { trustProxy: ['10.0.0.1', '10.0.0.2'] }) +}) + test('a rotating forged X-Forwarded-For from one untrusted peer does not mint new buckets', async () => { await withApp(async (built) => { const statuses: number[] = [] @@ -121,6 +167,35 @@ test('the app refuses to start when TRUST_PROXY is not an address or CIDR', () = } }) +test('the app refuses to start when the hops together cover the whole space', () => { + // Each entry below is a legal prefix on its own; the union is what trusts + // every caller, so the check has to be numeric, not per entry. + for (const covering of ['0.0.0.0/1,128.0.0.0/1', '::/1,8000::/1', '0.0.0.0/1,128.0.0.0/2,192.0.0.0/2', '::ffff:0:0/96', '::ffff:0.0.0.0/96', '::ffff:0.0.0.0/97,::ffff:128.0.0.0/97']) { + withTrustProxy(covering, () => assert.throws(() => loadConfig({ env: 'test' }), /TRUST_PROXY/, `"${covering}" must be refused`)) + } + // The message names the covering entries and the space, so an operator can fix + // the env without guessing which line did it. + withTrustProxy('0.0.0.0/1,128.0.0.0/1', () => assert.throws(() => loadConfig({ env: 'test' }), /"0\.0\.0\.0\/1" and "128\.0\.0\.0\/1" together cover the whole IPv4 space/)) + withTrustProxy('::ffff:0:0/96', () => assert.throws(() => loadConfig({ env: 'test' }), /"::ffff:0:0\/96" \(an IPv4-mapped prefix\) covers the whole IPv4 space/)) + // Directly on the parser too: the refusal is not only reachable through boot. + assert.throws(() => parseTrustProxy('0.0.0.0/1,128.0.0.0/1'), /TRUST_PROXY/) + assert.throws(() => parseTrustProxy('::/1,8000::/1'), /TRUST_PROXY/) +}) + +test('a hop list that stops short of the whole space still starts', () => { + // Three quarters of IPv4, host bits set, a mapped single address, a mapped + // prefix below the marker that matches nothing, and the default list: none of + // these cover the space, so none may lock an operator out. + assert.deepEqual(parseTrustProxy('0.0.0.0/1,128.0.0.0/2'), ['0.0.0.0/1', '128.0.0.0/2']) + assert.deepEqual(parseTrustProxy('10.1.2.3/8'), ['10.1.2.3/8']) + assert.deepEqual(parseTrustProxy('127.0.0.1,::1'), ['127.0.0.1', '::1']) + assert.deepEqual(parseTrustProxy('172.17.0.0/16'), ['172.17.0.0/16']) + assert.deepEqual(parseTrustProxy('::ffff:127.0.0.1'), ['::ffff:127.0.0.1']) + assert.deepEqual(parseTrustProxy('::ffff:0:0/95'), ['::ffff:0:0/95']) + assert.deepEqual(parseTrustProxy('fe80:0:0:0:0:0:0:1'), ['fe80:0:0:0:0:0:0:1']) + withTrustProxy('0.0.0.0/1,128.0.0.0/2', () => assert.deepEqual(loadConfig({ env: 'test' }).trustProxy, ['0.0.0.0/1', '128.0.0.0/2'])) +}) + test('a configured proxy hop is trusted: the appended client address, not the peer, decides the bucket', async () => { await withApp(async (built) => { for (let i = 0; i < 30; i += 1) {