Replace the per-IP rate limiter with a trustworthy key behind a proxy (trust proxy + X-Forwarded-For)

[mikewheeleer]

Harden the rate limiter against spoofed client IPs behind a proxy

Description

The rate limiter in src/index.ts keys buckets on req.ip ?? req.socket.remoteAddress. Express does not trust proxies by default, so behind a load balancer every request shares the proxy's IP (limiting everyone together), and if trust proxy is later enabled naively, a spoofed X-Forwarded-For lets an attacker evade the limit entirely. This issue makes the limiter key trustworthy in a proxied deployment.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add a TRUST_PROXY env setting wired to app.set("trust proxy", ...) so req.ip reflects the real client behind a known proxy hop count.
• When auth is present, prefer keying the limiter on the API key over the IP to avoid shared-NAT throttling.
• Document the deployment assumption (only enable trust proxy behind a proxy you control).
• Keep the 429 rate_limited response shape and Retry-After header intact.

Suggested execution

• Fork the repo and create a branch
• git checkout -b security/security-18-trust-proxy-rate-key
• Implement changes
  • Write code in: the app bootstrap and rate-limit middleware in src/index.ts.
  • Write comprehensive tests in: new src/ratelimit-key.test.ts — spoofed XFF cannot bypass when trust-proxy is off; api-key keying isolates callers.
  • Add documentation: add a "Running behind a proxy" section to README.md.
  • Add TSDoc on the key-derivation helper.
  • Validate security assumptions: XFF only honoured when explicitly trusted.
• Test and commit

Test and commit

• Run npm run build, npm test, and npm run lint.
• Cover edge cases: trust-proxy off + XFF set, trust-proxy on, api-key vs ip keying.
• Include the full npm test output and a threat-model note in the PR description.

Example commit message

security: derive rate-limit key from trusted proxy ip or api key

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.