@wopr-network/platform-core 0.1.0

package/src/middleware/csrf.ts

@@ -0,0 +1,101 @@
+import type { MiddlewareHandler } from "hono";
+import { extractBearerToken } from "../auth/index.js";
+
+const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+/**
+ * Check whether a path matches any of the exempt patterns.
+ * Patterns ending with "*" match as prefixes; exact strings match exactly.
+ */
+function isExempt(path: string, exemptPaths: string[]): boolean {
+  for (const pattern of exemptPaths) {
+    if (pattern.endsWith("*")) {
+      const prefix = pattern.slice(0, -1);
+      if (path.startsWith(prefix)) return true;
+    } else {
+      if (path === pattern) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Validate that a request's Origin or Referer matches one of the allowed origins.
+ * Returns true if the request is safe, false if it should be blocked.
+ */
+export function validateCsrfOrigin(headers: Headers, allowedOrigins: string[]): boolean {
+  const origin = headers.get("origin");
+
+  // Check Origin header first (most reliable)
+  if (origin) {
+    return allowedOrigins.includes(origin);
+  }
+
+  // Fall back to Referer header
+  const referer = headers.get("referer");
+  if (referer) {
+    try {
+      const refererOrigin = new URL(referer).origin;
+      return allowedOrigins.includes(refererOrigin);
+    } catch {
+      return false;
+    }
+  }
+
+  // No Origin or Referer on a mutation request — block it
+  return false;
+}
+
+export interface CsrfOptions {
+  /** Allowed origins (e.g. ["https://app.example.com"]). */
+  allowedOrigins: string[];
+  /**
+   * Paths exempt from CSRF validation.
+   * Use trailing "*" for prefix matching (e.g. "/api/auth/*").
+   * Exact strings match exactly (e.g. "/api/billing/webhook").
+   */
+  exemptPaths?: string[];
+}
+
+/**
+ * Hono middleware that validates Origin/Referer on state-changing requests.
+ * Skips:
+ * - GET/HEAD/OPTIONS requests (safe methods)
+ * - Requests with Bearer token (not vulnerable to CSRF)
+ * - Exempt paths (configurable)
+ */
+export function csrfProtection(options: CsrfOptions): MiddlewareHandler {
+  const exempt = options.exemptPaths ?? [];
+
+  return async (c, next) => {
+    // Safe methods — no CSRF risk
+    if (!MUTATION_METHODS.has(c.req.method)) {
+      return next();
+    }
+
+    // Exempt paths
+    if (isExempt(c.req.path, exempt)) {
+      return next();
+    }
+
+    // Bearer-token requests are not vulnerable to CSRF (browser doesn't auto-send)
+    const authHeader = c.req.header("Authorization");
+    if (extractBearerToken(authHeader)) {
+      return next();
+    }
+
+    // Unauthenticated requests (no session user, no bearer token) cannot be CSRF attacks —
+    // there is no credential to hijack. Let auth middleware return 401 naturally.
+    const user = c.get("user" as never);
+    if (!user) {
+      return next();
+    }
+
+    // Validate Origin/Referer
+    if (!validateCsrfOrigin(c.req.raw.headers, options.allowedOrigins)) {
+      return c.json({ error: "CSRF validation failed" }, 403);
+    }
+
+    return next();
+  };
+}

package/src/middleware/drizzle-rate-limit-repository.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Unit tests for DrizzleRateLimitRepository.
+ */
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { DrizzleRateLimitRepository } from "./drizzle-rate-limit-repository.js";
+
+describe("DrizzleRateLimitRepository", () => {
+  let repo: DrizzleRateLimitRepository;
+  let db: PlatformDb;
+  let pool: PGlite;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-02-21T12:00:00Z"));
+    await truncateAllTables(pool);
+    repo = new DrizzleRateLimitRepository(db);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("starts count at 1 for the first request", async () => {
+    const entry = await repo.increment("1.2.3.4", "api:default", 60_000);
+    expect(entry.count).toBe(1);
+    expect(entry.key).toBe("1.2.3.4");
+    expect(entry.scope).toBe("api:default");
+  });
+
+  it("increments count on subsequent requests within the window", async () => {
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+    const entry = await repo.increment("1.2.3.4", "api:default", 60_000);
+    expect(entry.count).toBe(3);
+  });
+
+  it("resets count when window expires", async () => {
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+
+    // Advance past the window
+    vi.advanceTimersByTime(61_000);
+
+    const entry = await repo.increment("1.2.3.4", "api:default", 60_000);
+    expect(entry.count).toBe(1);
+  });
+
+  it("tracks different keys independently", async () => {
+    await repo.increment("10.0.0.1", "api:default", 60_000);
+    await repo.increment("10.0.0.1", "api:default", 60_000);
+    const entry = await repo.increment("10.0.0.2", "api:default", 60_000);
+    expect(entry.count).toBe(1);
+  });
+
+  it("tracks different scopes independently", async () => {
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+    const entry = await repo.increment("1.2.3.4", "api:webhook", 60_000);
+    expect(entry.count).toBe(1);
+  });
+
+  it("get returns null for unknown entry", async () => {
+    expect(await repo.get("1.2.3.4", "api:default")).toBeNull();
+  });
+
+  it("get returns current entry", async () => {
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+    const entry = await repo.get("1.2.3.4", "api:default");
+    expect(entry).not.toBeNull();
+    expect(entry?.count).toBe(1);
+  });
+
+  it("purgeStale removes entries older than windowMs", async () => {
+    await repo.increment("1.2.3.4", "api:default", 60_000);
+
+    // Advance 2 minutes
+    vi.advanceTimersByTime(2 * 60_000);
+    await repo.increment("10.0.0.2", "api:default", 60_000);
+
+    const removed = await repo.purgeStale(60_000);
+    expect(removed).toBe(1);
+
+    expect(await repo.get("1.2.3.4", "api:default")).toBeNull();
+    expect(await repo.get("10.0.0.2", "api:default")).not.toBeNull();
+  });
+});

package/src/middleware/drizzle-rate-limit-repository.ts

@@ -0,0 +1,57 @@
+import { and, eq, lt, sql } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { rateLimitEntries } from "../db/schema/index.js";
+import type { IRateLimitRepository, RateLimitEntry } from "./rate-limit-repository.js";
+
+export class DrizzleRateLimitRepository implements IRateLimitRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async increment(key: string, scope: string, windowMs: number): Promise<RateLimitEntry> {
+    const now = Date.now();
+
+    // Check if existing entry is within the current window
+    const rows = await this.db
+      .select()
+      .from(rateLimitEntries)
+      .where(and(eq(rateLimitEntries.key, key), eq(rateLimitEntries.scope, scope)));
+    const existing = rows[0];
+
+    if (existing && now - existing.windowStart < windowMs) {
+      // Within window: increment
+      await this.db
+        .update(rateLimitEntries)
+        .set({ count: sql`${rateLimitEntries.count} + 1` })
+        .where(and(eq(rateLimitEntries.key, key), eq(rateLimitEntries.scope, scope)));
+      return { key, scope, count: existing.count + 1, windowStart: existing.windowStart };
+    }
+
+    // New window (or first request): upsert with count = 1
+    await this.db
+      .insert(rateLimitEntries)
+      .values({ key, scope, count: 1, windowStart: now })
+      .onConflictDoUpdate({
+        target: [rateLimitEntries.key, rateLimitEntries.scope],
+        set: { count: 1, windowStart: now },
+      });
+    return { key, scope, count: 1, windowStart: now };
+  }
+
+  async get(key: string, scope: string): Promise<RateLimitEntry | null> {
+    const rows = await this.db
+      .select()
+      .from(rateLimitEntries)
+      .where(and(eq(rateLimitEntries.key, key), eq(rateLimitEntries.scope, scope)));
+    const row = rows[0];
+    if (!row) return null;
+    return { key: row.key, scope: row.scope, count: row.count, windowStart: row.windowStart };
+  }
+
+  async purgeStale(windowMs: number): Promise<number> {
+    const cutoff = Date.now() - windowMs;
+    const result = await this.db
+      .delete(rateLimitEntries)
+      .where(lt(rateLimitEntries.windowStart, cutoff))
+      .returning({ key: rateLimitEntries.key });
+    return result.length;
+  }
+}

package/src/middleware/get-client-ip.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { getClientIp, parseTrustedProxies } from "./get-client-ip.js";
+
+describe("parseTrustedProxies", () => {
+  it("returns empty set for undefined", () => {
+    expect(parseTrustedProxies(undefined).size).toBe(0);
+  });
+
+  it("returns empty set for empty string", () => {
+    expect(parseTrustedProxies("").size).toBe(0);
+  });
+
+  it("parses comma-separated IPs", () => {
+    const result = parseTrustedProxies("10.0.0.1, 10.0.0.2");
+    expect(result.has("10.0.0.1")).toBe(true);
+    expect(result.has("10.0.0.2")).toBe(true);
+    expect(result.size).toBe(2);
+  });
+});
+
+describe("getClientIp", () => {
+  it("returns socket address when no trusted proxies configured", () => {
+    expect(getClientIp("attacker-spoofed", "1.2.3.4", new Set())).toBe("1.2.3.4");
+  });
+
+  it("ignores XFF when socket is not in trusted proxy set", () => {
+    const trusted = new Set(["10.0.0.1"]);
+    expect(getClientIp("spoofed-ip", "9.9.9.9", trusted)).toBe("9.9.9.9");
+  });
+
+  it("trusts XFF rightmost value when socket is a trusted proxy", () => {
+    const trusted = new Set(["10.0.0.1"]);
+    expect(getClientIp("client-ip, 10.0.0.1", "10.0.0.1", trusted)).toBe("10.0.0.1");
+  });
+
+  it("uses rightmost XFF entry (closest to trusted proxy)", () => {
+    const trusted = new Set(["10.0.0.1"]);
+    expect(getClientIp("spoofed, real-client", "10.0.0.1", trusted)).toBe("real-client");
+  });
+
+  it("handles IPv6-mapped IPv4 socket addresses", () => {
+    const trusted = new Set(["10.0.0.1"]);
+    expect(getClientIp("client-ip", "::ffff:10.0.0.1", trusted)).toBe("client-ip");
+  });
+
+  it("returns 'unknown' when no socket and no XFF", () => {
+    expect(getClientIp(undefined, undefined, new Set())).toBe("unknown");
+  });
+});

package/src/middleware/get-client-ip.ts

@@ -0,0 +1,62 @@
+import type { Context } from "hono";
+
+/**
+ * Parse the TRUSTED_PROXY_IPS env var into a Set of IP addresses.
+ * Returns an empty set if the value is undefined or empty.
+ */
+export function parseTrustedProxies(envValue: string | undefined): Set<string> {
+  if (!envValue) return new Set();
+  return new Set(
+    envValue
+      .split(",")
+      .map((ip) => ip.trim())
+      .filter(Boolean),
+  );
+}
+
+/** Strip IPv6-mapped-IPv4 prefix (::ffff:) for comparison. */
+function normalizeIp(ip: string): string {
+  return ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+}
+
+// Parsed once at module load — no per-request overhead.
+const trustedProxies = parseTrustedProxies(process.env.TRUSTED_PROXY_IPS);
+
+/**
+ * Determine the real client IP.
+ *
+ * - If `socketAddr` matches a trusted proxy, use the **last** (rightmost)
+ *   value from `X-Forwarded-For` (closest hop to the trusted proxy).
+ * - Otherwise, use `socketAddr` directly (XFF is untrusted).
+ * - Falls back to `"unknown"` if neither is available.
+ */
+export function getClientIp(
+  xffHeader: string | undefined,
+  socketAddr: string | undefined,
+  trusted: Set<string> = trustedProxies,
+): string {
+  const normalizedSocket = socketAddr ? normalizeIp(socketAddr) : undefined;
+
+  if (xffHeader && normalizedSocket && trusted.has(normalizedSocket)) {
+    // Trust XFF — take the rightmost (last) value
+    const parts = xffHeader.split(",");
+    const last = parts[parts.length - 1]?.trim();
+    if (last) return last;
+  }
+
+  if (socketAddr) return socketAddr;
+  return "unknown";
+}
+
+/**
+ * Convenience wrapper: extract client IP from a Hono Context.
+ * Reads XFF header and socket address from the request.
+ * Optionally accepts a trusted proxy set (defaults to the module-level set
+ * parsed from TRUSTED_PROXY_IPS — useful for testing).
+ */
+export function getClientIpFromContext(c: Context, trusted?: Set<string>): string {
+  const xff = c.req.header("x-forwarded-for");
+  const incoming = (c.env as Record<string, unknown>)?.incoming as { socket?: { remoteAddress?: string } } | undefined;
+  const socketAddr = incoming?.socket?.remoteAddress;
+  return trusted !== undefined ? getClientIp(xff, socketAddr, trusted) : getClientIp(xff, socketAddr);
+}

package/src/middleware/index.ts

@@ -0,0 +1,12 @@
+export type { IRateLimitRepository, RateLimitEntry } from "./rate-limit-repository.js";
+export { DrizzleRateLimitRepository } from "./drizzle-rate-limit-repository.js";
+export {
+  rateLimit,
+  rateLimitByRoute,
+  getClientIp,
+  parseTrustedProxies,
+  type RateLimitConfig,
+  type RateLimitRule,
+} from "./rate-limit.js";
+export { getClientIpFromContext } from "./get-client-ip.js";
+export { csrfProtection, validateCsrfOrigin, type CsrfOptions } from "./csrf.js";

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

@@ -0,0 +1,22 @@
+export interface RateLimitEntry {
+  key: string;
+  scope: string;
+  count: number;
+  windowStart: number;
+}
+
+export interface IRateLimitRepository {
+  /**
+   * Increment the counter for the given key + scope.
+   * If the current window has expired (now - windowStart >= windowMs), resets
+   * the counter to 1 and starts a new window.
+   * Returns the updated entry.
+   */
+  increment(key: string, scope: string, windowMs: number): Promise<RateLimitEntry>;
+
+  /** Read the current entry without modifying it. Returns null if absent. */
+  get(key: string, scope: string): Promise<RateLimitEntry | null>;
+
+  /** Delete entries whose window started more than windowMs ago. */
+  purgeStale(windowMs: number): Promise<number>;
+}