@joinremba/gate 0.3.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.
@@ -191,10 +190,9 @@ if (!result.authenticated) throw new AuthenticationError(result.error);
 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 }
-);
+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"] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/gate",
-  "version": "0.3.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",
@@ -110,6 +110,7 @@
     "bun": ">=1.3.1"
   },
   "dependencies": {
+    "@joinremba/core": "^0.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/src/api-keys.test.ts

@@ -1,6 +1,5 @@
 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"] }]);
@@ -20,7 +19,7 @@ test("verify with hashKeys true hashes before lookup", async () => {
   const validator = createApiKeyValidator(
     [
       {
-        key: "9418b81169b79003fd8c4481e61b79a762e996a0c172cda188c927714b5ee05b",
+        key: "sk-live-123",
         scopes: ["admin"],
       },
     ],
@@ -38,7 +37,7 @@ test("authenticate middleware reads Authorization header", async () => {
   const req = new Request("http://localhost", {
     headers: { Authorization: "Bearer sk-test" },
   });
-  const result = await (auth(req) as Promise<AuthenticateResult>);
+  const result = await auth(req);
   expect(result.authenticated).toBe(true);
 });
 
@@ -48,7 +47,7 @@ test("authenticate rejects missing scopes", async () => {
   const req = new Request("http://localhost", {
     headers: { Authorization: "Bearer sk-test" },
   });
-  const result = await (auth(req) as Promise<AuthenticateResult>);
+  const result = await auth(req);
   expect(result.authenticated).toBe(false);
   expect(result.error).toBe("Insufficient permissions");
 });

package/src/api-keys.ts

@@ -39,9 +39,21 @@ export function createApiKeyValidator(keys: ApiKeyEntry[], options: ApiKeyValida
 
   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
+  }
+
+  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 {
@@ -62,8 +74,9 @@ export function createApiKeyValidator(keys: ApiKeyEntry[], options: ApiKeyValida
       if (!hashKeys) {
         return this.validate(providedKey);
       }
+      const cache = await ensureHashCache();
       const keyHash = await sha256(providedKey);
-      const entry = keyMap.get(keyHash);
+      const entry = cache.get(keyHash);
       if (!entry) {
         return { authenticated: false, error: "Invalid API key" };
       }
@@ -79,37 +92,14 @@ export function createApiKeyValidator(keys: ApiKeyEntry[], options: ApiKeyValida
       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 => {
+      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", () => {

package/src/index.ts

@@ -2,9 +2,28 @@ import { validateRequest } from "./validate";
 import { ok, fail, paginated, problem } from "./respond";
 import { idempotency, InMemoryStore } from "./idempotency";
 import { rateLimit, InMemoryRateLimitStore, keyByApiKey } from "./rate-limit";
+import type { RateLimitStore, RateLimitCheckResult } from "./rate-limit";
 import { createApiKeyValidator } 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,
@@ -71,6 +90,7 @@ export interface MiddlewareOptions {
 
 export interface GateOptions {
   apiKeys?: ApiKeyEntry[];
+  client?: Client;
   idempotency?: {
     store?: IdempotencyStore;
     keyHeader?: string;
@@ -79,7 +99,7 @@ export interface GateOptions {
   rateLimit?: {
     windowMs?: number;
     max?: number;
-    store?: IdempotencyStore;
+    store?: RateLimitStore;
     keyFn?: (req: Request) => string;
   };
 }
@@ -105,6 +125,8 @@ export interface Gate {
 }
 
 export function createGate(options: GateOptions = {}): Gate {
+  const client = options.client;
+
   const idempInstance = idempotency({
     store: options.idempotency?.store ?? new InMemoryStore(),
     keyHeader: options.idempotency?.keyHeader,
@@ -114,10 +136,69 @@ 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 = {
@@ -150,6 +231,7 @@ export function createGate(options: GateOptions = {}): Gate {
         // 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), {
@@ -161,15 +243,12 @@ export function createGate(options: GateOptions = {}): Gate {
               },
             });
           }
-          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);
+          const authResult = await authFn(req);
           if (!authResult.authenticated) {
             const body = defaultFail(authResult.error ?? "Unauthorized", "AUTHENTICATION_ERROR");
             return new Response(JSON.stringify(body), {
@@ -177,7 +256,7 @@ export function createGate(options: GateOptions = {}): Gate {
               headers: { "Content-Type": "application/json" },
             });
           }
-          (req as unknown as Record<string, unknown>).gateAuth = authResult;
+          gateAuthStore.set(req, authResult);
         }
 
         // Idempotency check
@@ -191,7 +270,7 @@ export function createGate(options: GateOptions = {}): Gate {
                 headers: { "Content-Type": "application/json" },
               });
             }
-            (req as unknown as Record<string, unknown>).gateIdempotencyKey = idemKey;
+            gateIdempotencyStore.set(req, idemKey);
           }
         }
 
@@ -200,9 +279,7 @@ export function createGate(options: GateOptions = {}): Gate {
 
         // Store response for idempotency
         if (enableIdem) {
-          const idemKey = (req as unknown as Record<string, unknown>).gateIdempotencyKey as
-            | string
-            | undefined;
+          const idemKey = gateIdempotencyStore.get(req);
           if (idemKey && response.status < 500) {
             const body = await response.clone().json();
             await idempInstance.setResponse(idemKey, body);

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";
@@ -40,7 +64,7 @@ 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)}`;
+    if (token) return `ak:${token}`;
   }
   return req.headers.get("x-forwarded-for") ?? "global";
 }
@@ -49,6 +73,10 @@ 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) => {
@@ -62,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,
@@ -75,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.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.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()),
     });