Repository navigation
fix(security): explicit trusted-client-IP contract for rate limiting (CD-05) - #4070
Merged
Merged
Conversation
…(CD-05) getClientIp took the FIRST X-Forwarded-For segment as the rate-limit identity. Every proxy layer in the production chain (Cloudflare -> ALB -> openresty -> app) merely APPENDS to XFF without sanitizing, so a client sending "X-Forwarded-For: 203.0.113.77" arrived at the app as the first segment (captured at the container: "203.0.113.77, <real-client>, <cf-edge>, <real-client>") and fully controlled every per-IP bucket key (authChallenge 30/min, authLoginIp 10/min, steemBroadcast 30/min). After CD-04 the per-IP bucket is the only gate for unauthenticated login floods, which made the spoof critical. Replace the implicit header priority with an explicit trust contract: - New env var TRUSTED_CLIENT_IP_HEADER declaring WHICH header the deployment trusts: x-real-ip (recommended for our openresty chain, which sets it unconditionally from the rewritten $remote_addr), cf-connecting-ip (directly behind Cloudflare), xff-tail (last XFF entry, appended by the closest proxy; as trustworthy as that proxy), or unset/none (direct exposure). Only the declared header is read; every other candidate header is ignored entirely (a forged XFF has zero effect under x-real-ip). Values must be strict IP literals (v4/v6, no ports/lists/leading zeros); IPv6 keeps /64 aggregation. - Unknown env values fail at module load (startup validation listing the valid modes) instead of silently degrading to no-trust. - Missing/invalid trusted header in a CONFIGURED deployment: the proxy always sets it, so such a request bypassed the proxy (direct-to-app) or the proxy is misconfigured. It is never exempt (dropping the header must not become a rate-limit escape); it shares one dedicated 'unattributed' bucket at the rule's normal per-IP limit, with a throttled warning. Legitimate users never land there. - UNSET mode (direct exposure): no header is trusted and no sound IP identity exists (route handlers have no socket peer address), so IP-dimension buckets are exempt with a throttled warning instead of collapsing all visitors into one shared quota where they 429 each other at site-wide ceilings. Identifier-dimension buckets (per- account login limit, CD-04) remain enforced. RATE_LIMITS and aggregateIpIdentity are unchanged; getClientIp's exported signature is unchanged. Deployment action item: set TRUSTED_CLIENT_IP_HEADER=x-real-ip as an EB environment property.
…t contract Review follow-up on #4070 (PR review round 1): - Document in the module comment, CONFIGURATION.md and .env.example that the trusted-header contract only holds for traffic that actually traverses the trusted proxy: a direct-to-app client can forge the declared header itself with arbitrary valid IP literals (for xff-tail, a single-entry X-Forwarded-For is entirely the client's own value), so the app port must be reachable only from the trusted proxy. Header validation cannot substitute for that segmentation. - login.test.ts: delete TRUSTED_CLIENT_IP_HEADER in afterAll so the trust mode never leaks into other test files sharing the worker (same cleanup discipline as the rate-limit tests).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The spoof chain (audit CD-05, confirmed by packet capture on 2026-10-24)
getClientIpinlib/cache/rate-limit.tstook the firstX-Forwarded-Forsegment as the rate-limit identity. All four proxy layers (Cloudflare → ALB → openresty → app) merely append to XFF without sanitizing, so a client-suppliedX-Forwarded-For: 203.0.113.77arrives at the app as the first segment and fully controls every per-IP bucket key (authChallenge30/min,authLoginIp10/min,steemBroadcast30/min). Captured at the container:Normal requests only worked by accident: Cloudflare writes the real client IP first when the client sends no XFF. After the CD-04 fix (#4066) the per-IP bucket is the only remaining gate for unauthenticated login floods, which made the spoof critical.
The contract
New env var
TRUSTED_CLIENT_IP_HEADERdeclares which header the deployment trusts:x-real-ipX-Real-IPonlyproxy_set_header X-Real-IP $remote_addr, unconditionally overwriting any client valuecf-connecting-ipCF-Connecting-IPonlyxff-tailnoneRules:
x-real-ip(there is also no fallback to undeclared headers — see missing-header design below).aggregateIpIdentity) is preserved for every trusted source.RATE_LIMITSunchanged;aggregateIpIdentityunchanged;getClientIp(request)signature unchanged.Missing-header design (the deliberate asymmetry)
unattributedbucket at the rule's normal per-IP limit. Legitimate users never land there, so the shared bucket cannot cause cross-user lockout — only the anomalous traffic is collectively capped. A throttled (1/min) warning names the mode and the anomaly.Test evidence
__tests__/lib/cache/rate-limit.test.tsreworked around aloadRateLimit(mode)loader (the mode is captured at module load, so mode tests re-import the module):x-real-ip(the exact captured spoof shape) and underxff-tail(spoofed first segment ignored);unattributedbucket at the normal limit + throttled warn (never exempt, never mixed into per-user buckets);Fail-on-pre-fix proof: reverting only
lib/cache/rate-limit.tstonext(keeping the new tests) fails 19 of the behavioral tests, including the spot-checkedx-real-ipspoof test,xff-taillast-entry test, the unset-mode exemption test, and the startup-validation throw.__tests__/api/auth/login.test.ts: onevi.hoistedblock setsTRUSTED_CLIENT_IP_HEADER=xff-tailso the CD-04 counting limiter's per-IP simulation (single-segment XFF values) keeps resolving distinct buckets; all 27 login tests green.Gates
pnpm lint:ci— 0 errorsnpx tsc --noEmit— cleanpnpm test— 87 files / 1134 tests passedDeployment action item (out of scope for this PR)
Set
TRUSTED_CLIENT_IP_HEADER=x-real-ipas an Elastic Beanstalk environment property when this ships (runtime read at module load — restart, no rebuild needed). Until it is set, the per-IP limiter runs in the exempt (unset) mode and logs the warning documenting that state.