@joinremba/gate 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/gate",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -60,6 +60,11 @@
       "types": "./src/stores/postgres-api-keys.ts",
       "import": "./src/stores/postgres-api-keys.ts",
       "default": "./src/stores/postgres-api-keys.ts"
+    },
+    "./adapters/hono": {
+      "types": "./src/adapters/hono.ts",
+      "import": "./src/adapters/hono.ts",
+      "default": "./src/adapters/hono.ts"
     }
   },
   "files": [
@@ -110,6 +115,7 @@
     "bun": ">=1.3.1"
   },
   "dependencies": {
+    "@joinremba/core": "^0.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/src/adapters/hono.ts

@@ -0,0 +1,134 @@
+import { createMiddleware } from "hono/factory";
+import type { Gate, MiddlewareOptions } from "../index";
+import type { Context, Next } from "hono";
+
+type HonoRateLimitOptions = {
+  gate: Gate;
+  limit: number;
+  windowMs: number;
+  keyPrefix: string;
+  message?: string;
+  getKey?: (c: Context) => string;
+};
+
+/**
+ * Create a Hono rate-limit middleware from a Gate instance.
+ * Sets X-RateLimit-Remaining header and returns 429 with Retry-After when exceeded.
+ */
+export function createRateLimiter({
+  gate,
+  limit: max,
+  windowMs,
+  keyPrefix,
+  message = "Too many requests",
+  getKey,
+}: HonoRateLimitOptions) {
+  return createMiddleware(async (c: Context, next: Next) => {
+    const identifier = getKey
+      ? getKey(c)
+      : ((c as Record<string, unknown>).var as Record<string, unknown>).clientIp ??
+        c.req.header("x-forwarded-for") ??
+        "unknown";
+
+    const result = await gate.rateLimit.check(`${keyPrefix}:${identifier}`);
+
+    if (!result.allowed) {
+      return c.json(
+        { success: false, error: { message, code: "RATE_LIMIT_EXCEEDED" } },
+        429,
+        {
+          "Retry-After": String(Math.ceil((result.reset - Date.now()) / 1000)),
+          "X-RateLimit-Remaining": "0",
+        }
+      );
+    }
+
+    c.res.headers.set("X-RateLimit-Remaining", String(result.remaining));
+    await next();
+  });
+}
+
+type HonoIdempotencyOptions = {
+  gate: Gate;
+  keyHeader?: string;
+};
+
+/**
+ * Create a Hono idempotency middleware from a Gate instance.
+ * Requires Idempotency-Key header on mutating requests.
+ * Returns cached response on repeat requests. Stores response after handler completes.
+ */
+export function requireIdempotencyKey({
+  gate,
+  keyHeader = "Idempotency-Key",
+}: HonoIdempotencyOptions) {
+  const KEY_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;
+
+  return createMiddleware(async (c: Context, next: Next) => {
+    const safeMethods = ["GET", "HEAD", "OPTIONS"];
+    if (safeMethods.includes(c.req.method)) {
+      await next();
+      return;
+    }
+
+    const key = c.req.header(keyHeader)?.trim() ?? "";
+    if (!key) {
+      return c.json(
+        {
+          success: false,
+          error: { message: `${keyHeader} header is required`, code: "BAD_REQUEST" },
+        },
+        400
+      );
+    }
+    if (!KEY_PATTERN.test(key)) {
+      return c.json(
+        {
+          success: false,
+          error: {
+            message: `${keyHeader} must be 8-128 chars (letters, numbers, ., _, :, -)`,
+            code: "BAD_REQUEST",
+          },
+        },
+        400
+      );
+    }
+
+    const cached = await gate.idempotency.getResponse(key);
+    if (cached) {
+      return c.json(cached, 200);
+    }
+
+    const originalJson = c.json.bind(c);
+    (c.json as any) = (
+      body: unknown,
+      status?: number,
+      headers?: Record<string, string>
+    ) => {
+      if (status === undefined || status < 500) {
+        gate.idempotency.setResponse(key, body).catch(() => {});
+      }
+      return originalJson(body, status as number, headers);
+    };
+
+    await next();
+  });
+}
+
+/**
+ * Hono middleware wrapper for Gate's combined middleware.
+ */
+export function gateMiddleware(gate: Gate, opts?: MiddlewareOptions) {
+  const mw = gate.middleware(opts);
+  return createMiddleware(async (c: Context, next: Next) => {
+    const req = new Request(c.req.raw);
+    const res = await mw(req, async () => {
+      await next();
+      return c.res;
+    });
+    if (res && res.status !== 200) {
+      const body = await res.json();
+      return c.json(body, res.status as 200 | 400 | 401 | 429 | 500);
+    }
+  });
+}

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

@@ -1,12 +1,48 @@
 import type { IdempotencyStore } from "../idempotency";
 import type { RateLimitStore } from "../rate-limit";
 
+/**
+ * Adapt an ioredis-compatible Redis instance to the Gate RedisClient interface.
+ *
+ * Usage:
+ *   import Redis from "ioredis";
+ *   import { fromIORedis, RedisIdempotencyStore } from "@joinremba/gate/stores/redis";
+ *
+ *   const redis = new Redis();
+ *   const adapted = fromIORedis(redis);
+ *   const store = new RedisIdempotencyStore(adapted);
+ *
+ * The adapter expects an object with the following methods matching ioredis's
+ * signature: `get`, `set`, `setex`, `incr`, `expire`, `ttl`, `del`.
+ */
+export function fromIORedis(client: {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<unknown>;
+  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(...keys: string[]): Promise<number>;
+}): RedisClient {
+  return {
+    get: (key) => client.get(key),
+    set: (key, value, opts) =>
+      opts?.ex ? client.setex(key, opts.ex, value) : client.set(key, value) as Promise<unknown>,
+    setex: (key, seconds, value) => client.setex(key, seconds, value),
+    incr: (key) => client.incr(key),
+    expire: (key, seconds) => client.expire(key, seconds),
+    ttl: (key) => client.ttl(key),
+    del: (key) => client.del(key),
+  };
+}
+
 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>;
+  ttl(key: string): Promise<number>;
   del(key: string): Promise<number>;
 }
 
@@ -37,7 +73,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 +80,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> {