@wopr-network/platform-core 0.1.0

package/dist/middleware/drizzle-rate-limit-repository.test.js

@@ -0,0 +1,74 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { DrizzleRateLimitRepository } from "./drizzle-rate-limit-repository.js";
+describe("DrizzleRateLimitRepository", () => {
+    let repo;
+    let db;
+    let pool;
+    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/dist/middleware/get-client-ip.d.ts

@@ -0,0 +1,22 @@
+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 declare function parseTrustedProxies(envValue: string | undefined): Set<string>;
+/**
+ * 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 declare function getClientIp(xffHeader: string | undefined, socketAddr: string | undefined, trusted?: Set<string>): string;
+/**
+ * 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 declare function getClientIpFromContext(c: Context, trusted?: Set<string>): string;

package/dist/middleware/get-client-ip.js

@@ -0,0 +1,51 @@
+/**
+ * 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) {
+    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) {
+    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, socketAddr, trusted = trustedProxies) {
+    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, trusted) {
+    const xff = c.req.header("x-forwarded-for");
+    const incoming = c.env?.incoming;
+    const socketAddr = incoming?.socket?.remoteAddress;
+    return trusted !== undefined ? getClientIp(xff, socketAddr, trusted) : getClientIp(xff, socketAddr);
+}

package/dist/middleware/get-client-ip.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/middleware/get-client-ip.test.js

@@ -0,0 +1,40 @@
+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/dist/middleware/index.d.ts

@@ -0,0 +1,5 @@
+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/dist/middleware/index.js

@@ -0,0 +1,4 @@
+export { DrizzleRateLimitRepository } from "./drizzle-rate-limit-repository.js";
+export { rateLimit, rateLimitByRoute, getClientIp, parseTrustedProxies, } from "./rate-limit.js";
+export { getClientIpFromContext } from "./get-client-ip.js";
+export { csrfProtection, validateCsrfOrigin } from "./csrf.js";

package/dist/middleware/rate-limit-repository.d.ts

@@ -0,0 +1,19 @@
+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>;
+}

package/dist/middleware/rate-limit-repository.js

@@ -0,0 +1 @@
+export {};

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 } from "hono";
+import type { IRateLimitRepository } from "./rate-limit-repository.js";
+export { getClientIp, parseTrustedProxies } from "./get-client-ip.js";
+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;
+}
+/**
+ * Create a rate-limiting middleware for a single configuration.
+ *
+ * ```ts
+ * app.use("/api/billing/*", rateLimit({ max: 10, repo, scope: "billing" }));
+ * ```
+ */
+export declare function rateLimit(cfg: RateLimitConfig): MiddlewareHandler;
+/**
+ * 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 declare function rateLimitByRoute(rules: RateLimitRule[], defaultConfig: Omit<RateLimitConfig, "repo" | "scope">, repo: IRateLimitRepository): MiddlewareHandler;

package/dist/middleware/rate-limit.js

@@ -0,0 +1,109 @@
+/**
+ * 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 { getClientIpFromContext } from "./get-client-ip.js";
+export { getClientIp, parseTrustedProxies } from "./get-client-ip.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function defaultKeyGenerator(c) {
+    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) {
+    const windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+    const keyGen = cfg.keyGenerator ?? defaultKeyGenerator;
+    const scope = cfg.scope ?? "default";
+    return async (c, 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, defaultConfig, repo) {
+    return async (c, next) => {
+        const method = c.req.method.toUpperCase();
+        const path = c.req.path;
+        // Find matching rule
+        let cfg = 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/dist/middleware/rate-limit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/middleware/rate-limit.test.js

@@ -0,0 +1,247 @@
+import { Hono } from "hono";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { DrizzleRateLimitRepository } from "./drizzle-rate-limit-repository.js";
+import { getClientIp, parseTrustedProxies, rateLimit, rateLimitByRoute, } from "./rate-limit.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Build a Hono app with a single rate-limited GET /test route. */
+function buildApp(cfg, repo) {
+    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, 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;
+let db;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+});
+afterAll(async () => {
+    await pool.close();
+});
+// ---------------------------------------------------------------------------
+// rateLimit (single-route)
+// ---------------------------------------------------------------------------
+describe("rateLimit", () => {
+    let repo;
+    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;
+    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 = [{ 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 = [{ 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 = [
+            { 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 = [
+            { 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;
+    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);
+    });
+});