rate-limit.guard.ts

rate-limit.guard.tsapps/api/src/common/guards/rate-limit.guard.tsraw ← guards4,482 B← Back to the app
1import { Inject, CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
2import type { Request, Response } from "express";
3import { loadEnv } from "../../config/env.js";
4import { ApiError } from "../errors.js";
5import { logger } from "../logger.js";
6import { RedisService } from "../redis.service.js";
7import type { AuthContext } from "../types.js";
8 
9/**
10 * Redis sliding-window rate limit guard (per credential × route class).
11 *
12 * Bucket key: `rl:<class>:<subject>` where subject is the authenticated
13 * user id, the API key id, or the client IP; class is "auth" for
14 * /auth/* and "api" otherwise. Limits come from env:
15 * RATE_LIMIT_AUTH (default 10 / min) and RATE_LIMIT_API (default 100 / min)
16 * for user/IP callers. TASK-0127: an API key gets its OWN window —
17 * the key's explicit `rateLimit` (carried on the auth context), else
18 * RATE_LIMIT_API_KEY (default 600 / min, docs/api/authentication.md §11) —
19 * and its bucket is keyed by the KEY id.
20 *
21 * Responses carry X-RateLimit-Limit/Remaining/Reset; over the limit →
22 * 429 { code: "RATE_LIMITED" } + Retry-After. If Redis is down the limit
23 * degrades OPEN (availability over strictness) and logs once per minute.
24 */
25const WINDOW_MS = 60_000;
26 
27@Injectable()
28export class RateLimitGuard implements CanActivate {
29  private lastRedisWarn = 0;
30 
31  constructor(@Inject(RedisService) private readonly redis: RedisService) {}
32 
33  async canActivate(context: ExecutionContext): Promise<boolean> {
34    const req = context.switchToHttp().getRequest<Request>();
35    const res = context.switchToHttp().getResponse<Response>();
36    const auth: AuthContext | undefined = req.auth;
37 
38    // The internal service surface (TASK-0092 slice 2) is trusted +
39    // high-frequency (a flush per dirty room, a hydration per cold room) —
40    // it must not count against the per-client window. The room's own rate
41    // limits already gate the upstream WS clients.
42    if (req.path.startsWith("/internal/")) return true;
43 
44    const cls = req.path.startsWith("/api/v1/auth/") ? "auth" : "api";
45    // TASK-0127: an API key gets its OWN window, per the published contract
46    // (docs/api/authentication.md §11: "Per API key: 600 req/min, or the
47    // key's rateLimit if set"): the key's explicit `rateLimit` (resolved by
48    // the AuthGuard, carried on the auth context — no second query) wins,
49    // else the key-specific default (RATE_LIMIT_API_KEY, 600). User/IP
50    // callers keep the generic windows (RATE_LIMIT_AUTH / RATE_LIMIT_API).
51    const envLimit = cls === "auth" ? loadEnv().RATE_LIMIT_AUTH : loadEnv().RATE_LIMIT_API;
52    const keyLimit = auth?.kind === "api" ? auth.rateLimit : undefined;
53    const limit =
54      auth?.kind === "api" ? keyLimit ?? loadEnv().RATE_LIMIT_API_KEY : envLimit;
55    const subject = auth?.apiKeyId ?? auth?.userId ?? req.ip ?? "unknown";
56    const key = `rl:${cls}:${subject}`;
57 
58    let count: number;
59    try {
60      const now = Date.now();
61      const pipe = this.redis.getRedis().pipeline();
62      pipe.zremrangebyscore(key, 0, now - WINDOW_MS);
63      pipe.zadd(key, now, `${now}:${Math.random().toString(36).slice(2)}`);
64      pipe.zcard(key);
65      pipe.pexpire(key, WINDOW_MS);
66      const results = await pipe.exec();
67      const cardResult = results?.[2]?.[1];
68      count = typeof cardResult === "number" ? cardResult : 1;
69    } catch (err) {
70      if (Date.now() - this.lastRedisWarn > 60_000) {
71        this.lastRedisWarn = Date.now();
72        logger.warn(`rate limiter degraded (redis unavailable): ${(err as Error).message}`);
73      }
74      // Fail-open, but still advertise the configured limit (docs §11:
75      // every public response carries the headers).
76      res.setHeader("X-RateLimit-Limit", String(limit));
77      res.setHeader("X-RateLimit-Remaining", "0");
78      res.setHeader("X-RateLimit-Reset", String(Math.ceil((Date.now() + WINDOW_MS) / 1000)));
79      return true;
80    }
81 
82    const remaining = Math.max(0, limit - count);
83    const reset = Math.ceil((Date.now() + WINDOW_MS) / 1000);
84    res.setHeader("X-RateLimit-Limit", String(limit));
85    res.setHeader("X-RateLimit-Remaining", String(remaining));
86    res.setHeader("X-RateLimit-Reset", String(reset));
87 
88    if (count > limit) {
89      const retryAfter = Math.ceil(WINDOW_MS / 1000);
90      res.setHeader("Retry-After", String(retryAfter));
91      throw new ApiError("RATE_LIMITED", 429, "Too many requests.", [
92        { retryAfterSeconds: retryAfter }
93      ]);
94    }
95    return true;
96  }
97}
98