@joinremba/gate 0.5.1 → 0.5.2

package/README.md

@@ -1,32 +1,36 @@
 # @joinremba/gate
 
-[![npm version](https://img.shields.io/npm/v/@joinremba/gate.svg)](https://www.npmjs.com/package/@joinremba/gate)
-[![license](https://img.shields.io/npm/l/@joinremba/gate.svg)](https://github.com/joinremba/gate/blob/main/LICENSE)
-[![bun](https://img.shields.io/badge/bun-%3E%3D1.3.1-black)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@joinremba/gate?color=blue&label=npm)](https://www.npmjs.com/package/@joinremba/gate)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-API safety layer for TypeScript backends — request validation, structured responses, idempotency, rate limiting, and API key authentication. Pluggable stores (in-memory, Redis, PostgreSQL). Framework-agnostic — operates on plain `Request`/`Response`.
+**API safety layer for TypeScript backends.** Validate requests, format structured responses, prevent duplicate processing, rate-limit endpoints, and manage API keys — all with first-class TypeScript types and Zod schemas.
+
+---
 
 ## Features
 
-- **Request validation** with Zod schemas (body, query, params, headers)
-- **Structured response helpers** — `ok()`, `fail()`, `paginated()`, `problem()` (RFC 9457)
-- **Idempotency middleware** with pluggable stores (InMemory, Redis, Postgres)
-- **Rate limiting** with fixed-window stores (InMemory, Redis, Postgres)
-- **API key authentication** with scopes, SHA-256 hashing, and expiry
-- **Combined middleware** — auth + rate limit + idempotency in one pass
-- **WeakMap side-channel** for pass-through state (`getGateAuth`, `getGateRateLimit`, `getGateIdempotencyKey`)
-- **Rich error hierarchy** — `GateError`, `ValidationError`, `AuthenticationError`, `RateLimitError`, `IdempotencyError`
-- **Remote delegation** via `client` option (connect to [Nexus](https://github.com/joinremba))
-- **Pluggable stores** — swap implementations via interfaces
-- **Auto-migration** for Postgres stores (`ensureTable()`)
-- **Zero framework dependency** — works with Hono, Express, Elysia, Bun, Node `http`, or plain fetch
+- **Request validation** — Validate `body`, `query`, `params`, and `headers` with Zod schemas
+- **Structured responses** — Consistent `ok`, `fail`, `paginated`, and RFC 9457 `problem` response shapes
+- **Rate limiting** — In-memory store included; pluggable Redis and Postgres stores for production
+- **Idempotency** — Prevent duplicate processing with idempotency keys (`Idempotency-Key` header)
+- **API keys** — Validate, hash, scope-check, and authenticate API keys from memory, Redis, or Postgres
+- **Framework agnostic** — Core works with any runtime/framework; official Hono adapter included
+- **Middleware** — Drop-in `gate.middleware()` for auth + rate limiting + idempotency in one call
+- **TypeScript strict** — Full type inference with `strict: true` and Zod 4
+- **Tree-shakeable** — Deep imports for every module; import only what you need
+
+---
 
 ## Installation
 
-```bash
+```sh
 bun add @joinremba/gate
 ```
 
+Requires **Bun >= 1.3.1** and **Zod ^4.4.2** (installed automatically).
+
+---
+
 ## Quick Start
 
 ```ts
@@ -34,304 +38,381 @@ import { createGate } from "@joinremba/gate";
 import { z } from "zod";
 
 const gate = createGate({
-  apiKeys: [{ key: "sk-admin", scopes: ["admin"] }],
-  rateLimit: { windowMs: 60_000, max: 100 },
-  idempotency: { ttl: 86_400_000 },
+  apiKeys: [{ key: "sk-secret-123", scopes: ["read"] }],
+  rateLimit: { windowMs: 60_000, max: 10 },
 });
 
-// Validate a request body
-const userSchema = z.object({ email: z.string().email() });
-const result = gate.validate({ body: userSchema }, { body: { email: "test@example.com" } });
+// Validate an incoming request
+const result = gate.validate({ body: z.object({ name: z.string() }) }, { body: { name: "Alice" } });
 
-// Check rate limit
-const rl = await gate.rateLimit.check(new Request("http://localhost"));
-// => { allowed: boolean, remaining: number, reset: number }
-
-// Authenticate an API key
-const auth = await gate.apiKeys.authenticate({ requiredScopes: ["admin"] })(
-  new Request("http://localhost", { headers: { Authorization: "Bearer sk-admin" } })
-);
-// => { authenticated: true, key: "sk-admin", scopes: ["admin"] }
-
-// Combined middleware (Hono / Express / Bun serve)
-app.use(gate.middleware({ auth: true, rateLimit: true, idempotency: true }));
-```
-
-## createGate
-
-The main factory. Accepts an options object and returns a `Gate` instance with all modules wired together.
-
-```ts
-import { createGate } from "@joinremba/gate";
+if (!result.success) {
+  return gate.fail("Validation failed", "VALIDATION_ERROR", result.errors);
+}
 
-const gate = createGate({
-  // API key authentication
-  apiKeys?: ApiKeyEntry[];
-
-  // Remote delegation — delegate checks to Nexus
-  client?: Client;
-
-  // Idempotency configuration
-  idempotency?: {
-    store?: IdempotencyStore;   // default: new InMemoryStore()
-    keyHeader?: string;         // default: "Idempotency-Key"
-    ttl?: number;               // default: 86_400_000 (24 hours)
-  };
-
-  // Rate limiting configuration
-  rateLimit?: {
-    windowMs?: number;          // default: 60_000
-    max?: number;               // default: 100
-    store?: RateLimitStore;     // default: new InMemoryRateLimitStore()
-    keyFn?: (req: Request) => string;
-  };
-});
+return gate.ok({ name: result.data.body.name });
 ```
 
-**Returns:**
-
-| Property | Type | Description |
-|---|---|---|
-| `gate.validate` | `typeof validateRequest` | Validate body/query/params/headers with Zod |
-| `gate.ok` | `typeof ok` | Structured success response |
-| `gate.fail` | `typeof fail` | Structured error response |
-| `gate.paginated` | `typeof paginated` | Paginated response |
-| `gate.problem` | `typeof problem` | RFC 9457 problem detail |
-| `gate.idempotency` | `IdempotencyInstance` | Idempotency guard (`getResponse`/`setResponse`) |
-| `gate.rateLimit` | `RateLimitInstance` | Rate limiter (`check`) |
-| `gate.apiKeys` | `ApiKeyValidator` | API key validator (`validate`/`verify`/`authenticate`) |
-| `gate.middleware` | `Middleware` | Combined middleware function |
+---
 
 ## Validation
 
-Validate request body, query, params, and headers against Zod schemas.
+Validation uses [Zod](https://zod.dev) schemas. The `validate()` method accepts an object with optional `body`, `query`, `params`, and `headers` schemas.
 
 ```ts
-import { validateRequest, validate } from "@joinremba/gate";
-import { z } from "zod";
+import { validateRequest } from "@joinremba/gate/validate";
+// or via gate instance:
+// gate.validate(schemas, request)
+
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
 
-// Low-level: pass parsed input directly
 const result = validateRequest(
   {
-    body: z.object({ email: z.string().email() }),
-    query: z.object({ page: z.coerce.number() }),
+    body: UserSchema,
+    query: z.object({ page: z.coerce.number().optional() }),
+    headers: z.object({ "x-request-id": z.string().optional() }),
   },
   {
-    body: { email: "test@example.com" },
-    query: { page: "1" },
+    body: { name: "Alice", email: "alice@example.com" },
+    query: { page: "2" },
+    params: { id: "123" },
+    headers: { "x-request-id": "abc-123" },
   }
 );
-// => { success: true, data: { body: { email: '...' }, query: { page: 1 } } }
-// or { success: false, errors: { body: ['body.email: Invalid email'] } }
-
-// Bind to a standard Request
-const validateReq = validate({ body: z.object({ email: z.string().email() }) });
-const result = await validateReq(new Request("http://localhost", {
-  method: "POST",
-  body: JSON.stringify({ email: "test@example.com" }),
-  headers: { "Content-Type": "application/json" },
-}));
+
+if (!result.success) {
+  // result.errors → { body: ["body.name: Required"], query: [...] }
+  console.error(result.errors);
+} else {
+  // result.data → { body: { name: "Alice", ... }, query: { page: 2 } }
+  console.log(result.data);
+}
 ```
 
-## Response Helpers
+The standalone `validate(schemas)` function also accepts a `Request` object directly, parsing the JSON body and URL search params automatically:
 
 ```ts
-import { ok, fail, paginated, problem } from "@joinremba/gate";
+import { validate } from "@joinremba/gate/validate";
 
-ok(userData);
-// { success: true, data: userData }
+const middleware = async (req: Request) => {
+  const result = await validate({
+    body: z.object({ title: z.string() }),
+    query: z.object({ limit: z.coerce.number() }),
+  })(req);
 
-fail("Not found", "NOT_FOUND");
-// { success: false, error: { message: "Not found", code: "NOT_FOUND" } }
+  if (!result.success) return new Response("Invalid", { status: 400 });
+  // ...
+};
+```
 
-fail("Invalid input", "VALIDATION_ERROR", { field: "email" });
-// { success: false, error: { message: "Invalid input", code: "VALIDATION_ERROR", details: { field: "email" } } }
+---
 
-paginated(items, 100, 1, 20);
-// { success: true, data: items, pagination: { total: 100, page: 1, limit: 20, pages: 5 } }
+## Responses
 
-problem({ type: "/errors/rate-limit", title: "Rate Limit Exceeded", status: 429, detail: "..." });
-// { success: false, error: { message: "Rate Limit Exceeded", ... }, problem: { type, title, status, detail } }
-```
+All response helpers return plain objects — serialise them however you like (JSON, Hono `c.json()`, etc.).
 
-## Idempotency
+### `ok(data)`
+
+```ts
+gate.ok({ id: 1, name: "Alice" });
+// → { success: true, data: { id: 1, name: "Alice" } }
+```
 
-Prevent duplicate processing by storing responses keyed by an idempotency key (default `Idempotency-Key` header).
+### `fail(message, code?, details?)`
 
 ```ts
-import { idempotency, InMemoryStore } from "@joinremba/gate";
+gate.fail("Not found", "NOT_FOUND");
+// → { success: false, error: { message: "Not found", code: "NOT_FOUND" } }
 
-const guard = idempotency({ store: new InMemoryStore(), ttl: 86_400_000 });
+gate.fail("Validation error", "VALIDATION_ERROR", { name: ["Required"] });
+// → { success: false, error: { message: "Validation error", code: "VALIDATION_ERROR", details: { name: ["Required"] } } }
+```
 
-// Check if a response was already cached
-const cached = await guard.getResponse("unique-key");
-if (!cached) {
-  const response = { success: true, data: await processPayment() };
-  await guard.setResponse("unique-key", response);
-}
+### `paginated(data, total, page, limit)`
+
+```ts
+gate.paginated([{ id: 1 }], 42, 1, 10);
+// → { success: true, data: [...], pagination: { total: 42, page: 1, limit: 10, pages: 5 } }
 ```
 
-**Via `createGate`:**
+### `problem(detail)` — RFC 9457 Problem Details
 
 ```ts
-const gate = createGate({ idempotency: { ttl: 86_400_000 } });
-const cached = await gate.idempotency.getResponse("key");
-if (!cached) {
-  await gate.idempotency.setResponse("key", response);
-}
+gate.problem({
+  type: "https://api.example.com/errors/rate-limit",
+  title: "Rate Limit Exceeded",
+  status: 429,
+  detail: "Too many requests. Retry after 30 seconds.",
+  instance: "/api/orders",
+});
+// → { success: false, error: { ... }, problem: { type, title, status, detail, instance } }
 ```
 
+---
+
 ## Rate Limiting
 
-```ts
-import { rateLimit, InMemoryRateLimitStore, keyByApiKey } from "@joinremba/gate";
+### Basic usage
 
-const limiter = rateLimit({ windowMs: 60_000, max: 100 });
+```ts
+import { createGate, InMemoryRateLimitStore } from "@joinremba/gate";
 
-// Check a standard Request (keyed by IP via x-forwarded-for)
-const result = await limiter.check(new Request("http://localhost"));
-// { allowed: boolean, remaining: number, reset: number }
+const gate = createGate({
+  rateLimit: {
+    windowMs: 60_000, // 1 minute window
+    max: 100, // 100 requests per window
+    // store: customStore // optional — defaults to InMemoryRateLimitStore
+  },
+});
 
-// Check with a custom key string
-const result = await limiter.check("user:42");
+// Usage
+const result = await gate.rateLimit.check(request);
+// → { allowed: boolean, remaining: number, reset: number (epoch ms) }
 
-// Key by API key (Bearer token) instead of IP
-const limiter2 = rateLimit({ keyFn: keyByApiKey });
+if (!result.allowed) {
+  return gate.fail("Too many requests", "RATE_LIMIT_EXCEEDED");
+}
 ```
 
-**Via `createGate`:**
+### Custom key function
 
 ```ts
-const gate = createGate({ rateLimit: { windowMs: 60_000, max: 100 } });
-const result = await gate.rateLimit.check(req);
+const gate = createGate({
+  rateLimit: {
+    keyFn: (req) => req.headers.get("x-api-key") ?? "anonymous",
+  },
+});
 ```
 
-## API Keys
+### Redis store
 
 ```ts
-import { createApiKeyValidator } from "@joinremba/gate";
+import { Redis, type Redis as RedisType } from "ioredis";
+import { fromIORedis, RedisRateLimitStore } from "@joinremba/gate/stores/redis";
 
-const validator = createApiKeyValidator([
-  { key: "sk-admin", scopes: ["admin"] },
-  { key: "sk-read", scopes: ["read"] },
-]);
+const client = new Redis();
+const redisClient = fromIORedis(client);
 
-// Direct key validation
-const result = validator.validate("sk-admin");
-// { authenticated: true, key: "sk-admin", scopes: ["admin"] }
-
-// Verifying against hashed keys (SHA-256)
-const hashedValidator = createApiKeyValidator(
-  [{ key: "sk-admin", scopes: ["admin"] }],
-  { hashKeys: true }
-);
-const result = await hashedValidator.verify("sk-admin");
-
-// Request authentication with scope checking
-const authFn = validator.authenticate({ requiredScopes: ["admin"] });
-const result = await authFn(new Request("http://localhost", {
-  headers: { Authorization: "Bearer sk-admin" },
-}));
+const gate = createGate({
+  rateLimit: {
+    store: new RedisRateLimitStore(redisClient),
+    windowMs: 60_000,
+    max: 1000,
+  },
+});
 ```
 
-**Via `createGate`:**
+### Postgres store
 
 ```ts
-const gate = createGate({ apiKeys: [{ key: "sk-admin", scopes: ["admin"] }] });
-const result = await gate.apiKeys.verify("sk-admin");
+import { PostgresRateLimitStore } from "@joinremba/gate/stores/postgres";
+import { sql } from "your-pg-client";
+
+const store = new PostgresRateLimitStore({ query: sql.query.bind(sql) });
+await store.ensureTable(); // creates gate_rate_limits table
 ```
 
-## Combined Middleware
+---
+
+## Idempotency
 
-Run auth, rate limiting, and idempotency in a single pass. Returns a middleware function compatible with any framework.
+Prevent duplicate processing by storing responses keyed by an `Idempotency-Key` header.
 
 ```ts
-const middleware = gate.middleware({
-  auth: true,                     // authenticate API keys (auto-enabled if apiKeys configured)
-  requiredScopes: ["admin"],      // scope check
-  rateLimit: true,                // rate limit (auto-enabled if rateLimit configured)
-  idempotency: true,              // check Idempotency-Key header
-  rateLimitMax: 50,               // override max for this specific middleware
-  excludePaths: ["/health", "/webhook"],  // skip entirely
+const gate = createGate({
+  idempotency: {
+    // store: customStore   — defaults to InMemoryStore
+    keyHeader: "Idempotency-Key", // default
+    ttl: 86_400_000, // 24 hours (default)
+  },
 });
+
+// Check for cached response
+const cached = await gate.idempotency.getResponse(key);
+if (cached) {
+  return cached; // return previous response
+}
+
+// ... process request ...
+
+// Store the response
+await gate.idempotency.setResponse(key, responseData);
 ```
 
-**Play nice with Hono:**
+### Redis store
 
 ```ts
-import { Hono } from "hono";
-const app = new Hono();
-app.use("*", (c, next) => gate.middleware()(c.req.raw, () => next()));
+import { Redis } from "ioredis";
+import { fromIORedis, RedisIdempotencyStore } from "@joinremba/gate/stores/redis";
+
+const client = new Redis();
+const redisClient = fromIORedis(client);
+
+const gate = createGate({
+  idempotency: {
+    store: new RedisIdempotencyStore(redisClient),
+  },
+});
 ```
 
-**Access pass-through state via WeakMap:**
+### Postgres store
 
 ```ts
-import { getGateAuth, getGateRateLimit, getGateIdempotencyKey } from "@joinremba/gate";
+import { PostgresIdempotencyStore } from "@joinremba/gate/stores/postgres";
 
-// Inside your request handler
-const auth = getGateAuth(req);           // { authenticated, key, scopes }
-const rl = getGateRateLimit(req);        // { allowed, remaining, reset }
-const idemKey = getGateIdempotencyKey(req); // string | undefined
+const store = new PostgresIdempotencyStore({ query: sql.query.bind(sql) });
+await store.ensureTable(); // creates gate_idempotency table
 ```
 
-## Stores
+---
 
-### InMemory (default)
+## API Keys
 
-Built-in stores for development and single-process deployments.
+### In-memory validation
 
 ```ts
-import { InMemoryStore, InMemoryRateLimitStore } from "@joinremba/gate";
+const gate = createGate({
+  apiKeys: [
+    { key: "sk-test-1", scopes: ["read", "write"] },
+    { key: "sk-test-2", scopes: ["read"] },
+  ],
+});
+
+// Direct validation
+const result = gate.apiKeys.validate("sk-test-1");
+// → { authenticated: true, key: "sk-test-1", scopes: ["read", "write"] }
 
-const idemStore = new InMemoryStore();
-const rlStore = new InMemoryRateLimitStore();
+// Authenticate from a Request (extracts Bearer token from Authorization header)
+const authenticate = gate.apiKeys.authenticate({ requiredScopes: ["read"] });
+const authResult = await authenticate(request);
+// → { authenticated: true, key: "sk-test-1", scopes: [...], metadata: {...} }
 ```
 
-### Redis
+### Redis store
 
 ```ts
-import { RedisIdempotencyStore, RedisRateLimitStore } from "@joinremba/gate/stores/redis";
+import { Redis } from "ioredis";
 import { RedisApiKeyStore } from "@joinremba/gate/stores/redis-api-keys";
-import type { RedisClient } from "@joinremba/gate/stores/redis";
-
-// Use with any Redis client that implements the RedisClient interface
-const client: RedisClient = {
-  get: (key) => redis.get(key),
-  setex: (key, sec, val) => redis.setex(key, sec, val),
-  incr: (key) => redis.incr(key),
-  expire: (key, sec) => redis.expire(key, sec),
-  ttl: (key) => redis.ttl(key),
-  del: (key) => redis.del(key),
-};
 
-const idemStore = new RedisIdempotencyStore(client);
-const rlStore = new RedisRateLimitStore(client);
-const apiKeyStore = new RedisApiKeyStore(client);
+const client = new Redis();
+const store = new RedisApiKeyStore(client);
+
+// Add a key
+await store.setKey({ key: "sk-redis-1", scopes: ["admin"] });
+
+// Validate
+const result = await store.validate("sk-redis-1");
+
+// Authenticate from request
+const authenticate = store.authenticate({ requiredScopes: ["admin"] });
+const authResult = await authenticate(request);
 ```
 
-### PostgreSQL
+### Postgres store
 
 ```ts
-import { PostgresIdempotencyStore, PostgresRateLimitStore } from "@joinremba/gate/stores/postgres";
 import { PostgresApiKeyStore } from "@joinremba/gate/stores/postgres-api-keys";
-import type { PostgresClient } from "@joinremba/gate/stores/postgres";
 
-const sql: PostgresClient = {
-  query: (text, params) => pool.query(text, params),
-};
+const store = new PostgresApiKeyStore({ query: sql.query.bind(sql) });
+await store.ensureTable(); // creates gate_api_keys table
+
+await store.setKey({ key: "sk-pg-1", scopes: ["read"] });
+const result = await store.validate("sk-pg-1");
+```
+
+---
+
+## Hono Adapter
+
+The `@joinremba/gate/adapters/hono` module provides first-class middleware for [Hono](https://hono.dev).
+
+```ts
+import { Hono } from "hono";
+import { createGate } from "@joinremba/gate";
+import {
+  createRateLimiter,
+  requireIdempotencyKey,
+  gateMiddleware,
+} from "@joinremba/gate/adapters/hono";
 
-const idemStore = new PostgresIdempotencyStore(sql);
-const rlStore = new PostgresRateLimitStore(sql);
-const apiKeyStore = new PostgresApiKeyStore(sql);
+const gate = createGate({
+  apiKeys: [{ key: "sk-hono-1", scopes: ["read"] }],
+  rateLimit: { windowMs: 60_000, max: 30 },
+  idempotency: { ttl: 86_400_000 },
+});
+
+const app = new Hono();
 
-// Auto-create tables
-await idemStore.ensureTable();
-await rlStore.ensureTable();
-await apiKeyStore.ensureTable();
+// Standalone rate limiter middleware (limit/windowMs from gate config)
+app.use(
+  "/api/*",
+  createRateLimiter({
+    gate,
+    keyPrefix: "api",
+    getKey: (c) => c.req.header("x-forwarded-for") ?? "unknown",
+  })
+);
+
+// Standalone idempotency middleware
+app.post("/api/orders", requireIdempotencyKey({ gate }), async (c) => {
+  // ...
+  return c.json(gate.ok({ orderId: "ord_123" }), 201);
+});
+
+// Combined middleware (auth + rate limit + idempotency)
+app.use(
+  "/admin/*",
+  gateMiddleware(gate, {
+    auth: true,
+    requiredScopes: ["admin"],
+    rateLimit: true,
+    idempotency: true,
+  })
+);
+
+app.get("/api/health", (c) => c.json(gate.ok({ status: "ok" })));
+
+export default app;
 ```
 
-## Error Classes
+### Adapter API
+
+| Middleware              | Description                                              |
+| ----------------------- | -------------------------------------------------------- |
+| `createRateLimiter`     | Rate-limit by a custom key (window/max from gate config) |
+| `requireIdempotencyKey` | Validates `Idempotency-Key` header, caches responses     |
+| `gateMiddleware`        | All-in-one: auth + rate limit + idempotency              |
+
+---
+
+## Deep Imports
+
+Every module can be imported individually for tree-shaking and direct use:
+
+| Subpath Export                             | Exports                                                                                                    |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `@joinremba/gate`                          | `createGate`, `validateRequest`, `ok`, `fail`, `paginated`, `problem`, types                               |
+| `@joinremba/gate/validate`                 | `validateRequest`, `validate`, types                                                                       |
+| `@joinremba/gate/respond`                  | `ok`, `fail`, `paginated`, `problem`, types                                                                |
+| `@joinremba/gate/idempotency`              | `idempotency`, `InMemoryStore`, types                                                                      |
+| `@joinremba/gate/rate-limit`               | `rateLimit`, `InMemoryRateLimitStore`, `keyByApiKey`, types                                                |
+| `@joinremba/gate/api-keys`                 | `createApiKeyValidator`, types                                                                             |
+| `@joinremba/gate/errors`                   | `GateError`, `ValidationError`, `AuthenticationError`, `RateLimitError`, `IdempotencyError`, `isGateError` |
+| `@joinremba/gate/stores/redis`             | `fromIORedis`, `RedisIdempotencyStore`, `RedisRateLimitStore`                                              |
+| `@joinremba/gate/stores/redis-api-keys`    | `RedisApiKeyStore`                                                                                         |
+| `@joinremba/gate/stores/postgres`          | `PostgresIdempotencyStore`, `PostgresRateLimitStore`                                                       |
+| `@joinremba/gate/stores/postgres-api-keys` | `PostgresApiKeyStore`                                                                                      |
+| `@joinremba/gate/adapters/hono`            | `createRateLimiter`, `requireIdempotencyKey`, `gateMiddleware`                                             |
+
+---
+
+## Error Handling
+
+Gate throws typed errors for programmatic handling, and the `fail()` helper for HTTP responses.
+
+### Error classes
 
 ```ts
 import {
@@ -340,55 +421,96 @@ import {
   AuthenticationError,
   RateLimitError,
   IdempotencyError,
-} from "@joinremba/gate";
+  isGateError,
+} from "@joinremba/gate/errors";
+```
 
-// Base class
-throw new GateError("Something went wrong", "INTERNAL_ERROR", 500);
+| Class                 | Code                   | Status | Description                    |
+| --------------------- | ---------------------- | ------ | ------------------------------ |
+| `GateError`           | (custom)               | 500    | Base error class               |
+| `ValidationError`     | `VALIDATION_ERROR`     | 400    | Invalid request data           |
+| `AuthenticationError` | `AUTHENTICATION_ERROR` | 401    | Missing or invalid credentials |
+| `RateLimitError`      | `RATE_LIMIT_ERROR`     | 429    | Rate limit exceeded            |
+| `IdempotencyError`    | `IDEMPOTENCY_ERROR`    | 409    | Idempotency key conflict       |
 
-// Validation — 400
-throw new ValidationError("Invalid email", [{ path: "email", message: "Invalid format" }]);
+Check for Gate errors:
 
-// Authentication — 401
-throw new AuthenticationError("Invalid API key");
+```ts
+try {
+  // ...
+} catch (err) {
+  if (isGateError(err)) {
+    console.error(err.code, err.status, err.message);
+  }
+}
+```
 
-// Rate limiting — 429
-throw new RateLimitError(30); // retry after 30 seconds
+---
 
-// Idempotency conflict — 409
-throw new IdempotencyError("Idempotency key already in use");
-```
+## Configuration Reference
+
+### `createGate(options?)`
+
+| Option                  | Type                       | Default                  | Description                                                                                          |
+| ----------------------- | -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `apiKeys`               | `ApiKeyEntry[]`            | `[]`                     | Static API keys for in-memory validation                                                             |
+| `client`                | `Client`                   | —                        | `@joinremba/core` client for remote rate-limit, idempotency & API key validation with local fallback |
+| `rateLimit.windowMs`    | `number`                   | `60_000`                 | Rate limit window in milliseconds                                                                    |
+| `rateLimit.max`         | `number`                   | `100`                    | Max requests per window                                                                              |
+| `rateLimit.store`       | `RateLimitStore`           | `InMemoryRateLimitStore` | Persistent store for rate limit data                                                                 |
+| `rateLimit.keyFn`       | `(req: Request) => string` | IP via `x-forwarded-for` | Function to derive rate limit key                                                                    |
+| `idempotency.store`     | `IdempotencyStore`         | `InMemoryStore`          | Persistent store for idempotency data                                                                |
+| `idempotency.keyHeader` | `string`                   | `Idempotency-Key`        | Header name for idempotency key                                                                      |
+| `idempotency.ttl`       | `number`                   | `86_400_000` (24h)       | Time-to-live for cached responses                                                                    |
+
+### `MiddlewareOptions`
+
+| Option           | Type       | Default                          | Description                    |
+| ---------------- | ---------- | -------------------------------- | ------------------------------ |
+| `auth`           | `boolean`  | `true` if `apiKeys` provided     | Enable API key authentication  |
+| `requiredScopes` | `string[]` | `[]`                             | Require specific scopes        |
+| `rateLimit`      | `boolean`  | `true` if `rateLimit` configured | Enable rate limiting           |
+| `idempotency`    | `boolean`  | `false`                          | Enable idempotency checks      |
+| `excludePaths`   | `string[]` | `[]`                             | Path prefixes to skip entirely |
 
-## Remote Delegation (client)
+---
 
-When a `client` from `@joinremba/core` is provided, `createGate` delegates rate limit, idempotency, and API key checks to [Nexus](https://github.com/joinremba). If Nexus is unreachable, methods fall back to local stores.
+## TypeScript
+
+Gate is built with TypeScript under `strict: true`. All validation schemas use Zod for full type inference.
 
 ```ts
-import { createClient } from "@joinremba/core";
-import { createGate } from "@joinremba/gate";
+import { z } from "zod";
+import type { ValidationSchemas, ValidationResult, SuccessResponse } from "@joinremba/gate";
 
-const gate = createGate({
-  client: createClient({ apiKey: "api_core_live_..." }),
-  rateLimit: { max: 100 },  // local fallback
-  idempotency: { ttl: 86_400_000 },
-});
+const schemas: ValidationSchemas = {
+  body: z.object({ email: z.string().email() }),
+  query: z.object({ page: z.coerce.number() }),
+};
+
+type Body = z.infer<typeof schemas.body>; // { email: string }
+
+// Response types
+const res: SuccessResponse<{ id: string }> = gate.ok({ id: "abc" });
+// → { success: true, data: { id: "abc" } }
+```
+
+Response types are branded with `success: true` / `success: false` for discriminated unions:
+
+```ts
+type Response = SuccessResponse<unknown> | ErrorResponse;
+
+function handle(res: Response) {
+  if (res.success) {
+    // TS narrows to SuccessResponse — access .data
+  } else {
+    // TS narrows to ErrorResponse — access .error
+  }
+}
 ```
 
-## API Reference
-
-| Entry Point | Exports |
-|---|---|
-| `@joinremba/gate` | `createGate`, `idempotency`, `rateLimit`, `createApiKeyValidator`, `keyByApiKey`, `ok`, `fail`, `paginated`, `problem`, `InMemoryStore`, `InMemoryRateLimitStore`, `GateError`, `ValidationError`, `AuthenticationError`, `RateLimitError`, `IdempotencyError`, `getGateAuth`, `getGateRateLimit`, `getGateIdempotencyKey` |
-| `@joinremba/gate/validate` | `validateRequest`, `validate` |
-| `@joinremba/gate/respond` | `ok`, `fail`, `paginated`, `problem` |
-| `@joinremba/gate/idempotency` | `idempotency`, `InMemoryStore` |
-| `@joinremba/gate/rate-limit` | `rateLimit`, `InMemoryRateLimitStore`, `keyByApiKey` |
-| `@joinremba/gate/api-keys` | `createApiKeyValidator` |
-| `@joinremba/gate/errors` | `GateError`, `ValidationError`, `AuthenticationError`, `RateLimitError`, `IdempotencyError` |
-| `@joinremba/gate/stores/redis` | `RedisIdempotencyStore`, `RedisRateLimitStore`, `RedisClient` |
-| `@joinremba/gate/stores/redis-api-keys` | `RedisApiKeyStore` |
-| `@joinremba/gate/stores/postgres` | `PostgresIdempotencyStore`, `PostgresRateLimitStore` |
-| `@joinremba/gate/stores/postgres-api-keys` | `PostgresApiKeyStore` |
+---
 
 ## License
 
-MIT
+MIT © [Benson Isaac](https://github.com/bensxn)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/gate",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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",
@@ -124,6 +124,7 @@
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^10.1.8",
+    "hono": "^4.12.23",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3"
   }

package/src/adapters/hono.test.ts

@@ -0,0 +1,168 @@
+import { expect, test, describe } from "bun:test";
+import { Hono } from "hono";
+import { createGate } from "../index";
+import { createRateLimiter, requireIdempotencyKey, gateMiddleware } from "./hono";
+
+function createApp(
+  ...middleware: ReturnType<
+    typeof createRateLimiter | typeof requireIdempotencyKey | typeof gateMiddleware
+  >[]
+): Hono {
+  const app = new Hono();
+  app.use(...middleware);
+  app.post("/test", (c) => c.json({ success: true, data: { id: "1" } }, 201));
+  app.get("/safe", (c) => c.json({ ok: true }));
+  return app;
+}
+
+describe("createRateLimiter", () => {
+  test("allows requests within limit", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 5 } });
+    const app = createApp(createRateLimiter({ gate, keyPrefix: "test" }));
+
+    const res = await app.request("http://localhost/test", { method: "POST" });
+    expect(res.status).toBe(201);
+    expect(res.headers.get("X-RateLimit-Remaining")).toBe("4");
+  });
+
+  test("blocks requests over limit", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 0 } });
+    const app = createApp(createRateLimiter({ gate, keyPrefix: "test" }));
+
+    const res = await app.request("http://localhost/test", { method: "POST" });
+    expect(res.status).toBe(429);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toHaveProperty("error");
+  });
+
+  test("uses custom getKey function", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 5 } });
+    const app = new Hono();
+    app.use(
+      createRateLimiter({
+        gate,
+        keyPrefix: "custom",
+        getKey: (c) => c.req.header("x-custom") ?? "unknown",
+      })
+    );
+    app.post("/test", (c) => c.json({ ok: true }, 201));
+
+    const res = await app.request("http://localhost/test", {
+      method: "POST",
+      headers: { "x-custom": "user-42" },
+    });
+    expect(res.status).toBe(201);
+  });
+
+  test("falls back to clientIp then x-forwarded-for", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 5 } });
+    const app = new Hono();
+    app.use(createRateLimiter({ gate, keyPrefix: "ip" }));
+    app.post("/test", (c) => c.json({ ok: true }, 201));
+
+    const res = await app.request("http://localhost/test", {
+      method: "POST",
+      headers: { "x-forwarded-for": "10.0.0.1" },
+    });
+    expect(res.status).toBe(201);
+  });
+});
+
+describe("requireIdempotencyKey", () => {
+  test("rejects missing key header", async () => {
+    const gate = createGate({ idempotency: { ttl: 60000 } });
+    const app = createApp(requireIdempotencyKey({ gate }));
+
+    const res = await app.request("http://localhost/test", { method: "POST" });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect((body.error as Record<string, unknown>).message).toContain(
+      "Idempotency-Key header is required"
+    );
+  });
+
+  test("rejects invalid key format", async () => {
+    const gate = createGate({ idempotency: { ttl: 60000 } });
+    const app = createApp(requireIdempotencyKey({ gate }));
+
+    const res = await app.request("http://localhost/test", {
+      method: "POST",
+      headers: { "Idempotency-Key": "short" },
+    });
+    expect(res.status).toBe(400);
+  });
+
+  test("passes through on GET requests", async () => {
+    const gate = createGate({ idempotency: { ttl: 60000 } });
+    const app = new Hono();
+    app.use(requireIdempotencyKey({ gate }));
+    app.get("/safe", (c) => c.json({ ok: true }));
+
+    const res = await app.request("http://localhost/safe");
+    expect(res.status).toBe(200);
+  });
+
+  test("returns cached response on duplicate key", async () => {
+    const gate = createGate({ idempotency: { ttl: 60000 } });
+    await gate.idempotency.setResponse("idemp-dup-key", { success: true, data: { id: "cached" } });
+    const app = createApp(requireIdempotencyKey({ gate }));
+
+    const res = await app.request("http://localhost/test", {
+      method: "POST",
+      headers: { "Idempotency-Key": "idemp-dup-key" },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect((body.data as Record<string, unknown>).id).toBe("cached");
+  });
+
+  test("caches successful response for idempotent re-use", async () => {
+    const gate = createGate({ idempotency: { ttl: 60000 } });
+    const app = createApp(requireIdempotencyKey({ gate }));
+
+    const res1 = await app.request("http://localhost/test", {
+      method: "POST",
+      headers: { "Idempotency-Key": "cache-me" },
+    });
+    expect(res1.status).toBe(201);
+
+    const cached = await gate.idempotency.getResponse("cache-me");
+    expect(cached).toBeDefined();
+    expect((cached as Record<string, unknown>).data).toBeDefined();
+  });
+});
+
+describe("gateMiddleware", () => {
+  test("passes through when no features configured", async () => {
+    const gate = createGate();
+    const app = new Hono();
+    app.use(gateMiddleware(gate));
+    app.post("/test", (c) => c.json({ ok: true }));
+
+    const res = await app.request("http://localhost/test", { method: "POST" });
+    expect(res.status).toBe(200);
+  });
+
+  test("rejects when auth fails", async () => {
+    const gate = createGate({ apiKeys: [{ key: "sk-valid" }] });
+    const app = new Hono();
+    app.use(gateMiddleware(gate, { auth: true }));
+    app.post("/test", (c) => c.json({ ok: true }));
+
+    const res = await app.request("http://localhost/test", {
+      method: "POST",
+      headers: { Authorization: "Bearer sk-wrong" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("rejects when rate limit exceeded", async () => {
+    const gate = createGate({ rateLimit: { windowMs: 60000, max: 0 } });
+    const app = new Hono();
+    app.use(gateMiddleware(gate, { rateLimit: true }));
+    app.post("/test", (c) => c.json({ ok: true }));
+
+    const res = await app.request("http://localhost/test", { method: "POST" });
+    expect(res.status).toBe(429);
+  });
+});

package/src/adapters/hono.ts

@@ -4,21 +4,13 @@ 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,
@@ -26,21 +18,15 @@ export function createRateLimiter({
   return createMiddleware(async (c: Context, next: Next) => {
     const identifier = getKey
       ? getKey(c)
-      : (c.get("clientIp") as string | undefined) ??
-        c.req.header("x-forwarded-for") ??
-        "unknown";
+      : ((c.get("clientIp") as string | undefined) ?? 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",
-        }
-      );
+      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));
@@ -53,11 +39,6 @@ type HonoIdempotencyOptions = {
   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",
@@ -99,25 +80,15 @@ export function requireIdempotencyKey({
       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 any, headers);
-    };
-
     await next();
+
+    if (c.res.status < 500) {
+      const body = await c.res.clone().json();
+      gate.idempotency.setResponse(key, body).catch(() => {});
+    }
   });
 }
 
-/**
- * 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) => {

package/src/errors.ts

@@ -43,3 +43,7 @@ export class IdempotencyError extends GateError {
     this.name = "IdempotencyError";
   }
 }
+
+export function isGateError(err: unknown): err is GateError {
+  return err instanceof GateError;
+}

package/src/index.ts

@@ -30,6 +30,7 @@ import {
   AuthenticationError,
   RateLimitError,
   IdempotencyError,
+  isGateError,
 } from "./errors";
 
 export {
@@ -49,6 +50,7 @@ export {
   AuthenticationError,
   RateLimitError,
   IdempotencyError,
+  isGateError,
 };
 
 export type { ValidationSchemas, ValidationResult, ValidatedRequest } from "./validate";
@@ -82,8 +84,6 @@ export interface MiddlewareOptions {
   requiredScopes?: string[];
   rateLimit?: boolean;
   idempotency?: boolean;
-  /** Override the max for this specific middleware. */
-  rateLimitMax?: number;
   /** Paths to skip entirely. */
   excludePaths?: string[];
 }

package/src/stores/redis.ts

@@ -1,20 +1,6 @@
 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>;
@@ -27,7 +13,7 @@ export function fromIORedis(client: {
   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>,
+      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),