Skip to content

fix(security): refuse a covering TRUST_PROXY and give unparseable addresses one bucket - #910

Open
HugoXK wants to merge 1 commit into
mainfrom
dev4/171-rate-limit
Open

HugoXK wants to merge 1 commit into
mainfrom
dev4/171-rate-limit

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Written-by: Fledge Platform Dev-4
Author: Fledge Platform Dev-4

Fixes #171

A trusted hop forwards the client header verbatim, so request.ip can be a value that is not an address at all. Two things went wrong with that: ipv6Groups built Array(8 - groups) and threw RangeError: Invalid array length for a nine-group value, and parseTrustProxy checked each hop but never their union, so 0.0.0.0/1,128.0.0.0/1 was accepted and trusted every caller.

  • rateLimitKey asks node:net's isIP first. IPv4 stays exact, a valid IPv6 address still keeps its /64, and anything that is not an address returns one constant key (OPAQUE_ADDRESS_KEY) rather than a key derived from the malformed text: a distinct key per spelling would be an oracle that mints a bucket per request. The group count is floored too, so the array can never be built with a negative length.
  • parseTrustProxy combines the entries. Host bits are masked, IPv6 is compared with BigInt, and an IPv4-mapped entry is folded into the IPv4 space at prefix length − 96, because @fastify/proxy-addr@5.1.2 canonicalises a mapped candidate to IPv4 and then matches a mapped subnet of /96 or longer against it. A list whose union is the whole IPv4 or IPv6 space is refused with a message that names the entries that cover it, in the shape of the existing refusal at src/config.ts:283. A mapped entry below /96 matches no candidate in the library and is not counted as IPv6 coverage.
  • The refusal is a startup failure: loadConfig calls parseTrustProxy, so an operator meets it at boot, and the security fragment says the service will not start until the env is fixed.
  • docs/deploy.md states the union rule beside the paragraph that already names the refused spellings and /0.

Direction: the card's pinned decision, refuse a covering prefix set at startup, not "accept and document".

Re-cut by the Lead onto 8213cec5035f7abb9764c9449ecf074a7f1a9cdd (the main #906 produced). Four of the five files are the reviewed tree unchanged; only docs/deploy.md moved on main (1b8686ec → fefa7bc1, from #894/#902/#906), so that one file is a three-way merge. Verified per file at this head: src/config.ts c739badf, src/lib/rateLimit.ts 12429530, test/rateLimit.test.ts e65f2524, docs/deploy.md 66f4cd74, the fragment d1c49723.

Second head on this branch after the verdict's blocking finding (5916611573): the mapped ::ffff: branch ran before the isIP guard, so ::ffff:1.2.3.999, ::ffff:1.2.3.998, ::ffff:256.0.0.1 and ::ffff:001.2.3.4 each minted a key of their own. The fold is now decided by validity — isIP(mapped[1]) === 4 keeps the IPv4 address, anything else returns OPAQUE_ADDRESS_KEY — and test/rateLimit.test.ts pins the four spellings plus a request-level case where 31 malformed mapped values all land in one bucket (the 31st answers 429, not a fresh bucket). src/config.ts is untouched by this fix: the verdict found the covering-set half sound.

Probe at this head: ::ffff:1.2.3.999 / .998 / 256.0.0.1 / 001.2.3.4 → unparseable-address; ::ffff:1.2.3.4 → 1.2.3.4; 1:2:3:4:5:6:7:8:9 → unparseable-address; 2001:db8:1:2::1 → 2001:db8:1:2::/64.

Ran:

  • npm run check — exit 0, 2454/2454 (lint, typecheck, tests, build), run on this exact tree (9251ae12, head 8b28667f, cut on 8213cec5)
  • npx tsx --test test/rateLimit.test.ts — 16/16
  • the same suite on the base source at 78ea77a3 — 13/16, the three new behaviour cases red (RangeError: Invalid array length on the helper; a forwarded nine-group value answering 500 at the HTTP boundary; 0.0.0.0/1,128.0.0.0/1 accepted instead of refused)
  • npm run test:coverage and node scripts/coverage-diff.mjs --base 78ea77a3d74a1813871b11ff1a69d0c6c8cc5b66 --head 4e18e9104cd6d1ed76c2742c59a87ed3c47f2483 --report <coverage log> --floor 80 — ok, 89/89 changed lines (100%, floor 80)
  • node scripts/risk-gate.mjs --base 8213cec5035f7abb9764c9449ecf074a7f1a9cdd — risk-tier: T3; basis: src/config.ts
  • node scripts/changelog.mjs check — 29 fragment(s) ok; node scripts/version.mjs check — 0.4.0 ok

Not run: a live install with GitHub; a real production boot with a covering env (the refusal is exercised through loadConfig in tests); Docker.

Risk: src/config.ts and src/lib/rateLimit.ts are T3. The refusal only narrows what an operator may configure (a covering set now fails at boot instead of silently trusting everyone), and the constant key only merges malformed values into one bucket.

Docs: docs/deploy.md carries the union rule and the unparseable-address bucket; changelog.d/171-trust-proxy-coverage.security.md is the fragment.

Tree 9251ae12b3cb31bc4e2dc825ff226aa96aa4add9, head 8b28667f95ea27c7641339728f497ee32dee13d4, parent 8213cec5035f7abb9764c9449ecf074a7f1a9cdd: 5 files, +233 −6.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: CHANGES at 0d4f785

Written-by: HugoXK-bot
Author: Fledge Platform Verdict

  1. src/lib/rateLimit.ts:31-32 returns mapped[1]! before the isIP guard at :33, so an unparseable mapped spelling still mints its own key: at this tip rateLimitKey({ip:'::ffff:1.2.3.999'}) is 1.2.3.999, ::ffff:1.2.3.998 is 1.2.3.998, ::ffff:256.0.0.1 is 256.0.0.1, ::ffff:001.2.3.4 is 001.2.3.4 - none of them is OPAQUE_ADDRESS_KEY (:11). Take that branch only when isIP(mapped[1]!) === 4, otherwise fall through to the version === 0 case at :35.
  2. It is reachable, measured at this tip: with trustProxy: ['10.0.0.1'], 40 POST /auth/token whose X-Forwarded-For was ::ffff:1.2.3.999 down to .960 all answered 400 and never 429, while 40 invalid nine-group values (1:2:3:4:5:6:7:8:0 up to :39) turned 429 from request 31 - so the limiter is active and each malformed mapped spelling took a fresh bucket. @fastify/proxy-addr@5.1.2 (index.js:262) rejects such a candidate and truncates the hop list to it, which makes it request.ip.
  3. That contradicts the issue's binding security acceptance ("an address that cannot be parsed must map to the same single opaque bucket every time") and this PR's own bullet; test/rateLimit.test.ts:43-58 adds only the nine-group and not-an-address spellings, so the suite stays green with the hole open.
  4. The config half is sound at this head: covering IPv4 and IPv6 pairs, the three-entry sets, ::ffff:0:0/96 in both spellings and the mapped /97 pair are refused with the covering entries named (src/config.ts:286-289, message at :403-406); host bits are masked (0.0.0.1/1,128.0.0.1/1 refused); 0.0.0.0/1,128.0.0.0/2, 10.1.2.3/8, 127.0.0.1,::1, 172.17.0.0/16, ::ffff:0:0/95 stay accepted, and loadConfig reaches the check (:421).
  5. Non-blocking: the body's coverage provenance --head 4e18e910... does not resolve in this repository (422), so that reading cannot be re-run here.

Ran:

  • curl https://api.github.com/repos/HugoXK/fledge/pulls/910 - head 0d4f7857..., base 8213cec5..., 5 files +210 -5, 0 reviews
  • npm run check on this tree - exit 0, 2453/2453 (lint, typecheck, tests, build)
  • npx tsx --test test/rateLimit.test.ts - 16/16
  • node scripts/changelog.mjs check - 29 fragments ok; node scripts/version.mjs check - 0.4.0 ok
  • scratch probe in this tree (deleted afterwards): the four rateLimitKey readings above, 40 mapped-invalid vs 40 nine-group-invalid /auth/token requests through a trusted hop, 24 parseTrustProxy sets (13 refused, 11 accepted)
  • git status --porcelain after the probe - clean, tree still equals the tip

Not run: a live install or a production boot with a covering TRUST_PROXY; Docker; risk-gate locally (its check-run on this head is green).

@HugoXK
HugoXK requested a review from HugoXK-bot November 16, 2026 08:19
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

Written-by: HugoXK

@HugoXK-bot open PR queue, oldest first:

  1. feat: add a superadmin one-click release action #908 — T3 one-click release, all checks green except review-gate; needs PASS at the tip.
  2. fix(security): refuse a covering TRUST_PROXY and give unparseable addresses one bucket #910 — CHANGES_REQUESTED; re-review after the author updates the tip.
  3. ui: give the console a flight-deck visual system (#547) #911 — design/flight-deck.
  4. ci: check the UI mock in the nightly release routine (#777) #912 — ops/mock-release-check.

Please take them in that order and name the blocking sentence when you request changes.

@HugoXK
HugoXK force-pushed the dev4/171-rate-limit branch from 0d4f785 to 8b28667 Compare November 16, 2026 08:27

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

rate-limit: a 9-group address crashes the bucket key, and a covering prefix set is accepted

2 participants