fix: make rate limiting auth-aware under shared proxy ips

[lc0rp]

Summary

Today, API rate limiting blocks based on IP or key. In proxied/shared-egress environments, IP sharing can deny legitimate authenticated users.

Ref issues: #349, #390

• Make API rate limiting prefer key for authenticated requests and keep IP enforcement for anonymous/invalid-token requests
• Invert trusted fallback precedence to x-forwarded-for -> x-real-ip -> fly-client-ip
• Add structured deny logs (auth, userAllowed, ipAllowed, ipSource, hasClientIp)
• Update HTTP API docs to reflect auth-aware limiter semantics

Rationale

• current ip OR key deny behavior can block valid authenticated users behind shared egress/proxy IPs
• user-first enforcement for authenticated traffic reduces false positives while preserving anonymous IP controls
• x-forwarded-for first hop is the more common client-IP signal in trusted proxy chains

Work done

• convex/lib/httpRateLimit.ts
  • switched to auth-aware decision model
  • switched trusted fallback precedence to x-forwarded-for first
  • added structured rate-limit deny logging
• convex/lib/httpRateLimit.test.ts
  • added auth-vs-anon enforcement regression coverage
  • added forwarded-header precedence coverage
• convex/httpApiV1.handlers.test.ts
  • adjusted auth mocks for stars routes under new limiter path
• docs/http-api.md, docs/api.md
  • documented auth-aware enforcement semantics

Testing

bun run lint
bunx vitest run convex/lib/httpRateLimit.test.ts convex/httpApiV1.handlers.test.ts
bun run test

Checklist

• Added test coverage and tested
• bun run lint
• Tested and working locally

Tag-teamed w/ codex 5.3 on this 🤖

Fixes #411, #349, #390

Greptile Summary

Modified rate limiting from IP OR key enforcement to auth-aware enforcement: authenticated requests now consume only user buckets, while anonymous requests use IP buckets. This prevents legitimate authenticated users from being blocked by shared proxy IPs while preserving IP-based protection for anonymous traffic.

Key changes:

• Switched IP header precedence to x-forwarded-for → x-real-ip → fly-client-ip (more common proxy pattern)
• Authenticated requests skip IP bucket consumption entirely (addressed previous reviewer's concern)
• Added structured deny logging with auth status, IP source, and bucket states
• Fixed double header parsing in client SDK (addressed previous reviewer's concern)
• Enhanced client retry logic to respect Retry-After headers with jitter
• Updated rate limit headers to include both legacy (X-RateLimit-*) and standardized (RateLimit-*) formats
• Comprehensive test coverage for auth vs anonymous enforcement, token validation fallback, and header precedence

Confidence Score: 5/5

• This PR is safe to merge with no blocking issues
• The implementation correctly addresses the shared proxy IP problem with clean auth-aware logic, comprehensive test coverage validates all critical paths including edge cases, previous review concerns about IP consumption and header parsing have been properly fixed, documentation is thorough, and the changes follow established patterns in the codebase
• No files require special attention

_{Last reviewed commit: a176658}

[vercel]

@lc0rp is attempting to deploy a commit to the Amantus Machina Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

_{10 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[lc0rp]

@greptileai I addressed the comments. Thoughts?

[greptile-apps]

Looks good! Both issues are resolved:

1. IP bucket isolation - Authenticated requests now only touch the user bucket. The code cleanly branches at if (userId) and never calls checkRateLimit for the IP when authenticated, so shared proxy IPs won't starve anonymous users.

2. Header precedence docs - docs/http-api.md now correctly lists x-forwarded-for before x-real-ip, matching the implementation.

The auth-aware enforcement logic is clear, the retry/header parsing improvements are solid, and test coverage looks thorough. Good to merge.

[lc0rp]

@greptileai Do you edit the score added to the description when comments are addressed?

[greptile-apps]

No, I don't automatically edit the score in the PR description when comments are addressed. The score reflects my assessment at the time of the last full review (commit 321bc9f in this case).

If you'd like an updated score after addressing comments, you would typically:

1. Ask me to re-review the PR, or
2. Push new commits, which would trigger a fresh review with an updated score

The score in the description is essentially a snapshot from that review moment, not a living counter that updates as discussion progresses.

[lc0rp]

Gotcha, @greptileai re-review the PR and update the score