B-10: API versioning and per-user rate limiting with Redis

[KuchiMercy]

Summary

The current @nestjs/throttler rate limiting is global (same limits for all users), and there is no API versioning. For production readiness and third-party API consumers, per-user rate limiting and versioned endpoints are essential.

Requirements

API Versioning

• Add a v1 prefix to all API routes (e.g., /v1/escrows, /v1/auth/challenge)
• Use NestJS URI versioning (app.enableVersioning({ type: VersioningType.URI }))
• Maintain backward compatibility during transition (redirect non-versioned routes to v1)
• Document the versioning strategy for API consumers

Per-User Rate Limiting

• Replace the global throttler with per-user rate limiting backed by Redis
• Rate limit tiers tied to API key type:
  • No API key (browser session): 60 requests/minute
  • Free tier API key: 120 requests/minute
  • Pro tier API key: 600 requests/minute
• Add a tier field to the ApiKey entity
• Return rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• Use Redis for distributed rate limit state (required for multi-instance deployments)
• Fall back to in-memory throttling if Redis is unavailable (development mode)

Redis Integration

• Add @nestjs/cache-manager with Redis store
• Configure Redis connection via environment variables
• Use Redis for both rate limiting and response caching (B-7 analytics cache)

Acceptance Criteria

• All API routes are prefixed with /v1/
• Non-versioned routes redirect or respond with a deprecation notice
• Rate limiting is enforced per-user based on JWT or API key
• Rate limit headers are present on all API responses
• Exceeding the rate limit returns HTTP 429 with retry-after header
• API key tier determines the rate limit
• Redis is used for rate limit state in production
• In-memory fallback works when Redis is unavailable
• Health check includes Redis connectivity status

Context

• Current throttler: @nestjs/throttler configured in apps/backend/src/app.module.ts
• API key entity: apps/backend/src/api-key/api-key.entity.ts
• API key guard: apps/backend/src/api-key/guards/api-key.guard.ts
• Auth guard: apps/backend/src/modules/auth/middleware/auth.guard.ts

Rollout Phase

Phase 5 — Admin & Production Hardening

Points: 200 (Difficult)