@joinremba/gate 0.1.0 → 0.2.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,10 @@ 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, extend with a DB-backed validator (e.g. query Postgres with `SELECT * FROM api_keys WHERE key_hash = $1`).
+
 ### Errors (`@joinremba/gate/errors`)
 
 Standard error types for consistent error handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/gate",
-  "version": "0.1.0",
+  "version": "0.2.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,16 @@
       "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/postgres": {
+      "types": "./src/stores/postgres.ts",
+      "import": "./src/stores/postgres.ts",
+      "default": "./src/stores/postgres.ts"
     }
   },
   "files": [

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.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);
+  }
+}