@joinremba/gate 0.1.0 → 0.3.0

package/README.md

@@ -162,7 +162,7 @@ Customise the key function to rate-limit by user ID, API key, or IP.
 
 ### API Keys (`@joinremba/gate/api-keys`)
 
-Validate API keys with optional scoped permissions.
+Validates API keys with optional scoped permissions. Designed for **internal** authentication — service-to-service, admin dashboards, cron jobs, webhooks. Not a replacement for user auth (OAuth, JWTs, password login).
 
 ```ts
 import { createApiKeyValidator } from "@joinremba/gate/api-keys";
@@ -182,6 +182,89 @@ const result = auth(request);
 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, 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: "9418b81169b7...", scopes: ["admin"] }], // pre-computed sha256("sk-live-123")
+  { 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`)
 
 Standard error types for consistent error handling.
@@ -313,15 +396,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.1.0",
+  "version": "0.3.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",
@@ -40,6 +40,26 @@
       "types": "./src/errors.ts",
       "import": "./src/errors.ts",
       "default": "./src/errors.ts"
+    },
+    "./stores/redis": {
+      "types": "./src/stores/redis.ts",
+      "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": [

package/src/api-keys.test.ts

@@ -0,0 +1,54 @@
+import { expect, test } from "bun:test";
+import { createApiKeyValidator } from "./api-keys";
+import type { AuthenticateResult } 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: "9418b81169b79003fd8c4481e61b79a762e996a0c172cda188c927714b5ee05b",
+        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) as Promise<AuthenticateResult>);
+  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) as Promise<AuthenticateResult>);
+  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,32 @@ 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 });
+    if (hashKeys) {
+      // Pre-compute hashes for lookup
+    }
+  }
 
   return {
     validate(providedKey: string): AuthenticateResult {
@@ -25,13 +50,58 @@ 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 keyHash = await sha256(providedKey);
+      const entry = keyMap.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 ?? [];
 
+      if (hashKeys) {
+        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;
+        };
+      }
+
       return (req: Request): AuthenticateResult => {
         const authHeader = req.headers.get(header);
         if (!authHeader) {

package/src/index.test.ts

@@ -114,3 +114,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,9 +1,9 @@
 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 { createApiKeyValidator } from "./api-keys";
-import type { ApiKeyEntry } from "./api-keys";
+import type { ApiKeyEntry, AuthenticateResult } from "./api-keys";
 import type { IdempotencyStore } from "./idempotency";
 import {
   GateError,
@@ -23,6 +23,7 @@ export {
   InMemoryStore,
   rateLimit,
   InMemoryRateLimitStore,
+  keyByApiKey,
   createApiKeyValidator,
   GateError,
   ValidationError,
@@ -52,10 +53,22 @@ 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[];
   idempotency?: {
@@ -66,10 +79,19 @@ export interface GateOptions {
   rateLimit?: {
     windowMs?: number;
     max?: number;
-    strategy?: "fixed" | "sliding";
+    store?: IdempotencyStore;
+    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,7 +101,7 @@ 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 {
@@ -96,6 +118,8 @@ export function createGate(options: GateOptions = {}): Gate {
 
   const apiKeyValidator = createApiKeyValidator(options.apiKeys ?? []);
 
+  const defaultFail = (message: string, code?: string) => fail(message, code ?? "UNAUTHORIZED");
+
   const gate: Gate = {
     validate: validateRequest,
     ok,
@@ -106,10 +130,86 @@ 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);
+          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",
+              },
+            });
+          }
+          req.headers.set("X-RateLimit-Remaining", String(rlResult.remaining));
+        }
+
+        // Auth check
+        if (auth) {
+          const authFn = apiKeyValidator.authenticate({ requiredScopes });
+          const authResult = await (authFn(req) as
+            | Promise<AuthenticateResult>
+            | AuthenticateResult);
+          if (!authResult.authenticated) {
+            const body = defaultFail(authResult.error ?? "Unauthorized", "AUTHENTICATION_ERROR");
+            return new Response(JSON.stringify(body), {
+              status: 401,
+              headers: { "Content-Type": "application/json" },
+            });
+          }
+          (req as unknown as Record<string, unknown>).gateAuth = 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" },
+              });
+            }
+            (req as unknown as Record<string, unknown>).gateIdempotencyKey = idemKey;
+          }
+        }
+
+        const response = await next();
+        if (!response) return null;
+
+        // Store response for idempotency
+        if (enableIdem) {
+          const idemKey = (req as unknown as Record<string, unknown>).gateIdempotencyKey as
+            | string
+            | undefined;
+          if (idemKey && response.status < 500) {
+            const body = await response.clone().json();
+            await idempInstance.setResponse(idemKey, body);
+          }
+        }
+
+        return response;
       };
     },
   };

package/src/rate-limit.ts

@@ -35,6 +35,16 @@ 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.slice(0, 12)}`;
+  }
+  return req.headers.get("x-forwarded-for") ?? "global";
+}
+
 export function rateLimit(options: RateLimitOptions = {}) {
   const windowMs = options.windowMs ?? 60_000;
   const max = options.max ?? 100;

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.test.ts

@@ -0,0 +1,101 @@
+import { expect, test } from "bun:test";
+import { PostgresIdempotencyStore, PostgresRateLimitStore, type PostgresClient } from "./postgres";
+
+function mockPostgresClient(): PostgresClient {
+  const tables: Record<string, Map<string, Record<string, unknown>>> = {};
+  return {
+    async query(sql: string, params?: unknown[]) {
+      // rudimentary parser for our specific SQL patterns
+      const tableMatch = sql.match(/(?:FROM|INTO|UPDATE)\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")) {
+        const keyIdx = sql.indexOf("$1");
+        if (keyIdx !== -1 && params?.[0]) {
+          table.delete(params[0] as string);
+        }
+        return { rows: [] };
+      }
+
+      if (sql.includes("SELECT") && sql.includes("WHERE key = $1")) {
+        const key = params?.[0] as string;
+        const now = (params?.[1] as number) ?? Date.now();
+        const entry = table.get(key);
+        if (!entry || (entry.expires_at as number) <= now) {
+          return { rows: [] };
+        }
+        return { rows: [entry] };
+      }
+
+      if (sql.includes("INSERT") && sql.includes("ON CONFLICT") && !sql.includes("RETURNING")) {
+        const key = params?.[0] as string;
+        const value = params?.[1] as string;
+        const expiresAt = params?.[2] as number;
+        table.set(key, { key, value, expires_at: expiresAt });
+        return { rows: [] };
+      }
+
+      if (sql.includes("INSERT") && sql.includes("ON CONFLICT") && sql.includes("RETURNING")) {
+        const key = params?.[0] as string;
+        const reset = params?.[1] as number;
+        const now = (params?.[2] as number) ?? Date.now();
+        const existing = table.get(key);
+
+        if (existing && (existing.reset_at as number) > now) {
+          existing.count = (existing.count as number) + 1;
+          return { rows: [{ count: existing.count, reset_at: existing.reset_at }] };
+        }
+
+        table.set(key, { key, count: 1, reset_at: reset });
+        return { rows: [{ count: 1, reset_at: reset }] };
+      }
+
+      return { rows: [] };
+    },
+  };
+}
+
+test("PostgresIdempotencyStore set and get", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresIdempotencyStore(client);
+  await store.ensureTable();
+  await store.set("payment:99", { id: "99", amount: 50 }, 60_000);
+  const result = await store.get("payment:99");
+  expect(result).toEqual({ id: "99", amount: 50 });
+});
+
+test("PostgresIdempotencyStore returns null for expired key", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresIdempotencyStore(client);
+  await store.ensureTable();
+  await store.set("expired-key", "value", -1);
+  const result = await store.get("expired-key");
+  expect(result).toBeNull();
+});
+
+test("PostgresRateLimitStore increment", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresRateLimitStore(client);
+  await store.ensureTable();
+  const first = await store.increment("ip:1.2.3.4", 60_000);
+  expect(first.count).toBe(1);
+  const second = await store.increment("ip:1.2.3.4", 60_000);
+  expect(second.count).toBe(2);
+});
+
+test("PostgresRateLimitStore reset", async () => {
+  const client = mockPostgresClient();
+  const store = new PostgresRateLimitStore(client);
+  await store.ensureTable();
+  await store.increment("ip:1.2.3.4", 60_000);
+  await store.reset("ip:1.2.3.4");
+  const result = await store.increment("ip:1.2.3.4", 60_000);
+  expect(result.count).toBe(1);
+});

package/src/stores/postgres.ts

@@ -0,0 +1,100 @@
+import type { IdempotencyStore } from "../idempotency";
+import type { RateLimitStore } from "../rate-limit";
+
+export interface PostgresClient {
+  query(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+const IDEMPOTENCY_TABLE = "gate_idempotency";
+const RATE_LIMIT_TABLE = "gate_rate_limits";
+
+export class PostgresIdempotencyStore implements IdempotencyStore {
+  constructor(
+    private client: PostgresClient,
+    private tableName: string = IDEMPOTENCY_TABLE
+  ) {}
+
+  async ensureTable(): Promise<void> {
+    await this.client.query(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        expires_at BIGINT NOT NULL
+      )
+    `);
+  }
+
+  async get(key: string): Promise<unknown | null> {
+    const { rows } = await this.client.query(
+      `SELECT value, expires_at FROM ${this.tableName} WHERE key = $1 AND expires_at > $2`,
+      [key, Date.now()]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    const val = row.value as string;
+    try {
+      return JSON.parse(val) as unknown;
+    } catch {
+      return val;
+    }
+  }
+
+  async set(key: string, value: unknown, ttl: number): Promise<void> {
+    const serialized = typeof value === "string" ? value : JSON.stringify(value);
+    await this.client.query(
+      `INSERT INTO ${this.tableName} (key, value, expires_at)
+       VALUES ($1, $2, $3)
+       ON CONFLICT (key) DO UPDATE SET value = $2, expires_at = $3`,
+      [key, serialized, Date.now() + ttl]
+    );
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.query(`DELETE FROM ${this.tableName} WHERE key = $1`, [key]);
+  }
+}
+
+export class PostgresRateLimitStore implements RateLimitStore {
+  constructor(
+    private client: PostgresClient,
+    private tableName: string = RATE_LIMIT_TABLE
+  ) {}
+
+  async ensureTable(): Promise<void> {
+    await this.client.query(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        key TEXT PRIMARY KEY,
+        count INTEGER NOT NULL DEFAULT 1,
+        reset_at BIGINT NOT NULL
+      )
+    `);
+  }
+
+  async increment(key: string, windowMs: number): Promise<{ count: number; reset: number }> {
+    const now = Date.now();
+    const reset = now + windowMs;
+
+    const { rows } = await this.client.query(
+      `INSERT INTO ${this.tableName} (key, count, reset_at)
+       VALUES ($1, 1, $2)
+       ON CONFLICT (key) DO UPDATE
+         SET count = CASE
+           WHEN ${this.tableName}.reset_at <= $3 THEN 1
+           ELSE ${this.tableName}.count + 1
+         END,
+         reset_at = CASE
+           WHEN ${this.tableName}.reset_at <= $3 THEN $4
+           ELSE ${this.tableName}.reset_at
+         END
+       RETURNING count, reset_at`,
+      [key, reset, now, reset]
+    );
+
+    const row = rows[0]!;
+    return { count: row.count as number, reset: row.reset_at as number };
+  }
+
+  async reset(key: string): Promise<void> {
+    await this.client.query(`DELETE FROM ${this.tableName} WHERE key = $1`, [key]);
+  }
+}

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

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test";
+import { RedisIdempotencyStore, RedisRateLimitStore, type RedisClient } from "./redis";
+
+function mockRedisClient(): RedisClient {
+  const store = new Map<string, { value: string; expires: number }>();
+  return {
+    async get(key: string) {
+      const entry = store.get(key);
+      if (!entry) return null;
+      if (Date.now() > entry.expires) {
+        store.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    async set(_key: string, _value: string, _opts?: { ex?: number }) {
+      // not used by current impl
+    },
+    async setex(key: string, seconds: number, value: string) {
+      store.set(key, { value, expires: Date.now() + seconds * 1000 });
+    },
+    async incr(key: string) {
+      const entry = store.get(key);
+      if (!entry) {
+        store.set(key, { value: "1", expires: Infinity });
+        return 1;
+      }
+      const next = Number(entry.value) + 1;
+      store.set(key, { value: String(next), expires: entry.expires });
+      return next;
+    },
+    async expire(key: string, _seconds: number) {
+      const entry = store.get(key);
+      if (entry) {
+        store.set(key, { ...entry, expires: Date.now() + _seconds * 1000 });
+        return 1;
+      }
+      return 0;
+    },
+    async del(key: string) {
+      return store.delete(key) ? 1 : 0;
+    },
+  };
+}
+
+test("RedisIdempotencyStore set and get", async () => {
+  const client = mockRedisClient();
+  const store = new RedisIdempotencyStore(client);
+  await store.set("order:42", { status: "confirmed" }, 60_000);
+  const result = await store.get("order:42");
+  expect(result).toEqual({ status: "confirmed" });
+});
+
+test("RedisIdempotencyStore returns null for missing key", async () => {
+  const client = mockRedisClient();
+  const store = new RedisIdempotencyStore(client);
+  const result = await store.get("nonexistent");
+  expect(result).toBeNull();
+});
+
+test("RedisRateLimitStore increment", async () => {
+  const client = mockRedisClient();
+  const store = new RedisRateLimitStore(client);
+  const first = await store.increment("user:1", 60_000);
+  expect(first.count).toBe(1);
+  const second = await store.increment("user:1", 60_000);
+  expect(second.count).toBe(2);
+});
+
+test("RedisRateLimitStore reset", async () => {
+  const client = mockRedisClient();
+  const store = new RedisRateLimitStore(client);
+  await store.increment("user:1", 60_000);
+  await store.reset("user:1");
+  const result = await store.increment("user:1", 60_000);
+  expect(result.count).toBe(1);
+});

package/src/stores/redis.ts

@@ -0,0 +1,60 @@
+import type { IdempotencyStore } from "../idempotency";
+import type { RateLimitStore } from "../rate-limit";
+
+export interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, opts?: { ex?: number }): Promise<unknown>;
+  setex(key: string, seconds: number, value: string): Promise<unknown>;
+  incr(key: string): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  del(key: string): Promise<number>;
+}
+
+export class RedisIdempotencyStore implements IdempotencyStore {
+  constructor(private client: RedisClient) {}
+
+  async get(key: string): Promise<unknown | null> {
+    const val = await this.client.get(key);
+    if (!val) return null;
+    try {
+      return JSON.parse(val) as unknown;
+    } catch {
+      return val;
+    }
+  }
+
+  async set(key: string, value: unknown, ttl: number): Promise<void> {
+    const serialized = typeof value === "string" ? value : JSON.stringify(value);
+    await this.client.setex(key, Math.ceil(ttl / 1000), serialized);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+}
+
+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);
+
+    if (count === 1) {
+      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;
+    });
+
+    return { count, reset: now + ttl };
+  }
+
+  async reset(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+}