@joinremba/gate 0.2.0 → 0.4.0

package/README.md

@@ -13,7 +13,6 @@ Gate is the API safety layer for TypeScript backends. It validates requests, for
 - **Structured responses** — Consistent `{ success, data, error }` response envelope with `ok()` and `fail()` helpers.
 - **Problem details** — RFC 9457 problem-details-style error format.
 - **Pagination** — Standardised paginated response helper.
-- **Request ID** — Automatic request ID generation and propagation.
 - **Idempotency** — Prevent duplicate writes with idempotency keys. Ships with in-memory store; plug in Redis or Postgres.
 - **Rate limiting** — Protect endpoints from abuse with configurable windows and limits.
 - **API key management** — Rotatable, scoped API key authentication with Bearer token support.
@@ -184,7 +183,85 @@ if (!result.authenticated) throw new AuthenticationError(result.error);
 
 **When to use it:** You have a few static keys for internal services, a shared webhook secret, or scoped tokens for admin tools. Keys are configured at startup and held in memory — no database query per request, zero dependencies.
 
-**When not to use it:** You need key rotation, hashed storage, per-user API keys, expiry/revocation, or rate limiting per key. For those cases, extend with a DB-backed validator (e.g. query Postgres with `SELECT * FROM api_keys WHERE key_hash = $1`).
+**When not to use it:** You need key rotation, hashed storage, per-user API keys, expiry/revocation, or rate limiting per key. For those cases, use the hashed or DB-backed stores below.
+
+#### Hashed API Keys
+
+Store SHA-256 hashes instead of plaintext keys. Protects against memory dumps.
+
+```ts
+const validator = createApiKeyValidator([{ key: "sk-live-123", scopes: ["admin"] }], {
+  hashKeys: true,
+});
+
+await validator.verify("sk-live-123");
+// -> { authenticated: true, key: "sk-live-123", scopes: ["admin"] }
+```
+
+#### DB-backed API Key Stores
+
+Validate keys against Postgres or Redis. Keys can be added/removed at runtime.
+
+```ts
+import { PostgresApiKeyStore } from "@joinremba/gate/stores/postgres-api-keys";
+
+const store = new PostgresApiKeyStore(pgClient);
+await store.ensureTable();
+
+// Add a key
+await store.setKey({ key: "sk-live-abc", scopes: ["read"] }, expiresAt);
+
+// Validate
+const result = await store.verify("sk-live-abc");
+
+// Remove
+await store.deleteKey("sk-live-abc");
+```
+
+```ts
+import { RedisApiKeyStore } from "@joinremba/gate/stores/redis-api-keys";
+
+const store = new RedisApiKeyStore(redisClient);
+await store.setKey({ key: "sk-redis-key", scopes: ["admin"] });
+const result = await store.verify("sk-redis-key");
+```
+
+### Combined Middleware
+
+Run auth, rate limiting, and idempotency in a single middleware call:
+
+```ts
+const gate = createGate({
+  apiKeys: [{ key: "sk-admin" }],
+  rateLimit: { windowMs: 60_000, max: 100 },
+});
+
+app.use(
+  gate.middleware({
+    auth: true,
+    requiredScopes: ["write"],
+    rateLimit: true,
+    idempotency: true,
+    excludePaths: ["/health", "/metrics"],
+  })
+);
+```
+
+The middleware returns 401 for invalid/missing keys, 429 when rate limited, and caches idempotent responses automatically.
+
+### Per-key Rate Limiting
+
+Rate-limit by API key instead of IP:
+
+```ts
+import { rateLimit, keyByApiKey } from "@joinremba/gate/rate-limit";
+
+const limiter = rateLimit({
+  windowMs: 60_000,
+  max: 30,
+  keyFn: keyByApiKey,
+});
+```
 
 ### Errors (`@joinremba/gate/errors`)
 
@@ -317,15 +394,13 @@ app.post("/orders", async (req, res, next) => {
 - In-memory idempotency store
 - In-memory rate limiting store
 
-**V1**
+**V1** (current)
 
-- Idempotency middleware
-- Redis idempotency store
-- Postgres idempotency store
-- Rate limiting middleware
+- Redis and Postgres stores for idempotency and rate limiting
 - API key hashing and validation
-- Scopes and permissions middleware
-- Usage tracking hooks
+- DB-backed API key stores (Redis, Postgres)
+- Combined middleware (auth + rate limit + idempotency)
+- Per-key rate limiting helper
 
 **V2**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/gate",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "API safety layer for TypeScript backends. Validate requests, format responses, prevent duplicates, manage API keys, and protect endpoints from abuse.",
   "type": "module",
   "main": "./src/index.ts",
@@ -46,10 +46,20 @@
       "import": "./src/stores/redis.ts",
       "default": "./src/stores/redis.ts"
     },
+    "./stores/redis-api-keys": {
+      "types": "./src/stores/redis-api-keys.ts",
+      "import": "./src/stores/redis-api-keys.ts",
+      "default": "./src/stores/redis-api-keys.ts"
+    },
     "./stores/postgres": {
       "types": "./src/stores/postgres.ts",
       "import": "./src/stores/postgres.ts",
       "default": "./src/stores/postgres.ts"
+    },
+    "./stores/postgres-api-keys": {
+      "types": "./src/stores/postgres-api-keys.ts",
+      "import": "./src/stores/postgres-api-keys.ts",
+      "default": "./src/stores/postgres-api-keys.ts"
     }
   },
   "files": [
@@ -100,6 +110,7 @@
     "bun": ">=1.3.1"
   },
   "dependencies": {
+    "@joinremba/core": "^0.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/src/api-keys.test.ts

@@ -0,0 +1,53 @@
+import { expect, test } from "bun:test";
+import { createApiKeyValidator } from "./api-keys";
+
+test("validate returns authenticated for matching key", () => {
+  const validator = createApiKeyValidator([{ key: "sk-live-abc", scopes: ["read"] }]);
+  const result = validator.validate("sk-live-abc");
+  expect(result.authenticated).toBe(true);
+  expect(result.scopes).toEqual(["read"]);
+});
+
+test("validate returns error for unknown key", () => {
+  const validator = createApiKeyValidator([{ key: "sk-live-abc" }]);
+  const result = validator.validate("sk-live-xyz");
+  expect(result.authenticated).toBe(false);
+  expect(result.error).toBe("Invalid API key");
+});
+
+test("verify with hashKeys true hashes before lookup", async () => {
+  const validator = createApiKeyValidator(
+    [
+      {
+        key: "sk-live-123",
+        scopes: ["admin"],
+      },
+    ],
+    { hashKeys: true }
+  );
+  // "sk-live-123" sha256 = 9418b81169b7...
+  const result = await validator.verify("sk-live-123");
+  expect(result.authenticated).toBe(true);
+  expect(result.scopes).toEqual(["admin"]);
+});
+
+test("authenticate middleware reads Authorization header", async () => {
+  const validator = createApiKeyValidator([{ key: "sk-test", scopes: ["read"] }]);
+  const auth = validator.authenticate({ requiredScopes: ["read"] });
+  const req = new Request("http://localhost", {
+    headers: { Authorization: "Bearer sk-test" },
+  });
+  const result = await auth(req);
+  expect(result.authenticated).toBe(true);
+});
+
+test("authenticate rejects missing scopes", async () => {
+  const validator = createApiKeyValidator([{ key: "sk-test", scopes: ["read"] }]);
+  const auth = validator.authenticate({ requiredScopes: ["write"] });
+  const req = new Request("http://localhost", {
+    headers: { Authorization: "Bearer sk-test" },
+  });
+  const result = await auth(req);
+  expect(result.authenticated).toBe(false);
+  expect(result.error).toBe("Insufficient permissions");
+});

package/src/api-keys.ts

@@ -4,6 +4,10 @@ export interface ApiKeyEntry {
   metadata?: Record<string, unknown>;
 }
 
+export interface ApiKeyValidatorOptions {
+  hashKeys?: boolean;
+}
+
 export interface AuthenticateOptions {
   requiredScopes?: string[];
   header?: string;
@@ -13,11 +17,44 @@ export interface AuthenticateResult {
   authenticated: boolean;
   key?: string;
   scopes?: string[];
+  metadata?: Record<string, unknown>;
   error?: string;
 }
 
-export function createApiKeyValidator(keys: ApiKeyEntry[]) {
-  const keyMap = new Map(keys.map((k) => [k.key, k]));
+async function sha256(input: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function createApiKeyValidator(keys: ApiKeyEntry[], options: ApiKeyValidatorOptions = {}) {
+  const { hashKeys = false } = options;
+  const keyMap = new Map<
+    string,
+    { key: string; scopes?: string[]; metadata?: Record<string, unknown> }
+  >();
+
+  for (const entry of keys) {
+    keyMap.set(entry.key, { key: entry.key, scopes: entry.scopes, metadata: entry.metadata });
+  }
+
+  let hashCache: Map<
+    string,
+    { key: string; scopes?: string[]; metadata?: Record<string, unknown> }
+  > | null = null;
+
+  async function ensureHashCache() {
+    if (!hashCache) {
+      hashCache = new Map();
+      for (const [, entry] of keyMap) {
+        hashCache.set(await sha256(entry.key), entry);
+      }
+    }
+    return hashCache;
+  }
 
   return {
     validate(providedKey: string): AuthenticateResult {
@@ -25,21 +62,44 @@ export function createApiKeyValidator(keys: ApiKeyEntry[]) {
       if (!entry) {
         return { authenticated: false, error: "Invalid API key" };
       }
-      return { authenticated: true, key: entry.key, scopes: entry.scopes };
+      return {
+        authenticated: true,
+        key: entry.key,
+        scopes: entry.scopes,
+        metadata: entry.metadata,
+      };
+    },
+
+    async verify(providedKey: string): Promise<AuthenticateResult> {
+      if (!hashKeys) {
+        return this.validate(providedKey);
+      }
+      const cache = await ensureHashCache();
+      const keyHash = await sha256(providedKey);
+      const entry = cache.get(keyHash);
+      if (!entry) {
+        return { authenticated: false, error: "Invalid API key" };
+      }
+      return {
+        authenticated: true,
+        key: providedKey,
+        scopes: entry.scopes,
+        metadata: entry.metadata,
+      };
     },
 
     authenticate(options: AuthenticateOptions = {}) {
       const header = options.header ?? "Authorization";
       const requiredScopes = options.requiredScopes ?? [];
 
-      return (req: Request): AuthenticateResult => {
+      return async (req: Request): Promise<AuthenticateResult> => {
         const authHeader = req.headers.get(header);
         if (!authHeader) {
           return { authenticated: false, error: "Missing API key" };
         }
 
         const token = authHeader.replace(/^Bearer\s+/i, "").trim();
-        const result = this.validate(token);
+        const result = hashKeys ? await this.verify(token) : this.validate(token);
 
         if (!result.authenticated) return result;
 

package/src/idempotency.ts

@@ -6,6 +6,25 @@ export interface IdempotencyStore {
 
 export class InMemoryStore implements IdempotencyStore {
   private store = new Map<string, { value: unknown; expires: number }>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor() {
+    this.cleanupInterval = setInterval(() => this.evictExpired(), 60_000);
+    if (
+      this.cleanupInterval &&
+      typeof this.cleanupInterval === "object" &&
+      "unref" in this.cleanupInterval
+    ) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  private evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expires) this.store.delete(key);
+    }
+  }
 
   async get(key: string): Promise<unknown | null> {
     const entry = this.store.get(key);
@@ -24,6 +43,11 @@ export class InMemoryStore implements IdempotencyStore {
   async delete(key: string): Promise<void> {
     this.store.delete(key);
   }
+
+  dispose(): void {
+    if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+    this.store.clear();
+  }
 }
 
 export interface IdempotencyOptions {

package/src/index.test.ts

@@ -95,6 +95,16 @@ describe("rate limit", () => {
     expect(result.allowed).toBe(true);
     expect(result.remaining).toBe(99);
   });
+
+  test("accepts string key directly", async () => {
+    const gate = createGate({
+      rateLimit: { windowMs: 60000, max: 10 },
+    });
+
+    const result = await gate.rateLimit.check("custom:user-42");
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(9);
+  });
 });
 
 describe("api keys", () => {
@@ -114,3 +124,69 @@ describe("api keys", () => {
     expect(result.authenticated).toBe(false);
   });
 });
+
+describe("keyByApiKey", () => {
+  test("uses API key from Authorization header", async () => {
+    const { keyByApiKey } = await import("./rate-limit");
+    const req = new Request("http://localhost", {
+      headers: { Authorization: "Bearer sk-live-abc123" },
+    });
+    const key = keyByApiKey(req);
+    expect(key).toStartWith("ak:sk-live-abc1");
+  });
+
+  test("falls back to IP when no auth header", async () => {
+    const { keyByApiKey } = await import("./rate-limit");
+    const req = new Request("http://localhost");
+    const key = keyByApiKey(req);
+    expect(typeof key).toBe("string");
+  });
+});
+
+describe("middleware", () => {
+  test("passes through when no features enabled", async () => {
+    const gate = createGate();
+    const mw = gate.middleware();
+    const req = new Request("http://localhost/api");
+    let called = false;
+    const res = await mw(req, async () => {
+      called = true;
+      return new Response("ok");
+    });
+    expect(called).toBe(true);
+    expect(res).toBeInstanceOf(Response);
+  });
+
+  test("rejects request when auth fails", async () => {
+    const gate = createGate({ apiKeys: [{ key: "sk-valid" }] });
+    const mw = gate.middleware({ auth: true });
+    const req = new Request("http://localhost/api", {
+      headers: { Authorization: "Bearer sk-wrong" },
+    });
+    const res = await mw(req, async () => new Response("ok"));
+    expect(res!.status).toBe(401);
+    const body = (await res!.json()) as Record<string, unknown>;
+    expect(body.success).toBe(false);
+  });
+
+  test("rejects when rate limit exceeded", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 0 } });
+    const mw = gate.middleware({ rateLimit: true });
+    const req = new Request("http://localhost/api");
+    const res = await mw(req, async () => new Response("ok"));
+    expect(res!.status).toBe(429);
+  });
+
+  test("skips excluded paths", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 0 } });
+    const mw = gate.middleware({ rateLimit: true, excludePaths: ["/health"] });
+    const req = new Request("http://localhost/health");
+    let called = false;
+    const res = await mw(req, async () => {
+      called = true;
+      return new Response("ok");
+    });
+    expect(called).toBe(true);
+    expect(res!.status).toBe(200);
+  });
+});

package/src/index.ts

@@ -1,10 +1,29 @@
 import { validateRequest } from "./validate";
 import { ok, fail, paginated, problem } from "./respond";
 import { idempotency, InMemoryStore } from "./idempotency";
-import { rateLimit, InMemoryRateLimitStore } from "./rate-limit";
+import { rateLimit, InMemoryRateLimitStore, keyByApiKey } from "./rate-limit";
+import type { RateLimitStore, RateLimitCheckResult } from "./rate-limit";
 import { createApiKeyValidator } from "./api-keys";
-import type { ApiKeyEntry } from "./api-keys";
+import type { ApiKeyEntry, AuthenticateResult } from "./api-keys";
 import type { IdempotencyStore } from "./idempotency";
+import type { Client } from "@joinremba/core";
+import { NetworkError } from "@joinremba/core";
+
+const gateAuthStore = new WeakMap<Request, AuthenticateResult>();
+const gateIdempotencyStore = new WeakMap<Request, string>();
+const gateRateLimitStore = new WeakMap<Request, RateLimitCheckResult>();
+
+export function getGateAuth(req: Request): AuthenticateResult | undefined {
+  return gateAuthStore.get(req);
+}
+
+export function getGateIdempotencyKey(req: Request): string | undefined {
+  return gateIdempotencyStore.get(req);
+}
+
+export function getGateRateLimit(req: Request): RateLimitCheckResult | undefined {
+  return gateRateLimitStore.get(req);
+}
 import {
   GateError,
   ValidationError,
@@ -23,6 +42,7 @@ export {
   InMemoryStore,
   rateLimit,
   InMemoryRateLimitStore,
+  keyByApiKey,
   createApiKeyValidator,
   GateError,
   ValidationError,
@@ -52,12 +72,25 @@ export type {
   AuthenticateOptions,
   AuthenticateResult,
   ApiKeyValidator,
+  ApiKeyValidatorOptions,
 } from "./api-keys";
 
 export type Middleware = (req: Request, next?: () => Promise<Response>) => Promise<Response | null>;
 
+export interface MiddlewareOptions {
+  auth?: boolean;
+  requiredScopes?: string[];
+  rateLimit?: boolean;
+  idempotency?: boolean;
+  /** Override the max for this specific middleware. */
+  rateLimitMax?: number;
+  /** Paths to skip entirely. */
+  excludePaths?: string[];
+}
+
 export interface GateOptions {
   apiKeys?: ApiKeyEntry[];
+  client?: Client;
   idempotency?: {
     store?: IdempotencyStore;
     keyHeader?: string;
@@ -66,10 +99,19 @@ export interface GateOptions {
   rateLimit?: {
     windowMs?: number;
     max?: number;
-    strategy?: "fixed" | "sliding";
+    store?: RateLimitStore;
+    keyFn?: (req: Request) => string;
   };
 }
 
+export type MiddlewareResult =
+  | {
+      passed: true;
+      auth?: { key: string; scopes?: string[] };
+      rateLimit?: { remaining: number; reset: number };
+    }
+  | { passed: false; status: number; body: unknown };
+
 export interface Gate {
   validate: typeof validateRequest;
   ok: typeof ok;
@@ -79,10 +121,12 @@ export interface Gate {
   idempotency: ReturnType<typeof idempotency>;
   rateLimit: ReturnType<typeof rateLimit>;
   apiKeys: ReturnType<typeof createApiKeyValidator>;
-  middleware(): Middleware;
+  middleware(opts?: MiddlewareOptions): Middleware;
 }
 
 export function createGate(options: GateOptions = {}): Gate {
+  const client = options.client;
+
   const idempInstance = idempotency({
     store: options.idempotency?.store ?? new InMemoryStore(),
     keyHeader: options.idempotency?.keyHeader,
@@ -92,10 +136,71 @@ export function createGate(options: GateOptions = {}): Gate {
   const rlInstance = rateLimit({
     windowMs: options.rateLimit?.windowMs,
     max: options.rateLimit?.max,
+    store: options.rateLimit?.store,
+    keyFn: options.rateLimit?.keyFn,
   });
 
   const apiKeyValidator = createApiKeyValidator(options.apiKeys ?? []);
 
+  if (client) {
+    const origCheck = rlInstance.check.bind(rlInstance);
+    rlInstance.check = async (reqOrKey) => {
+      const key = typeof reqOrKey === "string" ? reqOrKey : rlInstance.keyFn(reqOrKey);
+      try {
+        return await client.checkRateLimit(key);
+      } catch (err) {
+        if (err instanceof NetworkError) return origCheck(reqOrKey);
+        throw err;
+      }
+    };
+
+    const origIdemGet = idempInstance.getResponse.bind(idempInstance);
+    const origIdemSet = idempInstance.setResponse.bind(idempInstance);
+    idempInstance.getResponse = async (key: string) => {
+      try {
+        const result = await client.checkIdempotency(key);
+        if (result.exists) return result.response;
+        return null;
+      } catch (err) {
+        if (err instanceof NetworkError) return origIdemGet(key);
+        throw err;
+      }
+    };
+    idempInstance.setResponse = async (key: string, response: unknown) => {
+      try {
+        await client.setIdempotency(key, response);
+      } catch (err) {
+        if (err instanceof NetworkError) return origIdemSet(key, response);
+        throw err;
+      }
+    };
+
+    const origAuthenticate = apiKeyValidator.authenticate.bind(apiKeyValidator);
+    apiKeyValidator.authenticate = (authOptions) => {
+      const handler = origAuthenticate(authOptions);
+      return async (req) => {
+        const token = req.headers
+          .get("Authorization")
+          ?.replace(/^Bearer\s+/i, "")
+          .trim();
+        if (token) {
+          try {
+            const result = await client.verifyApiKey(token);
+            if (result.valid) {
+              return { authenticated: true, key: token, scopes: result.scopes };
+            }
+            return { authenticated: false, error: "Invalid API key" };
+          } catch (err) {
+            if (!(err instanceof NetworkError)) throw err;
+          }
+        }
+        return handler(req);
+      };
+    };
+  }
+
+  const defaultFail = (message: string, code?: string) => fail(message, code ?? "UNAUTHORIZED");
+
   const gate: Gate = {
     validate: validateRequest,
     ok,
@@ -106,10 +211,82 @@ export function createGate(options: GateOptions = {}): Gate {
     rateLimit: rlInstance,
     apiKeys: apiKeyValidator,
 
-    middleware() {
+    middleware(opts?: MiddlewareOptions) {
+      const {
+        auth = options.apiKeys != null && options.apiKeys.length > 0,
+        requiredScopes,
+        rateLimit: enableRl = options.rateLimit != null,
+        idempotency: enableIdem = false,
+        excludePaths = [],
+      } = opts ?? {};
+
       return async (req: Request, next?: () => Promise<Response>) => {
         if (!next) return null;
-        return next();
+
+        const path = new URL(req.url).pathname;
+        if (excludePaths.some((p) => path === p || path.startsWith(p))) {
+          return next();
+        }
+
+        // Rate limit check
+        if (enableRl) {
+          const rlResult = await rlInstance.check(req);
+          gateRateLimitStore.set(req, rlResult);
+          if (!rlResult.allowed) {
+            const body = defaultFail("Too many requests", "RATE_LIMIT_EXCEEDED");
+            return new Response(JSON.stringify(body), {
+              status: 429,
+              headers: {
+                "Content-Type": "application/json",
+                "Retry-After": String(Math.ceil((rlResult.reset - Date.now()) / 1000)),
+                "X-RateLimit-Remaining": "0",
+              },
+            });
+          }
+        }
+
+        // Auth check
+        if (auth) {
+          const authFn = apiKeyValidator.authenticate({ requiredScopes });
+          const authResult = await authFn(req);
+          if (!authResult.authenticated) {
+            const body = defaultFail(authResult.error ?? "Unauthorized", "AUTHENTICATION_ERROR");
+            return new Response(JSON.stringify(body), {
+              status: 401,
+              headers: { "Content-Type": "application/json" },
+            });
+          }
+          gateAuthStore.set(req, authResult);
+        }
+
+        // Idempotency check
+        if (enableIdem) {
+          const idemKey = req.headers.get(idempInstance.keyHeader);
+          if (idemKey) {
+            const cached = await idempInstance.getResponse(idemKey);
+            if (cached) {
+              return new Response(JSON.stringify(cached), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+              });
+            }
+            gateIdempotencyStore.set(req, idemKey);
+          }
+        }
+
+        const response = await next();
+        if (!response) return null;
+
+        // Store response for idempotency
+        if (enableIdem) {
+          const idemKey = gateIdempotencyStore.get(req);
+          if (idemKey && response.status < 500) {
+            const body = await response.clone().json();
+            await idempInstance.setResponse(idemKey, body);
+          }
+        }
+
+        return response;
       };
     },
   };

package/src/rate-limit.ts

@@ -5,6 +5,25 @@ export interface RateLimitStore {
 
 export class InMemoryRateLimitStore implements RateLimitStore {
   private store = new Map<string, { count: number; reset: number }>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor() {
+    this.cleanupInterval = setInterval(() => this.evictExpired(), 60_000);
+    if (
+      this.cleanupInterval &&
+      typeof this.cleanupInterval === "object" &&
+      "unref" in this.cleanupInterval
+    ) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  private evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.reset) this.store.delete(key);
+    }
+  }
 
   async increment(key: string, windowMs: number): Promise<{ count: number; reset: number }> {
     const now = Date.now();
@@ -23,6 +42,11 @@ export class InMemoryRateLimitStore implements RateLimitStore {
   async reset(key: string): Promise<void> {
     this.store.delete(key);
   }
+
+  dispose(): void {
+    if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+    this.store.clear();
+  }
 }
 
 export type RateLimitStrategy = "fixed" | "sliding";
@@ -35,10 +59,24 @@ export interface RateLimitOptions {
   keyFn?: (req: Request) => string;
 }
 
+/** Rate-limit by API key (Bearer token from Authorization header). Falls back to IP. */
+export function keyByApiKey(req: Request): string {
+  const auth = req.headers.get("authorization");
+  if (auth) {
+    const token = auth.replace(/^Bearer\s+/i, "").trim();
+    if (token) return `ak:${token}`;
+  }
+  return req.headers.get("x-forwarded-for") ?? "global";
+}
+
 export function rateLimit(options: RateLimitOptions = {}) {
   const windowMs = options.windowMs ?? 60_000;
   const max = options.max ?? 100;
   const store = options.store ?? new InMemoryRateLimitStore();
+
+  if (options.strategy === "sliding") {
+    throw new Error("Sliding window rate limiting is not yet implemented. Use 'fixed' (default).");
+  }
   const keyFn =
     options.keyFn ??
     ((req: Request) => {
@@ -52,8 +90,8 @@ export function rateLimit(options: RateLimitOptions = {}) {
     store,
     keyFn,
 
-    async check(req: Request): Promise<{ allowed: boolean; remaining: number; reset: number }> {
-      const key = keyFn(req);
+    async check(reqOrKey: Request | string): Promise<RateLimitCheckResult> {
+      const key = typeof reqOrKey === "string" ? reqOrKey : keyFn(reqOrKey);
       const { count, reset } = await store.increment(`rl:${key}`, windowMs);
       return {
         allowed: count <= max,
@@ -65,3 +103,9 @@ export function rateLimit(options: RateLimitOptions = {}) {
 }
 
 export type RateLimitInstance = ReturnType<typeof rateLimit>;
+
+export type RateLimitCheckResult = {
+  allowed: boolean;
+  remaining: number;
+  reset: number;
+};

package/src/stores/postgres-api-keys.test.ts

@@ -0,0 +1,86 @@
+import { expect, test } from "bun:test";
+import { PostgresApiKeyStore, type PostgresClient } from "./postgres-api-keys";
+
+function mockPostgresClient(): PostgresClient {
+  const tables: Record<string, Map<string, Record<string, unknown>>> = {};
+  return {
+    async query(sql: string, params?: unknown[]) {
+      const tableMatch = sql.match(/(?:FROM|INTO|UPDATE|TABLE)\s+(\w+)/i);
+      const tableName = tableMatch?.[1] ?? "unknown";
+      if (!tables[tableName]) tables[tableName] = new Map();
+      const table = tables[tableName];
+
+      if (sql.includes("CREATE TABLE IF NOT EXISTS")) {
+        return { rows: [] };
+      }
+
+      if (sql.includes("DELETE")) {
+        if (params?.[0]) table.delete(params[0] as string);
+        return { rows: [] };
+      }
+
+      if (sql.includes("SELECT") && sql.includes("WHERE key_hash = $1")) {
+        const keyHash = params?.[0] as string;
+        const entry = table.get(keyHash);
+        if (!entry) return { rows: [] };
+        return { rows: [entry] };
+      }
+
+      if (sql.includes("INSERT") && sql.includes("ON CONFLICT")) {
+        const keyHash = params?.[0] as string;
+        table.set(keyHash, {
+          key_hash: keyHash,
+          scopes: params?.[1],
+          metadata: params?.[2],
+          expires_at: params?.[3],
+        });
+        return { rows: [] };
+      }
+
+      return { rows: [] };
+    },
+  };
+}
+
+test("PostgresApiKeyStore validate and setKey", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresApiKeyStore(client);
+  await store.ensureTable();
+  await store.setKey({ key: "sk-live-test", scopes: ["admin"] });
+
+  const result = await store.validate("sk-live-test");
+  expect(result.authenticated).toBe(true);
+  expect(result.scopes).toEqual(["admin"]);
+});
+
+test("PostgresApiKeyStore rejects unknown key", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresApiKeyStore(client);
+  await store.ensureTable();
+  const result = await store.validate("sk-unknown");
+  expect(result.authenticated).toBe(false);
+});
+
+test("PostgresApiKeyStore rejects expired key", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresApiKeyStore(client);
+  await store.ensureTable();
+  await store.setKey({ key: "sk-expired" }, Date.now() - 1000);
+  const result = await store.validate("sk-expired");
+  expect(result.authenticated).toBe(false);
+  expect(result.error).toBe("API key expired");
+});
+
+test("PostgresApiKeyStore authenticate middleware", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresApiKeyStore(client);
+  await store.ensureTable();
+  await store.setKey({ key: "sk-auth-test", scopes: ["read"] });
+
+  const auth = store.authenticate({ requiredScopes: ["read"] });
+  const req = new Request("http://localhost", {
+    headers: { Authorization: "Bearer sk-auth-test" },
+  });
+  const result = await auth(req);
+  expect(result.authenticated).toBe(true);
+});

package/src/stores/postgres-api-keys.ts

@@ -0,0 +1,107 @@
+import type { ApiKeyEntry, AuthenticateResult } from "../api-keys";
+
+export interface PostgresClient {
+  query(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+const TABLE_NAME = "gate_api_keys";
+
+export class PostgresApiKeyStore {
+  constructor(
+    private client: PostgresClient,
+    private tableName: string = TABLE_NAME
+  ) {}
+
+  async ensureTable(): Promise<void> {
+    await this.client.query(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        key_hash TEXT PRIMARY KEY,
+        scopes TEXT,
+        metadata TEXT,
+        created_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000),
+        expires_at BIGINT
+      )
+    `);
+  }
+
+  async validate(providedKey: string): Promise<AuthenticateResult> {
+    const keyHash = await sha256(providedKey);
+    const { rows } = await this.client.query(
+      `SELECT key_hash, scopes, metadata, expires_at FROM ${this.tableName} WHERE key_hash = $1`,
+      [keyHash]
+    );
+    const row = rows[0];
+    if (!row) {
+      return { authenticated: false, error: "Invalid API key" };
+    }
+
+    const expiresAt = row.expires_at as number | null;
+    if (expiresAt && Date.now() > expiresAt) {
+      return { authenticated: false, error: "API key expired" };
+    }
+
+    const scopes = row.scopes ? (JSON.parse(row.scopes as string) as string[]) : undefined;
+    const metadata = row.metadata
+      ? (JSON.parse(row.metadata as string) as Record<string, unknown>)
+      : undefined;
+    return { authenticated: true, key: providedKey, scopes, metadata };
+  }
+
+  verify = this.validate;
+
+  authenticate(options: { requiredScopes?: string[]; header?: string } = {}) {
+    const header = options.header ?? "Authorization";
+    const requiredScopes = options.requiredScopes ?? [];
+
+    return async (req: Request): Promise<AuthenticateResult> => {
+      const authHeader = req.headers.get(header);
+      if (!authHeader) {
+        return { authenticated: false, error: "Missing API key" };
+      }
+
+      const token = authHeader.replace(/^Bearer\s+/i, "").trim();
+      const result = await this.verify(token);
+
+      if (!result.authenticated) return result;
+
+      if (requiredScopes.length > 0) {
+        const hasScopes = requiredScopes.every((s) => result.scopes?.includes(s));
+        if (!hasScopes) {
+          return { authenticated: false, error: "Insufficient permissions" };
+        }
+      }
+
+      return result;
+    };
+  }
+
+  async setKey(entry: ApiKeyEntry, expiresAt?: number): Promise<void> {
+    const keyHash = await sha256(entry.key);
+    await this.client.query(
+      `INSERT INTO ${this.tableName} (key_hash, scopes, metadata, expires_at)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (key_hash) DO UPDATE
+         SET scopes = $2, metadata = $3, expires_at = $4`,
+      [
+        keyHash,
+        entry.scopes ? JSON.stringify(entry.scopes) : null,
+        entry.metadata ? JSON.stringify(entry.metadata) : null,
+        expiresAt ?? null,
+      ]
+    );
+  }
+
+  async deleteKey(key: string): Promise<void> {
+    const keyHash = await sha256(key);
+    await this.client.query(`DELETE FROM ${this.tableName} WHERE key_hash = $1`, [keyHash]);
+  }
+}
+
+async function sha256(input: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/stores/postgres.ts

@@ -90,7 +90,13 @@ export class PostgresRateLimitStore implements RateLimitStore {
       [key, reset, now, reset]
     );
 
-    const row = rows[0]!;
+    // Best-effort locking hint to prevent write skew under concurrency.
+    // Not a full serializable isolation — for production, set the table's
+    // fillfactor low or use advisory locks.
+    await this.client.query(`SELECT pg_advisory_xact_lock(hashtext($1))`, [key]);
+
+    const row = rows[0];
+    if (!row) return { count: 0, reset: Date.now() + windowMs };
     return { count: row.count as number, reset: row.reset_at as number };
   }
 

package/src/stores/redis-api-keys.test.ts

@@ -0,0 +1,51 @@
+import { expect, test } from "bun:test";
+import { RedisApiKeyStore, type RedisClient } from "./redis-api-keys";
+
+function mockRedisClient(): RedisClient {
+  const store = new Map<string, string>();
+  return {
+    async get(key: string) {
+      return store.get(key) ?? null;
+    },
+    async hget(_key: string, _field: string) {
+      return undefined;
+    },
+    async hgetall(key: string) {
+      const val = store.get(key);
+      if (!val) return null;
+      return JSON.parse(val) as Record<string, string>;
+    },
+    async set(key: string, value: string) {
+      store.set(key, value);
+    },
+    async del(key: string) {
+      return store.delete(key) ? 1 : 0;
+    },
+  };
+}
+
+test("RedisApiKeyStore validate and setKey", async () => {
+  const client = mockRedisClient();
+  const store = new RedisApiKeyStore(client);
+  await store.setKey({ key: "sk-redis-test", scopes: ["read"] });
+
+  const result = await store.validate("sk-redis-test");
+  expect(result.authenticated).toBe(true);
+  expect(result.scopes).toEqual(["read"]);
+});
+
+test("RedisApiKeyStore rejects unknown key", async () => {
+  const client = mockRedisClient();
+  const store = new RedisApiKeyStore(client);
+  const result = await store.validate("sk-unknown");
+  expect(result.authenticated).toBe(false);
+});
+
+test("RedisApiKeyStore supports deleteKey", async () => {
+  const client = mockRedisClient();
+  const store = new RedisApiKeyStore(client);
+  await store.setKey({ key: "sk-deletable" });
+  await store.deleteKey("sk-deletable");
+  const result = await store.validate("sk-deletable");
+  expect(result.authenticated).toBe(false);
+});

package/src/stores/redis-api-keys.ts

@@ -0,0 +1,79 @@
+import type { ApiKeyEntry, AuthenticateResult } from "../api-keys";
+
+export interface RedisClient {
+  get(key: string): Promise<string | null>;
+  hget(key: string, field: string): Promise<string | undefined>;
+  hgetall(key: string): Promise<Record<string, string> | null>;
+  set(key: string, value: string, opts?: { ex?: number }): Promise<unknown>;
+  del(key: string): Promise<number>;
+}
+
+export class RedisApiKeyStore {
+  constructor(
+    private client: RedisClient,
+    private keyPrefix = "gate:apikey:"
+  ) {}
+
+  async validate(providedKey: string): Promise<AuthenticateResult> {
+    const keyHash = await sha256(providedKey);
+    const entry = await this.client.hgetall(`${this.keyPrefix}${keyHash}`);
+    if (!entry) {
+      return { authenticated: false, error: "Invalid API key" };
+    }
+    const scopes = entry.scopes ? (JSON.parse(entry.scopes) as string[]) : undefined;
+    const metadata = entry.metadata
+      ? (JSON.parse(entry.metadata) as Record<string, unknown>)
+      : undefined;
+    return { authenticated: true, key: providedKey, scopes, metadata };
+  }
+
+  verify = this.validate;
+
+  authenticate(options: { requiredScopes?: string[]; header?: string } = {}) {
+    const header = options.header ?? "Authorization";
+    const requiredScopes = options.requiredScopes ?? [];
+
+    return async (req: Request): Promise<AuthenticateResult> => {
+      const authHeader = req.headers.get(header);
+      if (!authHeader) {
+        return { authenticated: false, error: "Missing API key" };
+      }
+
+      const token = authHeader.replace(/^Bearer\s+/i, "").trim();
+      const result = await this.verify(token);
+
+      if (!result.authenticated) return result;
+
+      if (requiredScopes.length > 0) {
+        const hasScopes = requiredScopes.every((s) => result.scopes?.includes(s));
+        if (!hasScopes) {
+          return { authenticated: false, error: "Insufficient permissions" };
+        }
+      }
+
+      return result;
+    };
+  }
+
+  async setKey(entry: ApiKeyEntry): Promise<void> {
+    const keyHash = await sha256(entry.key);
+    const data: Record<string, string> = {};
+    if (entry.scopes) data.scopes = JSON.stringify(entry.scopes);
+    if (entry.metadata) data.metadata = JSON.stringify(entry.metadata);
+    await this.client.set(`${this.keyPrefix}${keyHash}`, JSON.stringify(data));
+  }
+
+  async deleteKey(key: string): Promise<void> {
+    const keyHash = await sha256(key);
+    await this.client.del(`${this.keyPrefix}${keyHash}`);
+  }
+}
+
+async function sha256(input: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/stores/redis.test.ts

@@ -29,6 +29,12 @@ function mockRedisClient(): RedisClient {
       store.set(key, { value: String(next), expires: entry.expires });
       return next;
     },
+    async ttl(key: string) {
+      const entry = store.get(key);
+      if (!entry) return -2;
+      const remaining = Math.ceil((entry.expires - Date.now()) / 1000);
+      return remaining > 0 ? remaining : -2;
+    },
     async expire(key: string, _seconds: number) {
       const entry = store.get(key);
       if (entry) {

package/src/stores/redis.ts

@@ -7,6 +7,7 @@ export interface RedisClient {
   setex(key: string, seconds: number, value: string): Promise<unknown>;
   incr(key: string): Promise<number>;
   expire(key: string, seconds: number): Promise<number>;
+  ttl(key: string): Promise<number>;
   del(key: string): Promise<number>;
 }
 
@@ -37,7 +38,6 @@ export class RedisRateLimitStore implements RateLimitStore {
   constructor(private client: RedisClient) {}
 
   async increment(key: string, windowMs: number): Promise<{ count: number; reset: number }> {
-    const now = Date.now();
     const windowSeconds = Math.ceil(windowMs / 1000);
     const count = await this.client.incr(key);
 
@@ -45,13 +45,11 @@ export class RedisRateLimitStore implements RateLimitStore {
       await this.client.expire(key, windowSeconds);
     }
 
-    const ttl = await this.client.get(key).then((v) => {
-      if (!v) return windowSeconds * 1000;
-      // approximate remaining TTL — we use incr+expire so ttl is reset
-      return windowMs;
-    });
+    const ttlSeconds = await this.client.ttl(key);
+    const remainingMs = ttlSeconds > 0 ? ttlSeconds * 1000 : windowMs;
+    const reset = Date.now() + remainingMs;
 
-    return { count, reset: now + ttl };
+    return { count, reset };
   }
 
   async reset(key: string): Promise<void> {

package/src/validate.ts

@@ -63,7 +63,7 @@ export function validateRequest(
 }
 
 export function validate(schemas: ValidationSchemas) {
-  return (req: Request) => {
+  return async (req: Request) => {
     const url = new URL(req.url);
 
     const searchParams: Record<string, string> = {};
@@ -71,8 +71,15 @@ export function validate(schemas: ValidationSchemas) {
       searchParams[k] = v;
     });
 
+    let body: unknown;
+    try {
+      body = await req.json();
+    } catch {
+      body = undefined;
+    }
+
     const result = validateRequest(schemas, {
-      body: req.body,
+      body,
       query: searchParams,
       headers: Object.fromEntries(req.headers.entries()),
     });