import { createHash } from "crypto"; import type { IRateLimiterStoreOptions } from "rate-limiter-flexible"; import { RateLimiterRedis, RateLimiterMemory } from "rate-limiter-flexible"; import { toError } from "@shared/utils/error"; import env from "@server/env"; import Logger from "@server/logging/Logger"; import Redis from "@server/storage/redis"; /** * Manages rate limiters for API endpoints, backed by Redis with an in-memory * insurance limiter as a fallback. */ export default class RateLimiter { constructor() { throw Error(`Cannot instantiate class!`); } static readonly RATE_LIMITER_REDIS_KEY_PREFIX = "rl"; static readonly TOKEN_CACHE_KEY_PREFIX = "rl:tok:"; static readonly TOKEN_CACHE_TTL_SECONDS = 3600; /** Distinguishes credential-derived identifiers from user ids and IPs. */ static readonly CREDENTIAL_IDENTIFIER_PREFIX = "cred:"; static readonly rateLimiterMap = new Map(); static readonly insuranceRateLimiter = new RateLimiterMemory({ points: env.RATE_LIMITER_REQUESTS, duration: env.RATE_LIMITER_DURATION_WINDOW, }); private static _defaultRateLimiter: RateLimiterRedis | undefined; /** * The default rate limiter, used for any path without a specific limiter * registered. */ static get defaultRateLimiter(): RateLimiterRedis { if (!this._defaultRateLimiter) { this._defaultRateLimiter = new RateLimiterRedis({ storeClient: Redis.ephemeralClient, points: env.RATE_LIMITER_REQUESTS, duration: env.RATE_LIMITER_DURATION_WINDOW, keyPrefix: this.RATE_LIMITER_REDIS_KEY_PREFIX, insuranceLimiter: this.insuranceRateLimiter, }); } return this._defaultRateLimiter; } /** * Normalizes a request path into the key that identifies its rate limiter. * The router matches paths case-insensitively and with an optional trailing * slash, so every one of those variants must collapse onto a single key. * * @param path the request path to normalize. * @returns the normalized path. */ static normalizePath(path: string): string { const lowercased = path.toLowerCase(); return lowercased.length > 1 && lowercased.endsWith("/") ? lowercased.slice(0, -1) : lowercased; } /** * Returns the rate limiter registered for a path, falling back to the * default rate limiter. The path is normalized before lookup. * * @param path the request path to look up. * @returns the rate limiter for the path. */ static getRateLimiter(path: string): RateLimiterRedis { return ( this.rateLimiterMap.get(this.normalizePath(path)) || this.defaultRateLimiter ); } /** * Registers a rate limiter with a custom configuration for a path. The path * is normalized before registration. * * @param path the request path to register the rate limiter for. * @param config the rate limiter configuration. */ static setRateLimiter(path: string, config: IRateLimiterStoreOptions): void { const rateLimiter = new RateLimiterRedis(config); this.rateLimiterMap.set(this.normalizePath(path), rateLimiter); } /** * Checks whether a custom rate limiter is registered for a path. The path is * normalized before lookup. * * @param path the request path to check. * @returns true if a custom rate limiter is registered. */ static hasRateLimiter(path: string): boolean { return this.rateLimiterMap.has(this.normalizePath(path)); } /** * Derives a stable rate limiting identifier for a long-lived credential such * as an API key or OAuth access token. The credential itself is never used * as an identifier so that it does not reach the rate limiter store. * * @param token The credential presented on the request. * @returns An identifier scoped to the credential. */ static identifierForCredential(token: string): string { return `${this.CREDENTIAL_IDENTIFIER_PREFIX}${this.hashToken(token)}`; } /** * Caches the user id associated with a verified authentication token so that * subsequent requests can be keyed by user without re-validating the token. * Errors are swallowed — a failed cache write just means the next request * falls back to IP-based keying. * * @param token The authentication token that was just verified. * @param userId The id of the user the token belongs to. */ static async cacheUserForToken(token: string, userId: string): Promise { try { await Redis.ephemeralClient.set( this.tokenCacheKey(token), userId, "EX", this.TOKEN_CACHE_TTL_SECONDS ); } catch (err) { Logger.warn("Failed to cache user for rate limiter token", toError(err)); } } /** * Looks up the cached user id for a previously verified token. Returns null * on cache miss or Redis error. * * @param token The authentication token presented on the current request. * @returns The associated user id, or null if unknown. */ static async getCachedUserIdForToken(token: string): Promise { try { return await Redis.ephemeralClient.get(this.tokenCacheKey(token)); } catch (err) { Logger.warn( "Failed to read cached user for rate limiter token", toError(err) ); return null; } } /** * Removes the cached user id for a token, for example on logout so that a * revoked token immediately stops keying rate limits per user. * * @param token The authentication token being invalidated. */ static async clearCachedToken(token: string): Promise { try { await Redis.ephemeralClient.del(this.tokenCacheKey(token)); } catch (err) { Logger.warn("Failed to clear cached rate limiter token", toError(err)); } } private static tokenCacheKey(token: string): string { return `${this.TOKEN_CACHE_KEY_PREFIX}${this.hashToken(token)}`; } private static hashToken(token: string): string { return createHash("sha256").update(token).digest("hex"); } } /** * Reusable configuration for rate limiter middleware. */ export const RateLimiterStrategy = { /** Allows five requests per minute, per IP address */ FivePerMinute: { duration: 60, requests: 5, }, /** Allows ten requests per minute, per IP address */ TenPerMinute: { duration: 60, requests: 10, }, /** Allows twenty five requests per minute, per IP address */ TwentyFivePerMinute: { duration: 60, requests: 25, }, /** Allows one hundred requests per minute, per IP address */ OneHundredPerMinute: { duration: 60, requests: 100, }, /** Allows one thousand requests per hour, per IP address */ OneThousandPerHour: { duration: 3600, requests: 1000, }, /** Allows one hunred requests per hour, per IP address */ OneHundredPerHour: { duration: 3600, requests: 100, }, /** Allows fifty requests per hour, per IP address */ FiftyPerHour: { duration: 3600, requests: 50, }, /** Allows ten requests per hour, per IP address */ TenPerHour: { duration: 3600, requests: 10, }, /** Allows five requests per hour, per IP address */ FivePerHour: { duration: 3600, requests: 5, }, };