Implement tiered rate-limit policies in `rateLimiter` driven by API key plan tier

[greatest0fallt1me]

Description

The gateway currently uses a single token-bucket per key in src/services/rateLimiter.ts with one default maxRequests/windowMs pair. To support paid plans and abuse control, we need per-tier policies (e.g. free, pro, enterprise) resolved from the API key record so that /v1/call/* enforces the correct ceiling for each tier without code changes.

Requirements and Context

• Extend RateLimiterConfig to accept a tier -> { maxRequests, windowMs } map and a tier resolver that reads from apiKeyRepository
• Wire gatewayApiKeyAuth middleware to set res.locals.apiKeyTier so proxyRoutes passes it into rateLimiter.check
• Keep backwards-compatible defaults when no tier is present
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b feature/tiered-rate-limits

2. Implement changes
   • src/services/rateLimiter.ts
   • src/middleware/gatewayApiKeyAuth.ts
   • src/routes/proxyRoutes.ts
   • src/repositories/apiKeyRepository.ts
3. Test and commit
   • npm test -- rateLimiter
   • Cover edge cases (missing tier, unknown tier, hot-reload)
   • Include test output and notes in the PR

Example commit message

feat: tiered rate limit policies driven by api key plan

Acceptance Criteria

• rateLimiter.check honors per-tier maxRequests/windowMs
• Unknown tier falls back to default with a warning log
• Tests assert each tier ceiling and refill behaviour
• Docs added under docs/ describing tier config

Guidelines

• Backend (Node/TS): real service/route/module paths, tests with Jest, input validation, error handling, minimum 90% test coverage
• Clear documentation and inline comments
• Timeframe: 96 hours

[temisan0x]

@temisan0x has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

hey team, i’d like to take on this issue
I’ve been able to go through it
I can start on it now if it’s okay

ℹ️ Repo Maintainers: To accept this application, review their application or assign @temisan0x to this issue.

[Ope4196]

@Ope4196 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi Boss... I can handle this professionally and make sure that your issue is closed quickly without errors.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ope4196 to this issue.

[drips-wave]

Congratulations, @temisan0x! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @temisan0x: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@temisan0x's PR #440 was approved and merged by @greatest0fallt1me.

🏆 @temisan0x: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (856 total points). Track your full progress on GrantFox.

👏 Great work, @temisan0x! Keep contributing to CalloraOrg.

[drips-wave]

This issue has been completed by @temisan0x as part of the Stellar Wave Program's 6th Wave 🥳

😎 @temisan0x: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.