@wopr-network/platform-core 0.1.0

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

@@ -0,0 +1,338 @@
+/**
+ * Unit tests for rate-limit middleware factories.
+ *
+ * Only tests the generic rateLimit() and rateLimitByRoute() factories.
+ * Platform-specific rules (platformRateLimitRules) remain in wopr-platform.
+ */
+import type { PGlite } from "@electric-sql/pglite";
+import { Hono } from "hono";
+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";
+import type { IRateLimitRepository } from "./rate-limit-repository.js";
+import {
+  getClientIp,
+  parseTrustedProxies,
+  type RateLimitConfig,
+  type RateLimitRule,
+  rateLimit,
+  rateLimitByRoute,
+} from "./rate-limit.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build a Hono app with a single rate-limited GET /test route. */
+function buildApp(cfg: Omit<RateLimitConfig, "repo" | "scope">, repo: IRateLimitRepository) {
+  const app = new Hono();
+  app.use("/test", rateLimit({ ...cfg, repo, scope: "test" }));
+  app.get("/test", (c) => c.json({ ok: true }));
+  return app;
+}
+
+function req(path = "/test", ip = "127.0.0.1") {
+  return new Request(`http://localhost${path}`, {
+    headers: { "x-forwarded-for": ip },
+  });
+}
+
+function postReq(path: string, ip = "127.0.0.1") {
+  return new Request(`http://localhost${path}`, {
+    method: "POST",
+    headers: { "x-forwarded-for": ip },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Shared PGlite instance (one pool for the entire file)
+// ---------------------------------------------------------------------------
+
+let pool: PGlite;
+let db: PlatformDb;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+// ---------------------------------------------------------------------------
+// rateLimit (single-route)
+// ---------------------------------------------------------------------------
+
+describe("rateLimit", () => {
+  let repo: IRateLimitRepository;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    await truncateAllTables(pool);
+    repo = new DrizzleRateLimitRepository(db);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("allows requests within the limit", async () => {
+    const app = buildApp({ max: 3 }, repo);
+
+    for (let i = 0; i < 3; i++) {
+      const res = await app.request(req());
+      expect(res.status).toBe(200);
+    }
+  });
+
+  it("returns 429 when limit is exceeded", async () => {
+    const app = buildApp({ max: 2 }, repo);
+
+    await app.request(req());
+    await app.request(req());
+    const res = await app.request(req());
+
+    expect(res.status).toBe(429);
+    const body = await res.json();
+    expect(body.error).toContain("Too many requests");
+  });
+
+  it("sets X-RateLimit-* headers on every response", async () => {
+    const app = buildApp({ max: 5 }, repo);
+    const res = await app.request(req());
+
+    expect(res.headers.get("X-RateLimit-Limit")).toBe("5");
+    expect(res.headers.get("X-RateLimit-Remaining")).toBe("4");
+    expect(res.headers.get("X-RateLimit-Reset")).toBeTruthy();
+  });
+
+  it("sets Retry-After header on 429", async () => {
+    const app = buildApp({ max: 1 }, repo);
+
+    await app.request(req());
+    const res = await app.request(req());
+
+    expect(res.status).toBe(429);
+    const retryAfter = res.headers.get("Retry-After");
+    expect(retryAfter).toBeTruthy();
+    expect(Number(retryAfter)).toBeGreaterThan(0);
+  });
+
+  it("resets the window after windowMs elapses", async () => {
+    const app = buildApp({ max: 1, windowMs: 10_000 }, repo);
+
+    const res1 = await app.request(req());
+    expect(res1.status).toBe(200);
+
+    const res2 = await app.request(req());
+    expect(res2.status).toBe(429);
+
+    vi.advanceTimersByTime(10_001);
+
+    const res3 = await app.request(req());
+    expect(res3.status).toBe(200);
+  });
+
+  it("tracks different IPs independently", async () => {
+    const app = new Hono();
+    app.use(
+      "/test",
+      rateLimit({ max: 1, repo, scope: "test", keyGenerator: (c) => c.req.header("x-forwarded-for") ?? "unknown" }),
+    );
+    app.get("/test", (c) => c.json({ ok: true }));
+
+    const res1 = await app.request(req("/test", "10.0.0.1"));
+    expect(res1.status).toBe(200);
+
+    const res2 = await app.request(req("/test", "10.0.0.2"));
+    expect(res2.status).toBe(200);
+
+    const res3 = await app.request(req("/test", "10.0.0.1"));
+    expect(res3.status).toBe(429);
+  });
+
+  it("uses a custom message when provided", async () => {
+    const app = buildApp({ max: 1, message: "Slow down" }, repo);
+
+    await app.request(req());
+    const res = await app.request(req());
+
+    expect(res.status).toBe(429);
+    const body = await res.json();
+    expect(body.error).toBe("Slow down");
+  });
+
+  it("supports custom key generator", async () => {
+    const app = new Hono();
+    app.use(
+      "/test",
+      rateLimit({ max: 1, repo, scope: "api-key", keyGenerator: (c) => c.req.header("x-api-key") ?? "anon" }),
+    );
+    app.get("/test", (c) => c.json({ ok: true }));
+
+    const r1 = new Request("http://localhost/test", { headers: { "x-api-key": "key-a" } });
+    const r2 = new Request("http://localhost/test", { headers: { "x-api-key": "key-b" } });
+    const r3 = new Request("http://localhost/test", { headers: { "x-api-key": "key-a" } });
+
+    expect((await app.request(r1)).status).toBe(200);
+    expect((await app.request(r2)).status).toBe(200);
+    expect((await app.request(r3)).status).toBe(429);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// rateLimitByRoute (multi-route)
+// ---------------------------------------------------------------------------
+
+describe("rateLimitByRoute", () => {
+  let repo: IRateLimitRepository;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    await truncateAllTables(pool);
+    repo = new DrizzleRateLimitRepository(db);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("applies rule-specific limits based on path prefix", async () => {
+    const rules: RateLimitRule[] = [{ method: "POST", pathPrefix: "/strict", config: { max: 1 }, scope: "strict" }];
+    const app = new Hono();
+    app.use("*", rateLimitByRoute(rules, { max: 100 }, repo));
+    app.post("/strict", (c) => c.json({ ok: true }));
+    app.get("/lenient", (c) => c.json({ ok: true }));
+
+    expect((await app.request(postReq("/strict"))).status).toBe(200);
+    expect((await app.request(postReq("/strict"))).status).toBe(429);
+    expect((await app.request(req("/lenient"))).status).toBe(200);
+  });
+
+  it("falls back to default config when no rule matches", async () => {
+    const rules: RateLimitRule[] = [{ method: "POST", pathPrefix: "/special", config: { max: 1 }, scope: "special" }];
+    const app = new Hono();
+    app.use("*", rateLimitByRoute(rules, { max: 2 }, repo));
+    app.get("/other", (c) => c.json({ ok: true }));
+
+    expect((await app.request(req("/other"))).status).toBe(200);
+    expect((await app.request(req("/other"))).status).toBe(200);
+    expect((await app.request(req("/other"))).status).toBe(429);
+  });
+
+  it("matches method correctly (wildcard vs specific)", async () => {
+    const rules: RateLimitRule[] = [
+      { method: "*", pathPrefix: "/any-method", config: { max: 1 }, scope: "any-method" },
+      { method: "GET", pathPrefix: "/get-only", config: { max: 1 }, scope: "get-only" },
+    ];
+    const app = new Hono();
+    app.use("*", rateLimitByRoute(rules, { max: 100 }, repo));
+    app.get("/any-method", (c) => c.json({ ok: true }));
+    app.post("/any-method", (c) => c.json({ ok: true }));
+    app.get("/get-only", (c) => c.json({ ok: true }));
+    app.post("/get-only", (c) => c.json({ ok: true }));
+
+    expect((await app.request(req("/any-method"))).status).toBe(200);
+    expect((await app.request(postReq("/any-method"))).status).toBe(429);
+    expect((await app.request(req("/get-only"))).status).toBe(200);
+    expect((await app.request(req("/get-only"))).status).toBe(429);
+    expect((await app.request(postReq("/get-only"))).status).toBe(200);
+  });
+
+  it("first matching rule wins", async () => {
+    const rules: RateLimitRule[] = [
+      { method: "POST", pathPrefix: "/api/billing/checkout", config: { max: 2 }, scope: "billing:checkout" },
+      { method: "POST", pathPrefix: "/api/billing", config: { max: 100 }, scope: "billing" },
+    ];
+    const app = new Hono();
+    app.use("*", rateLimitByRoute(rules, { max: 100 }, repo));
+    app.post("/api/billing/checkout", (c) => c.json({ ok: true }));
+
+    expect((await app.request(postReq("/api/billing/checkout"))).status).toBe(200);
+    expect((await app.request(postReq("/api/billing/checkout"))).status).toBe(200);
+    expect((await app.request(postReq("/api/billing/checkout"))).status).toBe(429);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Trusted proxy validation
+// ---------------------------------------------------------------------------
+
+describe("trusted proxy validation", () => {
+  let repo: IRateLimitRepository;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    await truncateAllTables(pool);
+    repo = new DrizzleRateLimitRepository(db);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("ignores X-Forwarded-For when TRUSTED_PROXY_IPS is not set", () => {
+    const trusted = parseTrustedProxies(undefined);
+    expect(trusted.size).toBe(0);
+
+    const ip = getClientIp("spoofed-ip", "192.168.1.100", trusted);
+    expect(ip).toBe("192.168.1.100");
+  });
+
+  it("trusts X-Forwarded-For when socket address is in TRUSTED_PROXY_IPS", () => {
+    const trusted = parseTrustedProxies("172.18.0.5,10.0.0.1");
+    expect(trusted.size).toBe(2);
+
+    const ip = getClientIp("real-client-ip", "172.18.0.5", trusted);
+    expect(ip).toBe("real-client-ip");
+  });
+
+  it("strips ::ffff: prefix when matching trusted proxies", () => {
+    const trusted = parseTrustedProxies("172.18.0.5");
+
+    const ip = getClientIp("real-client-ip", "::ffff:172.18.0.5", trusted);
+    expect(ip).toBe("real-client-ip");
+  });
+
+  it("falls back to socket address when socket is not a trusted proxy", () => {
+    const trusted = parseTrustedProxies("172.18.0.5");
+
+    const ip = getClientIp("spoofed-ip", "evil-direct-client", trusted);
+    expect(ip).toBe("evil-direct-client");
+  });
+
+  it("uses last XFF value (rightmost) when proxy is trusted", () => {
+    const trusted = parseTrustedProxies("172.18.0.5");
+
+    const ip = getClientIp("fake, real-client", "172.18.0.5", trusted);
+    expect(ip).toBe("real-client");
+  });
+
+  it("returns 'unknown' when no socket address and no trusted proxy", () => {
+    const trusted = parseTrustedProxies(undefined);
+    const ip = getClientIp(undefined, undefined, trusted);
+    expect(ip).toBe("unknown");
+  });
+
+  it("rate limits by socket IP when XFF is spoofed without trusted proxy", async () => {
+    delete process.env.TRUSTED_PROXY_IPS;
+
+    const app = new Hono();
+    app.use("/test", rateLimit({ max: 1, repo, scope: "test" }));
+    app.get("/test", (c) => c.json({ ok: true }));
+
+    const r1 = new Request("http://localhost/test", {
+      headers: { "x-forwarded-for": "attacker-ip-1" },
+    });
+    const r2 = new Request("http://localhost/test", {
+      headers: { "x-forwarded-for": "attacker-ip-2" },
+    });
+
+    const res1 = await app.request(r1);
+    expect(res1.status).toBe(200);
+
+    const res2 = await app.request(r2);
+    expect(res2.status).toBe(429);
+  });
+});

package/src/middleware/rate-limit.ts

@@ -0,0 +1,169 @@
+/**
+ * Rate-limiting middleware for Hono.
+ *
+ * Uses a fixed-window counter keyed by client IP. Each window is `windowMs`
+ * milliseconds wide. When a client exceeds `max` requests in a window the
+ * middleware responds with 429 Too Many Requests and a `Retry-After` header
+ * indicating how many seconds remain in the current window.
+ *
+ * State is persisted via IRateLimitRepository (DB-backed in production).
+ */
+
+import type { Context, MiddlewareHandler, Next } from "hono";
+import type { IRateLimitRepository } from "./rate-limit-repository.js";
+import { getClientIpFromContext } from "./get-client-ip.js";
+
+export { getClientIp, parseTrustedProxies } from "./get-client-ip.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RateLimitConfig {
+  /** Maximum number of requests per window. */
+  max: number;
+  /** Window size in milliseconds (default: 60 000 = 1 minute). */
+  windowMs?: number;
+  /** Extract the rate-limit key from a request (default: client IP). */
+  keyGenerator?: (c: Context) => string;
+  /** Custom message returned in the 429 body (default provided). */
+  message?: string;
+  /** Repository for persisting rate-limit state. Required when rate limiting is active. */
+  repo?: IRateLimitRepository;
+  /** Scope identifier for this limiter (used as the DB scope key). */
+  scope?: string;
+}
+
+export interface RateLimitRule {
+  /** HTTP method to match, or "*" for any. */
+  method: string;
+  /** Path prefix to match (matched with `startsWith`). */
+  pathPrefix: string;
+  /** Rate-limit configuration for matching requests. */
+  config: Omit<RateLimitConfig, "repo" | "scope">;
+  /** Scope override (defaults to pathPrefix). */
+  scope?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function defaultKeyGenerator(c: Context): string {
+  return getClientIpFromContext(c);
+}
+
+const DEFAULT_WINDOW_MS = 60_000; // 1 minute
+
+// ---------------------------------------------------------------------------
+// Single-route rate limiter
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a rate-limiting middleware for a single configuration.
+ *
+ * ```ts
+ * app.use("/api/billing/*", rateLimit({ max: 10, repo, scope: "billing" }));
+ * ```
+ */
+export function rateLimit(cfg: RateLimitConfig): MiddlewareHandler {
+  const windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+  const keyGen = cfg.keyGenerator ?? defaultKeyGenerator;
+  const scope = cfg.scope ?? "default";
+
+  return async (c: Context, next: Next) => {
+    // No repo — rate limiting disabled (e.g., test environments)
+    if (!cfg.repo) return next();
+
+    const now = Date.now();
+    const key = keyGen(c);
+
+    const entry = await cfg.repo.increment(key, scope, windowMs);
+    const windowStart = entry.windowStart;
+    const count = entry.count;
+
+    // Check limit BEFORE this request counted — increment already happened
+    const retryAfterSec = Math.ceil((windowStart + windowMs - now) / 1000);
+
+    if (count > cfg.max) {
+      c.header("X-RateLimit-Limit", String(cfg.max));
+      c.header("X-RateLimit-Remaining", "0");
+      c.header("X-RateLimit-Reset", String(Math.ceil((windowStart + windowMs) / 1000)));
+      c.header("Retry-After", String(retryAfterSec));
+      return c.json({ error: cfg.message ?? "Too many requests, please try again later" }, 429);
+    }
+
+    const remaining = Math.max(0, cfg.max - count);
+
+    c.header("X-RateLimit-Limit", String(cfg.max));
+    c.header("X-RateLimit-Remaining", String(remaining));
+    c.header("X-RateLimit-Reset", String(Math.ceil((windowStart + windowMs) / 1000)));
+
+    return next();
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Multi-route rate limiter (global middleware with per-route overrides)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a global rate-limiting middleware that applies different limits based
+ * on the request path and method.
+ *
+ * Rules are evaluated top-to-bottom; the **first** matching rule wins. If no
+ * rule matches, the `defaultConfig` is used.
+ *
+ * ```ts
+ * app.use("*", rateLimitByRoute(rules, { max: 60 }, repo));
+ * ```
+ */
+export function rateLimitByRoute(
+  rules: RateLimitRule[],
+  defaultConfig: Omit<RateLimitConfig, "repo" | "scope">,
+  repo: IRateLimitRepository,
+): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    const method = c.req.method.toUpperCase();
+    const path = c.req.path;
+
+    // Find matching rule
+    let cfg: Omit<RateLimitConfig, "repo" | "scope"> = defaultConfig;
+    let scope = "default";
+    for (const rule of rules) {
+      const methodMatch = rule.method === "*" || rule.method.toUpperCase() === method;
+      if (methodMatch && path.startsWith(rule.pathPrefix)) {
+        cfg = rule.config;
+        scope = rule.scope ?? rule.pathPrefix;
+        break;
+      }
+    }
+
+    const windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+    const keyGen = cfg.keyGenerator ?? defaultKeyGenerator;
+    const now = Date.now();
+    const key = keyGen(c);
+
+    const entry = await repo.increment(key, scope, windowMs);
+    const windowStart = entry.windowStart;
+    const count = entry.count;
+
+    const retryAfterSec = Math.ceil((windowStart + windowMs - now) / 1000);
+
+    if (count > cfg.max) {
+      c.header("X-RateLimit-Limit", String(cfg.max));
+      c.header("X-RateLimit-Remaining", "0");
+      c.header("X-RateLimit-Reset", String(Math.ceil((windowStart + windowMs) / 1000)));
+      c.header("Retry-After", String(retryAfterSec));
+      return c.json({ error: cfg.message ?? "Too many requests, please try again later" }, 429);
+    }
+
+    const remaining = Math.max(0, cfg.max - count);
+
+    c.header("X-RateLimit-Limit", String(cfg.max));
+    c.header("X-RateLimit-Remaining", String(remaining));
+    c.header("X-RateLimit-Reset", String(Math.ceil((windowStart + windowMs) / 1000)));
+
+    return next();
+  };
+}

package/src/security/credential-vault/audit-repository.test.ts

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { DrizzleSecretAuditRepository } from "./audit-repository.js";
+
+let db: PlatformDb;
+let pool: PGlite;
+let repo: DrizzleSecretAuditRepository;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+beforeEach(async () => {
+  await truncateAllTables(pool);
+  repo = new DrizzleSecretAuditRepository(db);
+});
+
+describe("DrizzleSecretAuditRepository", () => {
+  const credentialId = "cred-1";
+
+  it("inserts and retrieves audit events", async () => {
+    const event = {
+      id: randomUUID(),
+      credentialId,
+      accessedAt: Date.now(),
+      accessedBy: "user-1",
+      action: "read" as const,
+      ip: "127.0.0.1",
+    };
+    await repo.insert(event);
+
+    const events = await repo.listByCredentialId(credentialId, { limit: 50, offset: 0 });
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      id: event.id,
+      credentialId,
+      accessedBy: "user-1",
+      action: "read",
+      ip: "127.0.0.1",
+    });
+  });
+
+  it("counts events by credential ID", async () => {
+    for (let i = 0; i < 3; i++) {
+      await repo.insert({
+        id: randomUUID(),
+        credentialId,
+        accessedAt: Date.now() + i,
+        accessedBy: "user-1",
+        action: "read",
+        ip: null,
+      });
+    }
+    const count = await repo.countByCredentialId(credentialId);
+    expect(count).toBe(3);
+  });
+
+  it("paginates results ordered by accessedAt desc", async () => {
+    for (let i = 0; i < 5; i++) {
+      await repo.insert({
+        id: randomUUID(),
+        credentialId,
+        accessedAt: 1000 + i,
+        accessedBy: "user-1",
+        action: "read",
+        ip: null,
+      });
+    }
+    const page1 = await repo.listByCredentialId(credentialId, { limit: 2, offset: 0 });
+    expect(page1).toHaveLength(2);
+    expect(page1[0]?.accessedAt).toBe(1004); // newest first
+
+    const page2 = await repo.listByCredentialId(credentialId, { limit: 2, offset: 2 });
+    expect(page2).toHaveLength(2);
+    expect(page2[0]?.accessedAt).toBe(1002);
+  });
+
+  it("returns empty for unknown credential", async () => {
+    const events = await repo.listByCredentialId("nonexistent", { limit: 50, offset: 0 });
+    expect(events).toHaveLength(0);
+    const count = await repo.countByCredentialId("nonexistent");
+    expect(count).toBe(0);
+  });
+});

package/src/security/credential-vault/audit-repository.ts

@@ -0,0 +1,64 @@
+import { count, desc, eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { secretAuditLog } from "../../db/schema/index.js";
+
+export interface SecretAuditEvent {
+  id: string;
+  credentialId: string;
+  accessedAt: number;
+  accessedBy: string;
+  action: "read" | "write" | "delete";
+  ip: string | null;
+}
+
+export interface ISecretAuditRepository {
+  insert(event: SecretAuditEvent): Promise<void>;
+  listByCredentialId(credentialId: string, opts: { limit: number; offset: number }): Promise<SecretAuditEvent[]>;
+  countByCredentialId(credentialId: string): Promise<number>;
+}
+
+const MAX_LIMIT = 250;
+
+export class DrizzleSecretAuditRepository implements ISecretAuditRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async insert(event: SecretAuditEvent): Promise<void> {
+    await this.db.insert(secretAuditLog).values({
+      id: event.id,
+      credentialId: event.credentialId,
+      accessedAt: event.accessedAt,
+      accessedBy: event.accessedBy,
+      action: event.action,
+      ip: event.ip,
+    });
+  }
+
+  async listByCredentialId(credentialId: string, opts: { limit: number; offset: number }): Promise<SecretAuditEvent[]> {
+    const limit = Math.min(Math.max(1, opts.limit), MAX_LIMIT);
+    const offset = Math.max(0, opts.offset);
+
+    const rows = await this.db
+      .select()
+      .from(secretAuditLog)
+      .where(eq(secretAuditLog.credentialId, credentialId))
+      .orderBy(desc(secretAuditLog.accessedAt))
+      .limit(limit)
+      .offset(offset);
+
+    return rows.map((r) => ({
+      id: r.id,
+      credentialId: r.credentialId,
+      accessedAt: r.accessedAt,
+      accessedBy: r.accessedBy,
+      action: r.action as "read" | "write" | "delete",
+      ip: r.ip,
+    }));
+  }
+
+  async countByCredentialId(credentialId: string): Promise<number> {
+    const result = (
+      await this.db.select({ count: count() }).from(secretAuditLog).where(eq(secretAuditLog.credentialId, credentialId))
+    )[0];
+    return result?.count ?? 0;
+  }
+}