Enforce each API key's rateLimitPerMinute in the gateway limiter instead of only labelling metrics with it #1505

Summary

Developers can set rateLimitPerMinute when they create an API key, and the value is stored and loaded with the key. Nothing enforces it. The gateway limiter buckets every key of a user together under user:<id>, and the tier limiter applies fixed per-tier policies. The per-key value is only copied into a metrics label. Separately, resolvePolicy uses tier in this.tierPolicies, so a tier string such as "constructor" resolves to an object prototype member, giving NaN limits that allow everything. This issue enforces per-key limits as a ceiling within the tier policy and hardens tier resolution.

Background and evidence

• Accepted and stored.
  • src/routes/apiKeyRoutes.ts (line 31) accepts rateLimitPerMinute: z.number().int().positive().nullable().optional().default(null).
  • src/repositories/apiKeyRepository.ts persists it (lines 146, 176).
  • src/middleware/gatewayApiKeyAuth.ts (line 423) loads it.
• Only used as a label. grep -rn rateLimitPerMinute src finds no limiter. Its only runtime use is advertisedLimitPerMinute in a metrics call in src/routes/proxyRoutes.ts (line 423).
• Shared user bucket. src/middleware/gatewayRateLimit.ts, getGatewayRateLimitKey (about lines 136-145), returns user:${apiKeyRecord.userId}, so all of a user's keys share one bucket.
• Prototype lookup. src/services/rateLimiter.ts, resolvePolicy (about lines 444-450), uses if (!tier || !(tier in this.tierPolicies)). The in operator walks the prototype chain, so a plan_tier of toString or constructor returns a function as the policy.

Scope

In scope

1. Two-level limiting. In the gateway rate-limit middleware, after the user or tier bucket check, check a key bucket key:<apiKeyId> with limit min(rateLimitPerMinute, tierLimit) per 60s when rateLimitPerMinute is set. Reject with 429 and RateLimit-* / Retry-After headers that reflect the stricter bucket.
2. Store reuse. Use the existing RateLimiterStore abstraction (InMemoryRateLimiterStore and the Postgres store) so per-key limits work in multi-instance mode.
3. Safe tier lookup. Use Object.prototype.hasOwnProperty.call(this.tierPolicies, tier), or a Map. Validate plan_tier against the known set when keys are created (src/routes/apiKeyRoutes.ts).
4. API visibility. Return the effective limit in GET /api/developers/me/keys and in the key creation response.
5. Docs. Update docs/tiered-rate-limits.md and docs/gateway-rate-limiting.md, and the OpenAPI schemas.

Out of scope

• Mounting the gateway proxy routers.
• Billing for rejected calls.

Design constraints

• Keys only narrow. A per-key limit can only lower the effective limit, never raise it above the tier.
• Truthful headers. RateLimit-* headers describe whichever bucket is closest to exhaustion.
• Hashed bucket keys. Bucket keys use the key id, never the raw key.

Test plan

Extend src/middleware/gatewayRateLimit.test.ts and src/services/rateLimiter.test.ts.

Regression proof. Rows 1 and 5 allow unlimited calls on current main.

Acceptance criteria

• Every test-plan row passes.
• npm run lint, npm run typecheck, npm run build and npm test pass, and CI is green.
• At least 90% line coverage on the touched limiter code.
• OpenAPI updated and npm run validate:openapi passes.

Getting started

git checkout -b feat/per-key-rate-limit
npm ci && npx prisma generate
npm run test:unit -- src/middleware/gatewayRateLimit src/services/rateLimiter

Read first: src/middleware/gatewayRateLimit.ts, resolvePolicy and the stores in src/services/rateLimiter.ts, and createApiKeyBodySchema in src/routes/apiKeyRoutes.ts.

PR requirements

• Link this issue (Closes #<n>).
• Explain how headers are chosen when two buckets apply.
• Paste test output and coverage.
• Example commit: feat(gateway): enforce per-key rateLimitPerMinute under the tier ceiling.

Priority rationale

Medium. It is contained to the limiter layer, but a documented control is currently a no-op and a malformed tier disables limiting entirely.