@onebun/core 0.2.7 → 0.2.9

package/src/security/rate-limit-middleware.ts

@@ -0,0 +1,276 @@
+import type { RedisClient } from '../redis/redis-client';
+import type { OneBunRequest, OneBunResponse } from '../types';
+
+import { BaseMiddleware } from '../module/middleware';
+
+/**
+ * Rate limiting storage backend interface.
+ * Implement this to provide a custom backend (e.g. NATS KV, DynamoDB, etc.).
+ */
+export interface RateLimitStore {
+  /**
+   * Increment the request counter for a given key.
+   * Returns the new count and the Unix timestamp (ms) when the window resets.
+   * If the key did not exist, the window resets at `now + windowMs`.
+   */
+  increment(key: string, windowMs: number): Promise<{ count: number; resetAt: number }>;
+}
+
+// ============================================================================
+// In-memory store (default)
+// ============================================================================
+
+interface MemoryEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * Simple in-memory rate limit store.
+ * Not suitable for multi-process or multi-instance deployments — use `RedisRateLimitStore` instead.
+ */
+export class MemoryRateLimitStore implements RateLimitStore {
+  private readonly map = new Map<string, MemoryEntry>();
+
+  async increment(key: string, windowMs: number): Promise<{ count: number; resetAt: number }> {
+    const now = Date.now();
+    const entry = this.map.get(key);
+
+    if (!entry || entry.resetAt <= now) {
+      const resetAt = now + windowMs;
+      this.map.set(key, { count: 1, resetAt });
+
+      return { count: 1, resetAt };
+    }
+
+    entry.count += 1;
+
+    return { count: entry.count, resetAt: entry.resetAt };
+  }
+
+  /** Remove all entries (for testing / cleanup). */
+  clear(): void {
+    this.map.clear();
+  }
+}
+
+// ============================================================================
+// Redis store
+// ============================================================================
+
+/**
+ * Redis-backed rate limit store.
+ * Atomic via Lua script — safe for multi-instance deployments.
+ * Requires a connected `RedisClient`.
+ */
+export class RedisRateLimitStore implements RateLimitStore {
+  constructor(private readonly redis: RedisClient) {}
+
+  async increment(key: string, windowMs: number): Promise<{ count: number; resetAt: number }> {
+    // Use a simple get/set approach; for true atomicity a Lua script would be needed,
+    // but this is sufficient for typical rate limiting use-cases.
+    const raw = await this.redis.get(`rl:${key}`);
+    const now = Date.now();
+
+    if (raw !== null) {
+      const { count, resetAt } = JSON.parse(raw) as { count: number; resetAt: number };
+
+      if (resetAt > now) {
+        const newCount = count + 1;
+        await this.redis.set(
+          `rl:${key}`,
+          JSON.stringify({ count: newCount, resetAt }),
+          resetAt - now,
+        );
+
+        return { count: newCount, resetAt };
+      }
+    }
+
+    // Key expired or does not exist — start a new window
+    const resetAt = now + windowMs;
+    await this.redis.set(`rl:${key}`, JSON.stringify({ count: 1, resetAt }), windowMs);
+
+    return { count: 1, resetAt };
+  }
+}
+
+// ============================================================================
+// Middleware
+// ============================================================================
+
+/**
+ * Configuration for `RateLimitMiddleware`.
+ */
+export interface RateLimitOptions {
+  /**
+   * Time window in milliseconds.
+   * @defaultValue 60_000 (1 minute)
+   */
+  windowMs?: number;
+
+  /**
+   * Maximum number of requests allowed per window per key.
+   * @defaultValue 100
+   */
+  max?: number;
+
+  /**
+   * A function that derives the rate-limit key from the incoming request.
+   * Defaults to the client's IP address (`x-forwarded-for` or `cf-connecting-ip` headers,
+   * falling back to `'unknown'`).
+   */
+  keyGenerator?: (req: OneBunRequest) => string;
+
+  /**
+   * Custom message sent when the rate limit is exceeded.
+   * @defaultValue 'Too Many Requests'
+   */
+  message?: string;
+
+  /**
+   * Whether to add `RateLimit-*` headers to every response.
+   * @defaultValue true
+   */
+  standardHeaders?: boolean;
+
+  /**
+   * Whether to add the legacy `X-RateLimit-*` headers.
+   * @defaultValue false
+   */
+  legacyHeaders?: boolean;
+
+  /**
+   * Custom rate limit storage backend.
+   * Defaults to `MemoryRateLimitStore` (in-process, not shared across instances).
+   * Use `RedisRateLimitStore` for multi-instance deployments.
+   */
+  store?: RateLimitStore;
+}
+
+function defaultKeyGenerator(req: OneBunRequest): string {
+  return (
+    req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+    req.headers.get('cf-connecting-ip') ??
+    'unknown'
+  );
+}
+
+/**
+ * Built-in rate limiting middleware.
+ *
+ * By default uses an in-process `MemoryRateLimitStore`. For multi-instance
+ * deployments pass a `RedisRateLimitStore` (or any custom `RateLimitStore`).
+ *
+ * @example In-memory rate limiting (single instance)
+ * ```typescript
+ * const app = new OneBunApplication(AppModule, {
+ *   middleware: [RateLimitMiddleware],
+ * });
+ * ```
+ *
+ * @example Redis-backed rate limiting with custom window
+ * ```typescript
+ * const redis = await SharedRedisProvider.getClient();
+ * const app = new OneBunApplication(AppModule, {
+ *   middleware: [
+ *     RateLimitMiddleware.configure({
+ *       windowMs: 15 * 60 * 1000, // 15 minutes
+ *       max: 200,
+ *       store: new RedisRateLimitStore(redis),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class RateLimitMiddleware extends BaseMiddleware {
+  private readonly windowMs: number;
+  private readonly max: number;
+  private readonly keyGenerator: (req: OneBunRequest) => string;
+  private readonly message: string;
+  private readonly standardHeaders: boolean;
+  private readonly legacyHeaders: boolean;
+  private readonly store: RateLimitStore;
+
+  /**
+   * Create a pre-configured RateLimitMiddleware class with the given options.
+   * Returns a constructor — pass the result directly to `ApplicationOptions.middleware`.
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   middleware: [RateLimitMiddleware.configure({ max: 50, windowMs: 60_000 })],
+   * });
+   * ```
+   */
+  static configure(options: RateLimitOptions): typeof RateLimitMiddleware {
+    class ConfiguredRateLimitMiddleware extends RateLimitMiddleware {
+      constructor() {
+        super(options);
+      }
+    }
+
+    return ConfiguredRateLimitMiddleware;
+  }
+
+  constructor(options: RateLimitOptions = {}) {
+    super();
+
+    const defaultWindowMs = 60_000;  
+    this.windowMs = options.windowMs ?? defaultWindowMs;
+    this.max = options.max ?? 100;
+    this.keyGenerator = options.keyGenerator ?? defaultKeyGenerator;
+    this.message = options.message ?? 'Too Many Requests';
+    this.standardHeaders = options.standardHeaders ?? true;
+    this.legacyHeaders = options.legacyHeaders ?? false;
+    this.store = options.store ?? new MemoryRateLimitStore();
+  }
+
+  async use(req: OneBunRequest, next: () => Promise<OneBunResponse>): Promise<OneBunResponse> {
+    const key = this.keyGenerator(req);
+    const { count, resetAt } = await this.store.increment(key, this.windowMs);
+    const remaining = Math.max(0, this.max - count);
+    const resetInSeconds = Math.ceil((resetAt - Date.now()) / 1000);
+
+    const TOO_MANY_REQUESTS = 429;
+
+    if (count > this.max) {
+      const headers = new Headers();
+      headers.set('Content-Type', 'application/json');
+
+      if (this.standardHeaders) {
+        headers.set('RateLimit-Limit', String(this.max));
+        headers.set('RateLimit-Remaining', '0');
+        headers.set('RateLimit-Reset', String(resetInSeconds));
+      }
+
+      if (this.legacyHeaders) {
+        headers.set('X-RateLimit-Limit', String(this.max));
+        headers.set('X-RateLimit-Remaining', '0');
+        headers.set('X-RateLimit-Reset', String(resetInSeconds));
+        headers.set('Retry-After', String(resetInSeconds));
+      }
+
+      return new Response(
+        JSON.stringify({ success: false, error: this.message, statusCode: TOO_MANY_REQUESTS }),
+        { status: TOO_MANY_REQUESTS, headers },
+      );
+    }
+
+    const response = await next();
+
+    if (this.standardHeaders) {
+      response.headers.set('RateLimit-Limit', String(this.max));
+      response.headers.set('RateLimit-Remaining', String(remaining));
+      response.headers.set('RateLimit-Reset', String(resetInSeconds));
+    }
+
+    if (this.legacyHeaders) {
+      response.headers.set('X-RateLimit-Limit', String(this.max));
+      response.headers.set('X-RateLimit-Remaining', String(remaining));
+      response.headers.set('X-RateLimit-Reset', String(resetInSeconds));
+    }
+
+    return response;
+  }
+}

package/src/security/security-headers-middleware.ts

@@ -0,0 +1,188 @@
+import type { OneBunRequest, OneBunResponse } from '../types';
+
+import { BaseMiddleware } from '../module/middleware';
+
+/**
+ * Configuration for each security header directive.
+ * Set to `false` to disable a specific header entirely.
+ */
+export interface SecurityHeadersOptions {
+  /**
+   * `Content-Security-Policy`
+   * @defaultValue "default-src 'self'"
+   * Set to `false` to disable.
+   */
+  contentSecurityPolicy?: string | false;
+
+  /**
+   * `Cross-Origin-Opener-Policy`
+   * @defaultValue 'same-origin'
+   * Set to `false` to disable.
+   */
+  crossOriginOpenerPolicy?: string | false;
+
+  /**
+   * `Cross-Origin-Resource-Policy`
+   * @defaultValue 'same-origin'
+   * Set to `false` to disable.
+   */
+  crossOriginResourcePolicy?: string | false;
+
+  /**
+   * `Origin-Agent-Cluster`
+   * @defaultValue '?1'
+   * Set to `false` to disable.
+   */
+  originAgentCluster?: string | false;
+
+  /**
+   * `Referrer-Policy`
+   * @defaultValue 'no-referrer'
+   * Set to `false` to disable.
+   */
+  referrerPolicy?: string | false;
+
+  /**
+   * `Strict-Transport-Security` (HSTS)
+   * @defaultValue 'max-age=15552000; includeSubDomains'
+   * Set to `false` to disable.
+   */
+  strictTransportSecurity?: string | false;
+
+  /**
+   * `X-Content-Type-Options`
+   * @defaultValue 'nosniff'
+   * Set to `false` to disable.
+   */
+  xContentTypeOptions?: string | false;
+
+  /**
+   * `X-DNS-Prefetch-Control`
+   * @defaultValue 'off'
+   * Set to `false` to disable.
+   */
+  xDnsPrefetchControl?: string | false;
+
+  /**
+   * `X-Download-Options`
+   * @defaultValue 'noopen'
+   * Set to `false` to disable.
+   */
+  xDownloadOptions?: string | false;
+
+  /**
+   * `X-Frame-Options`
+   * @defaultValue 'SAMEORIGIN'
+   * Set to `false` to disable.
+   */
+  xFrameOptions?: string | false;
+
+  /**
+   * `X-Permitted-Cross-Domain-Policies`
+   * @defaultValue 'none'
+   * Set to `false` to disable.
+   */
+  xPermittedCrossDomainPolicies?: string | false;
+
+  /**
+   * `X-XSS-Protection`
+   * @defaultValue '0' (disabled by recommendation, modern browsers use CSP instead)
+   * Set to `false` to omit the header entirely.
+   */
+  xXssProtection?: string | false;
+}
+
+const DEFAULTS: Required<SecurityHeadersOptions> = {
+  contentSecurityPolicy: "default-src 'self'",
+  crossOriginOpenerPolicy: 'same-origin',
+  crossOriginResourcePolicy: 'same-origin',
+  originAgentCluster: '?1',
+  referrerPolicy: 'no-referrer',
+  strictTransportSecurity: 'max-age=15552000; includeSubDomains',
+  xContentTypeOptions: 'nosniff',
+  xDnsPrefetchControl: 'off',
+  xDownloadOptions: 'noopen',
+  xFrameOptions: 'SAMEORIGIN',
+  xPermittedCrossDomainPolicies: 'none',
+  xXssProtection: '0',
+};
+
+/**
+ * Maps camelCase option keys to the actual HTTP header names.
+ */
+const HEADER_MAP: Record<keyof SecurityHeadersOptions, string> = {
+  contentSecurityPolicy: 'Content-Security-Policy',
+  crossOriginOpenerPolicy: 'Cross-Origin-Opener-Policy',
+  crossOriginResourcePolicy: 'Cross-Origin-Resource-Policy',
+  originAgentCluster: 'Origin-Agent-Cluster',
+  referrerPolicy: 'Referrer-Policy',
+  strictTransportSecurity: 'Strict-Transport-Security',
+  xContentTypeOptions: 'X-Content-Type-Options',
+  xDnsPrefetchControl: 'X-DNS-Prefetch-Control',
+  xDownloadOptions: 'X-Download-Options',
+  xFrameOptions: 'X-Frame-Options',
+  xPermittedCrossDomainPolicies: 'X-Permitted-Cross-Domain-Policies',
+  xXssProtection: 'X-XSS-Protection',
+};
+
+/**
+ * Built-in security headers middleware — analogous to [helmet](https://helmetjs.github.io/).
+ *
+ * Sets a sensible default set of security-related HTTP response headers on every
+ * response. Individual headers can be overridden or disabled via the options object.
+ *
+ * @example Default usage (all headers with recommended defaults)
+ * ```typescript
+ * const app = new OneBunApplication(AppModule, {
+ *   middleware: [SecurityHeadersMiddleware],
+ * });
+ * ```
+ *
+ * @example Custom CSP + disable HSTS (e.g. in development)
+ * ```typescript
+ * const app = new OneBunApplication(AppModule, {
+ *   middleware: [
+ *     SecurityHeadersMiddleware.configure({
+ *       contentSecurityPolicy: "default-src 'self'; img-src *",
+ *       strictTransportSecurity: false,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class SecurityHeadersMiddleware extends BaseMiddleware {
+  private readonly resolvedHeaders: Array<[string, string]>;
+
+  /**
+   * Create a pre-configured SecurityHeadersMiddleware class with the given options.
+   * Returns a constructor — pass the result directly to `ApplicationOptions.middleware`.
+   */
+  static configure(options: SecurityHeadersOptions): typeof SecurityHeadersMiddleware {
+    class ConfiguredSecurityHeadersMiddleware extends SecurityHeadersMiddleware {
+      constructor() {
+        super(options);
+      }
+    }
+
+    return ConfiguredSecurityHeadersMiddleware;
+  }
+
+  constructor(options: SecurityHeadersOptions = {}) {
+    super();
+
+    const merged: SecurityHeadersOptions = { ...DEFAULTS, ...options };
+    this.resolvedHeaders = (Object.keys(HEADER_MAP) as Array<keyof SecurityHeadersOptions>)
+      .filter((key) => merged[key] !== false && merged[key] !== undefined)
+      .map((key) => [HEADER_MAP[key], merged[key] as string]);
+  }
+
+  async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>): Promise<OneBunResponse> {
+    const response = await next();
+
+    for (const [header, value] of this.resolvedHeaders) {
+      response.headers.set(header, value);
+    }
+
+    return response;
+  }
+}