@codaijs/keel 0.1.0

package/sails/rate-limiting/README.md

@@ -0,0 +1,145 @@
+# API Rate Limiting Sail
+
+In-memory sliding window rate limiting middleware for Express API routes. No external dependencies or Redis required.
+
+## What this sail adds
+
+### Backend
+- **`src/middleware/rate-limit.ts`** -- Rate limiting middleware factory with preset configurations:
+  - `apiLimiter` -- 100 requests per 15 minutes (general API routes)
+  - `authLimiter` -- 10 requests per 15 minutes (login, signup)
+  - `strictLimiter` -- 5 requests per 15 minutes (password reset, sensitive operations)
+  - `createRateLimiter(options)` -- factory for custom configurations
+- **`src/middleware/rate-limit-store.ts`** -- Store abstraction with in-memory implementation:
+  - `RateLimitStore` interface for swapping storage backends
+  - `MemoryStore` with automatic cleanup of expired entries
+
+### How it works
+
+The middleware uses a **sliding window** algorithm:
+
+1. Each client is identified by their authenticated user ID or IP address
+2. Requests are counted within a configurable time window
+3. When the limit is exceeded the server responds with `429 Too Many Requests`
+4. Standard rate limit headers are set on every response:
+   - `X-RateLimit-Limit` -- maximum requests allowed
+   - `X-RateLimit-Remaining` -- requests remaining in the current window
+   - `X-RateLimit-Reset` -- Unix timestamp when the window resets
+   - `Retry-After` -- seconds until the client can retry (only on 429)
+
+### Environment variables (optional)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RATE_LIMIT_WINDOW_MS` | Window duration in milliseconds | `900000` (15 min) |
+| `RATE_LIMIT_MAX_REQUESTS` | Max requests per window | `100` |
+
+These environment variables override the defaults for `apiLimiter`. The preset `authLimiter` and `strictLimiter` always use their own hardcoded values.
+
+## Setup
+
+### Run the installer
+
+```bash
+npx tsx cli/sails/rate-limiting/install.ts
+```
+
+Or use the CLI:
+
+```bash
+npx @codaijs/keel sail add rate-limiting
+```
+
+The installer will:
+1. Copy the middleware files into your backend
+2. Apply the rate limiter to your chosen routes
+3. Optionally add environment variables for custom defaults
+
+## Usage
+
+### Apply globally
+
+```ts
+import { apiLimiter } from "./middleware/rate-limit.js";
+
+app.use("/api", apiLimiter);
+```
+
+### Apply to specific routes
+
+```ts
+import { authLimiter, strictLimiter } from "./middleware/rate-limit.js";
+
+app.use("/api/auth/login", authLimiter);
+app.use("/api/auth/signup", authLimiter);
+app.use("/api/auth/reset-password", strictLimiter);
+```
+
+### Create a custom limiter
+
+```ts
+import { createRateLimiter } from "./middleware/rate-limit.js";
+
+const uploadLimiter = createRateLimiter({
+  windowMs: 60 * 60 * 1000,  // 1 hour
+  maxRequests: 20,
+  message: "Upload limit exceeded. Try again later.",
+});
+
+app.use("/api/uploads", uploadLimiter);
+```
+
+### Custom key generator
+
+By default clients are identified by user ID (if authenticated) or IP address. You can provide a custom key generator:
+
+```ts
+const limiter = createRateLimiter({
+  keyGenerator: (req) => req.headers["x-api-key"] as string ?? req.ip,
+  maxRequests: 1000,
+});
+```
+
+## Scaling to production
+
+The default `MemoryStore` works well for single-process deployments. For multi-process or distributed environments, implement the `RateLimitStore` interface backed by Redis:
+
+```ts
+import type { RateLimitStore, RateLimitEntry } from "./middleware/rate-limit-store.js";
+
+class RedisStore implements RateLimitStore {
+  constructor(private redis: RedisClient) {}
+
+  async increment(key: string, windowMs: number): Promise<RateLimitEntry> {
+    const rKey = `rl:${key}`;
+    const count = await this.redis.incr(rKey);
+    if (count === 1) {
+      await this.redis.pexpire(rKey, windowMs);
+    }
+    const ttl = await this.redis.pttl(rKey);
+    return { count, resetAt: Date.now() + ttl };
+  }
+
+  async decrement(key: string): Promise<void> {
+    await this.redis.decr(`rl:${key}`);
+  }
+
+  async reset(key: string): Promise<void> {
+    await this.redis.del(`rl:${key}`);
+  }
+}
+```
+
+Then pass it when creating your limiter:
+
+```ts
+const limiter = createRateLimiter({
+  store: new RedisStore(redis),
+});
+```
+
+## Troubleshooting
+
+- **All requests are getting 429**: Check that the `maxRequests` value is appropriate for your traffic. Authenticated users are tracked by user ID, so shared IPs (like offices) should not cause issues for logged-in users.
+- **Rate limits not working behind a proxy**: Make sure your Express app trusts the proxy so that `X-Forwarded-For` is parsed correctly: `app.set("trust proxy", 1)`.
+- **Memory growing**: The `MemoryStore` prunes expired entries every 5 minutes. If you have very high traffic, consider switching to a Redis store.

package/sails/rate-limiting/addon.json

@@ -0,0 +1,20 @@
+{
+  "name": "rate-limiting",
+  "displayName": "API Rate Limiting",
+  "description": "In-memory sliding window rate limiting middleware for API routes. No external dependencies required.",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [],
+  "dependencies": {
+    "backend": {},
+    "frontend": {}
+  },
+  "modifies": {
+    "backend": ["src/index.ts", "src/env.ts"],
+    "frontend": []
+  },
+  "adds": {
+    "backend": ["src/middleware/rate-limit.ts", "src/middleware/rate-limit-store.ts"],
+    "frontend": []
+  }
+}

package/sails/rate-limiting/files/backend/middleware/rate-limit-store.ts

@@ -0,0 +1,104 @@
+/**
+ * Rate Limit Store Abstraction
+ *
+ * Provides an interface and in-memory implementation for rate limit tracking.
+ * This abstraction allows swapping to a Redis-backed store in production
+ * without changing the middleware logic.
+ */
+
+// ---------------------------------------------------------------------------
+// Interface
+// ---------------------------------------------------------------------------
+
+export interface RateLimitEntry {
+  /** Number of requests made in the current window. */
+  count: number;
+  /** Timestamp (ms) when the current window resets. */
+  resetAt: number;
+}
+
+export interface RateLimitStore {
+  /**
+   * Increment the request count for `key` within a window of `windowMs`.
+   * If the key does not exist or the window has expired a new window is
+   * started automatically.
+   */
+  increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+
+  /** Decrement the count for `key` (useful for undoing a counted request). */
+  decrement(key: string): Promise<void>;
+
+  /** Reset (delete) the entry for `key`. */
+  reset(key: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// In-memory implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple in-memory store backed by a `Map`.
+ *
+ * A periodic cleanup timer prunes expired entries every `cleanupIntervalMs`
+ * (default 5 minutes) so the map does not grow unboundedly.
+ */
+export class MemoryStore implements RateLimitStore {
+  private store = new Map<string, RateLimitEntry>();
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(cleanupIntervalMs = 5 * 60 * 1000) {
+    this.cleanupTimer = setInterval(() => {
+      this.prune();
+    }, cleanupIntervalMs);
+
+    // Allow the Node process to exit even if the timer is still active.
+    if (this.cleanupTimer && typeof this.cleanupTimer === "object" && "unref" in this.cleanupTimer) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  async increment(key: string, windowMs: number): Promise<RateLimitEntry> {
+    const now = Date.now();
+    const existing = this.store.get(key);
+
+    if (existing && existing.resetAt > now) {
+      // Window still active — increment.
+      existing.count += 1;
+      return { count: existing.count, resetAt: existing.resetAt };
+    }
+
+    // No entry or window expired — start a fresh window.
+    const entry: RateLimitEntry = { count: 1, resetAt: now + windowMs };
+    this.store.set(key, entry);
+    return { count: 1, resetAt: entry.resetAt };
+  }
+
+  async decrement(key: string): Promise<void> {
+    const entry = this.store.get(key);
+    if (entry && entry.count > 0) {
+      entry.count -= 1;
+    }
+  }
+
+  async reset(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  /** Remove all expired entries from the map. */
+  private prune(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (entry.resetAt <= now) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /** Stop the cleanup timer (useful for tests / graceful shutdown). */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+}

package/sails/rate-limiting/files/backend/middleware/rate-limit.ts

@@ -0,0 +1,137 @@
+/**
+ * Sliding-window rate limiting middleware for Express.
+ *
+ * Uses an in-memory store by default (no Redis required). You can swap in any
+ * implementation of `RateLimitStore` for distributed deployments.
+ *
+ * Usage:
+ *   import { apiLimiter, authLimiter, createRateLimiter } from "./middleware/rate-limit.js";
+ *
+ *   app.use("/api", apiLimiter);              // 100 req / 15 min
+ *   app.use("/api/auth", authLimiter);        // 10 req / 15 min
+ *
+ *   // Custom:
+ *   app.use("/api/special", createRateLimiter({ windowMs: 60_000, maxRequests: 5 }));
+ */
+
+import type { Request, Response, NextFunction } from "express";
+import { MemoryStore } from "./rate-limit-store.js";
+import type { RateLimitStore } from "./rate-limit-store.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RateLimitOptions {
+  /** Time window in milliseconds. Default: 15 minutes. */
+  windowMs?: number;
+  /** Maximum number of requests allowed in the window. Default: 100. */
+  maxRequests?: number;
+  /** Extract the key used to identify the client. Defaults to IP, or userId when authenticated. */
+  keyGenerator?: (req: Request) => string;
+  /** Store implementation. Defaults to `MemoryStore`. */
+  store?: RateLimitStore;
+  /** Custom message returned when the limit is exceeded. */
+  message?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults from environment (optional overrides)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_WINDOW_MS = Number(process.env.RATE_LIMIT_WINDOW_MS) || 15 * 60 * 1000;
+const DEFAULT_MAX_REQUESTS = Number(process.env.RATE_LIMIT_MAX_REQUESTS) || 100;
+
+// ---------------------------------------------------------------------------
+// Shared store — one MemoryStore instance for the entire process
+// ---------------------------------------------------------------------------
+
+const sharedStore = new MemoryStore();
+
+// ---------------------------------------------------------------------------
+// Key generator
+// ---------------------------------------------------------------------------
+
+function defaultKeyGenerator(req: Request): string {
+  // Prefer the authenticated user id when available so that rate limits are
+  // per-user rather than per-IP for logged-in users.
+  const userId = (req as Record<string, unknown>).user
+    ? ((req as Record<string, unknown>).user as { id?: string })?.id
+    : undefined;
+
+  if (userId) return `user:${userId}`;
+
+  // Fall back to IP address.
+  const forwarded = req.headers["x-forwarded-for"];
+  const ip =
+    typeof forwarded === "string"
+      ? forwarded.split(",")[0].trim()
+      : req.socket.remoteAddress ?? "unknown";
+
+  return `ip:${ip}`;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a rate-limiting middleware with the given options.
+ */
+export function createRateLimiter(options: RateLimitOptions = {}) {
+  const {
+    windowMs = DEFAULT_WINDOW_MS,
+    maxRequests = DEFAULT_MAX_REQUESTS,
+    keyGenerator = defaultKeyGenerator,
+    store = sharedStore,
+    message = "Too many requests, please try again later.",
+  } = options;
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const key = keyGenerator(req);
+
+    try {
+      const { count, resetAt } = await store.increment(key, windowMs);
+
+      // Always set informational headers.
+      res.setHeader("X-RateLimit-Limit", String(maxRequests));
+      res.setHeader("X-RateLimit-Remaining", String(Math.max(0, maxRequests - count)));
+      res.setHeader("X-RateLimit-Reset", String(Math.ceil(resetAt / 1000)));
+
+      if (count > maxRequests) {
+        const retryAfterSeconds = Math.ceil((resetAt - Date.now()) / 1000);
+        res.setHeader("Retry-After", String(retryAfterSeconds));
+        res.status(429).json({ error: message });
+        return;
+      }
+
+      next();
+    } catch (err) {
+      // If the store fails we let the request through rather than blocking.
+      console.error("[rate-limit] Store error:", err);
+      next();
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Preset limiters
+// ---------------------------------------------------------------------------
+
+/** General API limiter — 100 requests per 15 minutes. */
+export const apiLimiter = createRateLimiter({
+  windowMs: DEFAULT_WINDOW_MS,
+  maxRequests: DEFAULT_MAX_REQUESTS,
+});
+
+/** Auth limiter — 10 requests per 15 minutes (login, signup). */
+export const authLimiter = createRateLimiter({
+  windowMs: 15 * 60 * 1000,
+  maxRequests: 10,
+});
+
+/** Strict limiter — 5 requests per 15 minutes (password reset, sensitive ops). */
+export const strictLimiter = createRateLimiter({
+  windowMs: 15 * 60 * 1000,
+  maxRequests: 5,
+});