Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/171-trust-proxy-coverage.security.md
Original file line number Diff line number Diff line change
@@ -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.
14 changes: 14 additions & 0 deletions docs/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
120 changes: 120 additions & 0 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<number>(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> = {}): Config {
loadDotEnv()
const rawEnv = text('NODE_ENV', 'production').toLowerCase()
Expand Down
25 changes: 21 additions & 4 deletions src/lib/rateLimit.ts
Original file line number Diff line number Diff line change
@@ -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<string>(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`
}

Expand Down
79 changes: 77 additions & 2 deletions test/rateLimit.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<ReturnType<typeof buildApp>>) => Promise<void>, overrides: Partial<Config> = {}): Promise<void> {
Expand Down Expand Up @@ -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[] = []
Expand Down Expand Up @@ -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) {
Expand Down
Loading