Merge pull request #246 from wheval/fix/issues-116

fix(security): add Redis-backed tiered rate limiting (#116)

Author: Nathydre

PR_DESCRIPTION.md

@@ -1,4 +1,45 @@
 ## Summary
+
+Implements **distributed rate limiting** for the tiered API limiter using **Redis** when `REDIS_URL` is configured. This removes the bypass where limits lived only in process memory (restart or horizontal scaling cleared or split enforcement).
+
+## Purpose / Motivation
+
+Issue [#116](https://github.com/nathydre21/wata-board/issues/116): in-memory rate limiting could be bypassed by restarting the server or routing traffic across multiple instances. Production deployments need a shared store so limits are consistent and durable across replicas.
+
+## Changes Made
+
+- **`TieredRateLimiter`** (`backend/src/middleware/rateLimiter.ts`):
+  - When Redis is enabled (`REDIS_URL`), uses Redis sorted sets for a sliding window of request timestamps and a separate counter key for queue depth.
+  - Uses **Lua scripts** so check/consume and status reads are atomic and safe under concurrency.
+  - Keeps the previous **in-memory** behavior when Redis is not configured (e.g. local dev/tests without Redis).
+  - Exposes `resetTime` as ISO strings aligned with `TierRateLimitStatus`.
+  - Middleware is **async**, forwards limiter errors via `next(error)` instead of failing silently.
+- **Monitoring** (`backend/src/routes/monitoring.ts`): `GET /api/monitoring/rate-limit-status` awaits async `getStatus()`.
+
+## Operational notes
+
+- Set **`REDIS_URL`** in environments where multiple app instances run or restarts must not reset limits (same variable as existing Redis pub/sub for WebSockets).
+- Keys use the prefix `rl:tier:requests:` and `rl:tier:queue:` per user id derived from `x-user-id` or IP.
+
+## How to Test
+
+1. **With Redis**: Point `REDIS_URL` at a Redis instance, start the API, and hit `/api/payment` (or any route behind `tieredRateLimiter`) until `429` / queued responses; repeat from another client or after restart — counts should **continue** from shared state, not reset per process.
+2. **Without Redis**: Unset `REDIS_URL` — behavior should match prior in-memory limiting for a single process.
+3. **Monitoring**: `GET /api/monitoring/rate-limit-status` with `x-user-id` should return tier + limit fields without throwing.
+
+## Breaking Changes
+
+None intended. Response shapes and HTTP status codes for rate limit / queue paths are unchanged; Redis is additive behind configuration.
+
+## Related Issues
+
+Closes nathydre21/wata-board#116
+
+## Checklist
+
+- [x] Implementation scoped to tiered limiter + monitoring route
+- [ ] CI / full backend build (repo may have pre-existing TS issues outside this change)
+- [ ] Redis connectivity verified in staging
 This PR resolves three related reliability issues in one delivery:
 
 - `#120` Missing Error Recovery Mechanism

backend/src/middleware/rateLimiter.ts

@@ -12,6 +12,7 @@ import { UserTier, TierRateLimitStatus } from '../types/userTier';
 import { getRateLimitForTier } from '../config/rateLimits';
 import { userTierService } from '../services/userTierService';
 import logger from '../utils/logger';
+import { getPublisher, isRedisEnabled } from '../utils/redis';
 
 interface WindowEntry {
   timestamps: number[];
@@ -21,8 +22,11 @@ interface WindowEntry {
 export class TieredRateLimiter {
   private windows: Map<string, WindowEntry> = new Map();
   private cleanupInterval: NodeJS.Timeout;
+  private redisEnabled: boolean;
 
   constructor() {
+    this.redisEnabled = isRedisEnabled();
+
     // Prune stale entries every 2 minutes
     this.cleanupInterval = setInterval(() => this.cleanup(), 2 * 60 * 1000);
   }
@@ -32,12 +36,16 @@ export class TieredRateLimiter {
   /**
    * Check (and consume) one request slot for a user.
    */
-  checkLimit(userId: string): TierRateLimitStatus {
+  async checkLimit(userId: string): Promise<TierRateLimitStatus> {
     const tier = userTierService.getUserTier(userId);
     const config = getRateLimitForTier(tier);
     const now = Date.now();
     const windowStart = now - config.windowMs;
 
+    if (this.redisEnabled) {
+      return this.checkLimitRedis(userId, tier, config, now);
+    }
+
     let entry = this.windows.get(userId);
     if (!entry) {
       entry = { timestamps: [], queueCount: 0 };
@@ -94,10 +102,15 @@ export class TieredRateLimiter {
   /**
    * Read-only status check (does NOT consume a request slot).
    */
-  getStatus(userId: string): TierRateLimitStatus {
+  async getStatus(userId: string): Promise<TierRateLimitStatus> {
     const tier = userTierService.getUserTier(userId);
     const config = getRateLimitForTier(tier);
     const now = Date.now();
+
+    if (this.redisEnabled) {
+      return this.getStatusRedis(userId, tier, config, now);
+    }
+
     const windowStart = now - config.windowMs;
 
     const entry = this.windows.get(userId);
@@ -124,6 +137,12 @@ export class TieredRateLimiter {
   // ── Express middleware factory ─────────────────────────────
 
   middleware() {
+    return async (req: Request, res: Response, next: NextFunction) => {
+      try {
+        const userId =
+          (req.headers['x-user-id'] as string) || req.ip || 'unknown';
+        const status = await this.checkLimit(userId);
+        const resetAtMs = Date.parse(status.resetTime);
     return (req: Request, res: Response, next: NextFunction) => {
       const userId =
         (req.headers['x-user-id'] as string) || req.ip || 'unknown';
@@ -150,26 +169,55 @@ export class TieredRateLimiter {
         });
       }
 
-      if (status.queued) {
-        logger.info('Request queued', {
-          userId,
-          tier: status.tier,
-          position: status.queuePosition,
-        });
-        return res.status(202).json({
-          message: 'Request queued',
-          queuePosition: status.queuePosition,
-          tier: status.tier,
-        });
-      }
+        // Always expose rate-limit headers
+        res.set('X-RateLimit-Limit', String(status.limit));
+        res.set('X-RateLimit-Remaining', String(status.remainingRequests));
+        res.set(
+          'X-RateLimit-Reset',
+          String(Math.ceil(resetAtMs / 1000)),
+        );
+        res.set('X-RateLimit-Tier', status.tier);
+
+        if (!status.allowed && !status.queued) {
+          logger.warn('Rate limit exceeded', { userId, tier: status.tier });
+          return res.status(429).json({
+            error: 'Rate limit exceeded',
+            tier: status.tier,
+            retryAfter: Math.ceil((resetAtMs - Date.now()) / 1000),
+            limit: status.limit,
+          });
+        }
 
+        if (status.queued) {
+          logger.info('Request queued', {
+            userId,
+            tier: status.tier,
+            position: status.queuePosition,
+          });
+          return res.status(202).json({
+            message: 'Request queued',
+            queuePosition: status.queuePosition,
+            tier: status.tier,
+          });
+        }
+
+        return next();
+      } catch (error) {
+        logger.error('Rate limiter middleware failure', { error });
+        return next(error);
+      }
       return next();
     };
   }
 
   // ── Helpers ────────────────────────────────────────────────
 
   private cleanup() {
+    if (this.redisEnabled) {
+      // Redis key expiry handles cleanup in distributed mode.
+      return;
+    }
+
     const now = Date.now();
     for (const [userId, entry] of this.windows.entries()) {
       entry.timestamps = entry.timestamps.filter(
@@ -184,6 +232,162 @@ export class TieredRateLimiter {
   destroy() {
     clearInterval(this.cleanupInterval);
   }
+
+  private buildRedisKeys(userId: string): { requestsKey: string; queueKey: string } {
+    return {
+      requestsKey: `rl:tier:requests:${userId}`,
+      queueKey: `rl:tier:queue:${userId}`,
+    };
+  }
+
+  private toStatus(
+    tier: UserTier,
+    allowed: number,
+    remainingRequests: number,
+    resetTimeMs: number,
+    queued: number,
+    queuePosition: number,
+    limit: number,
+  ): TierRateLimitStatus {
+    return {
+      tier,
+      allowed: allowed === 1,
+      remainingRequests,
+      resetTime: new Date(resetTimeMs).toISOString(),
+      queued: queued === 1,
+      queuePosition: queuePosition > 0 ? queuePosition : undefined,
+      limit,
+    };
+  }
+
+  private async checkLimitRedis(
+    userId: string,
+    tier: UserTier,
+    config: { windowMs: number; maxRequests: number; queueSize: number },
+    now: number,
+  ): Promise<TierRateLimitStatus> {
+    const client = getPublisher();
+    const { requestsKey, queueKey } = this.buildRedisKeys(userId);
+    const member = `${now}-${Math.random().toString(36).slice(2, 10)}`;
+
+    const script = `
+      local requestsKey = KEYS[1]
+      local queueKey = KEYS[2]
+      local now = tonumber(ARGV[1])
+      local windowMs = tonumber(ARGV[2])
+      local maxRequests = tonumber(ARGV[3])
+      local queueSize = tonumber(ARGV[4])
+      local member = ARGV[5]
+      local windowStart = now - windowMs
+
+      redis.call('ZREMRANGEBYSCORE', requestsKey, '-inf', windowStart)
+      local count = redis.call('ZCARD', requestsKey)
+
+      if count < maxRequests then
+        redis.call('ZADD', requestsKey, now, member)
+        redis.call('PEXPIRE', requestsKey, windowMs)
+        local minData = redis.call('ZRANGE', requestsKey, 0, 0, 'WITHSCORES')
+        local reset = now + windowMs
+        if minData[2] then
+          reset = tonumber(minData[2]) + windowMs
+        end
+        local remaining = maxRequests - count - 1
+        return {1, remaining, reset, 0, 0, maxRequests}
+      end
+
+      local queueCount = redis.call('INCR', queueKey)
+      if queueCount == 1 then
+        redis.call('PEXPIRE', queueKey, windowMs)
+      end
+
+      local minData = redis.call('ZRANGE', requestsKey, 0, 0, 'WITHSCORES')
+      local reset = now + windowMs
+      if minData[2] then
+        reset = tonumber(minData[2]) + windowMs
+      end
+
+      if queueCount <= queueSize then
+        return {0, 0, reset, 1, queueCount, maxRequests}
+      end
+
+      redis.call('DECR', queueKey)
+      return {0, 0, reset, 0, 0, maxRequests}
+    `;
+
+    const result = (await client.eval(
+      script,
+      2,
+      requestsKey,
+      queueKey,
+      String(now),
+      String(config.windowMs),
+      String(config.maxRequests),
+      String(config.queueSize),
+      member,
+    )) as [number, number, number, number, number, number];
+
+    return this.toStatus(
+      tier,
+      Number(result[0]),
+      Number(result[1]),
+      Number(result[2]),
+      Number(result[3]),
+      Number(result[4]),
+      Number(result[5]),
+    );
+  }
+
+  private async getStatusRedis(
+    userId: string,
+    tier: UserTier,
+    config: { windowMs: number; maxRequests: number; queueSize: number },
+    now: number,
+  ): Promise<TierRateLimitStatus> {
+    const client = getPublisher();
+    const { requestsKey } = this.buildRedisKeys(userId);
+
+    const script = `
+      local requestsKey = KEYS[1]
+      local now = tonumber(ARGV[1])
+      local windowMs = tonumber(ARGV[2])
+      local maxRequests = tonumber(ARGV[3])
+      local windowStart = now - windowMs
+
+      redis.call('ZREMRANGEBYSCORE', requestsKey, '-inf', windowStart)
+      local count = redis.call('ZCARD', requestsKey)
+      local minData = redis.call('ZRANGE', requestsKey, 0, 0, 'WITHSCORES')
+      local reset = now + windowMs
+      if minData[2] then
+        reset = tonumber(minData[2]) + windowMs
+      end
+
+      local remaining = maxRequests - count
+      if remaining < 0 then remaining = 0 end
+      local allowed = 0
+      if remaining > 0 then allowed = 1 end
+
+      return {allowed, remaining, reset, maxRequests}
+    `;
+
+    const result = (await client.eval(
+      script,
+      1,
+      requestsKey,
+      String(now),
+      String(config.windowMs),
+      String(config.maxRequests),
+    )) as [number, number, number, number];
+
+    return this.toStatus(
+      tier,
+      Number(result[0]),
+      Number(result[1]),
+      Number(result[2]),
+      0,
+      0,
+      Number(result[3]),
+    );
+  }
 }
 
 /** Singleton instance */

backend/src/routes/monitoring.ts

@@ -36,10 +36,10 @@ router.get('/dashboard', (_req: Request, res: Response) => {
 });
 
 /** GET /api/monitoring/rate-limit-status */
-router.get('/rate-limit-status', (req: Request, res: Response) => {
+router.get('/rate-limit-status', async (req: Request, res: Response) => {
   const rawId = (req.headers['x-user-id'] as string) || req.ip || 'unknown';
   const userId = sanitizeAlphanumeric(rawId, 100) || 'unknown';
-  const status = tieredRateLimiter.getStatus(userId);
+  const status = await tieredRateLimiter.getStatus(userId);
   const tierInfo = userTierService.getUserTierInfo(userId);
   res.json({ ...status, ...tierInfo });
 });