@joinremba/gate 0.4.0 → 0.5.1

package/README.md

@@ -1,425 +1,394 @@
 # @joinremba/gate
 
-[![npm version](https://img.shields.io/npm/v/@joinremba/gate?logo=npm)](https://www.npmjs.com/package/@joinremba/gate)
-[![Licence](https://img.shields.io/npm/l/@joinremba/gate)](LICENSE)
-[![CI](https://github.com/joinremba/gate/actions/workflows/ci.yml/badge.svg)](https://github.com/joinremba/gate/actions/workflows/ci.yml)
-[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.3.1-black?logo=bun)](https://bun.sh)
+[![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)
 
-Gate is the API safety layer for TypeScript backends. It validates requests, formats responses, prevents duplicate operations, manages API keys, and protects endpoints from abuse.
+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`.
 
 ## Features
 
-- **Request validation** — Validate body, query, params, and headers with Zod schemas.
-- **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.
-- **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.
-- **Framework-agnostic** — Use with Express, Hono, Fastify, Elysia, or raw Bun.
+- **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
 
 ## Installation
 
-```sh
+```bash
 bun add @joinremba/gate
 ```
 
 ## Quick Start
 
 ```ts
-import { createGate, ok } from "@joinremba/gate";
+import { createGate } from "@joinremba/gate";
 import { z } from "zod";
 
 const gate = createGate({
-  apiKeys: [{ key: "sk-abc123", scopes: ["write"] }],
+  apiKeys: [{ key: "sk-admin", scopes: ["admin"] }],
   rateLimit: { windowMs: 60_000, max: 100 },
+  idempotency: { ttl: 86_400_000 },
 });
 
-app.post("/transfers", gate.middleware(), async (req, res) => {
-  return ok({ message: "Transfer queued" });
-});
-```
+// Validate a request body
+const userSchema = z.object({ email: z.string().email() });
+const result = gate.validate({ body: userSchema }, { body: { email: "test@example.com" } });
 
-## Modules
+// Check rate limit
+const rl = await gate.rateLimit.check(new Request("http://localhost"));
+// => { allowed: boolean, remaining: number, reset: number }
 
-Gate is organised into sub-modules that can be imported individually:
+// 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"] }
 
-```ts
-import { validateRequest } from "@joinremba/gate/validate";
-import { ok, fail, paginated, problem } from "@joinremba/gate/respond";
-import { idempotency, InMemoryStore } from "@joinremba/gate/idempotency";
-import { rateLimit, InMemoryRateLimitStore } from "@joinremba/gate/rate-limit";
-import { createApiKeyValidator } from "@joinremba/gate/api-keys";
-import { GateError, ValidationError, AuthenticationError } from "@joinremba/gate/errors";
+// Combined middleware (Hono / Express / Bun serve)
+app.use(gate.middleware({ auth: true, rateLimit: true, idempotency: true }));
 ```
 
-### `createGate(options?)`
+## createGate
 
-Factory function that returns a `Gate` instance with all modules pre-configured.
+The main factory. Accepts an options object and returns a `Gate` instance with all modules wired together.
 
 ```ts
+import { createGate } from "@joinremba/gate";
+
 const gate = createGate({
-  apiKeys: [
-    { key: "sk-read-only", scopes: ["read"] },
-    { key: "sk-admin", scopes: ["read", "write", "delete"] },
-  ],
-  rateLimit: { windowMs: 60_000, max: 50 },
-  idempotency: { keyHeader: "Idempotency-Key", ttl: 86_400_000 },
+  // 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;
+  };
 });
 ```
 
-### Validate (`@joinremba/gate/validate`)
+**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.
 
 ```ts
-import { validateRequest } from "@joinremba/gate/validate";
+import { validateRequest, validate } from "@joinremba/gate";
 import { z } from "zod";
 
-const transferSchema = z.object({
-  amount: z.number().positive(),
-  currency: z.enum(["NGN", "USD", "EUR"]),
-  recipient: z.string().min(1),
-});
-
-const result = validateRequest({ body: transferSchema }, { body: req.body });
-
-if (!result.success) {
-  return gate.fail("Validation failed", "VALIDATION_ERROR", result.errors);
-}
+// Low-level: pass parsed input directly
+const result = validateRequest(
+  {
+    body: z.object({ email: z.string().email() }),
+    query: z.object({ page: z.coerce.number() }),
+  },
+  {
+    body: { email: "test@example.com" },
+    query: { page: "1" },
+  }
+);
+// => { 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" },
+}));
 ```
 
-### Respond (`@joinremba/gate/respond`)
-
-Build consistent API responses.
+## Response Helpers
 
 ```ts
-import { ok, fail, paginated, problem } from "@joinremba/gate/respond";
-
-// Success
-ok({ id: 1, name: "Alice" });
-// -> { success: true, data: { id: 1, name: "Alice" } }
-
-// Error
-fail("Resource not found", "NOT_FOUND");
-// -> { success: false, error: { message: "Resource not found", code: "NOT_FOUND" } }
-
-// Paginated
-paginated([{ id: 1 }], 25, 1, 10);
-// -> { success: true, data: [...], pagination: { total: 25, page: 1, limit: 10, pages: 3 } }
-
-// Problem details (RFC 9457)
-problem({
-  type: "https://errors.remba.com/rate-limit",
-  title: "Rate Limit Exceeded",
-  status: 429,
-  detail: "Too many requests, please retry later",
-});
-```
+import { ok, fail, paginated, problem } from "@joinremba/gate";
 
-### Idempotency (`@joinremba/gate/idempotency`)
+ok(userData);
+// { success: true, data: userData }
 
-Prevent duplicate processing of the same request using idempotency keys.
+fail("Not found", "NOT_FOUND");
+// { success: false, error: { message: "Not found", code: "NOT_FOUND" } }
 
-```ts
-import { idempotency, InMemoryStore } from "@joinremba/gate/idempotency";
-
-const guard = idempotency({
-  store: new InMemoryStore(),
-  keyHeader: "Idempotency-Key",
-  ttl: 86_400_000, // 24 hours
-});
+fail("Invalid input", "VALIDATION_ERROR", { field: "email" });
+// { success: false, error: { message: "Invalid input", code: "VALIDATION_ERROR", details: { field: "email" } } }
 
-// Check if a request has been processed
-const existing = await guard.getResponse(idempotencyKey);
-if (existing) return existing;
+paginated(items, 100, 1, 20);
+// { success: true, data: items, pagination: { total: 100, page: 1, limit: 20, pages: 5 } }
 
-// Store the response after processing
-await guard.setResponse(idempotencyKey, response);
+problem({ type: "/errors/rate-limit", title: "Rate Limit Exceeded", status: 429, detail: "..." });
+// { success: false, error: { message: "Rate Limit Exceeded", ... }, problem: { type, title, status, detail } }
 ```
 
-Bring your own store by implementing the `IdempotencyStore` interface (Redis, Postgres, etc.).
+## Idempotency
 
-### Rate Limiting (`@joinremba/gate/rate-limit`)
-
-Protect endpoints from abuse.
+Prevent duplicate processing by storing responses keyed by an idempotency key (default `Idempotency-Key` header).
 
 ```ts
-import { rateLimit, InMemoryRateLimitStore } from "@joinremba/gate/rate-limit";
+import { idempotency, InMemoryStore } from "@joinremba/gate";
 
-const limiter = rateLimit({
-  windowMs: 60_000, // 1 minute
-  max: 30,
-  keyFn: (req) => req.headers.get("x-forwarded-for") ?? "global",
-});
+const guard = idempotency({ store: new InMemoryStore(), ttl: 86_400_000 });
 
-const { allowed, remaining } = await limiter.check(req);
-if (!allowed) throw new RateLimitError();
+// 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);
+}
 ```
 
-Customise the key function to rate-limit by user ID, API key, or IP.
-
-### API Keys (`@joinremba/gate/api-keys`)
-
-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).
+**Via `createGate`:**
 
 ```ts
-import { createApiKeyValidator } from "@joinremba/gate/api-keys";
+const gate = createGate({ idempotency: { ttl: 86_400_000 } });
+const cached = await gate.idempotency.getResponse("key");
+if (!cached) {
+  await gate.idempotency.setResponse("key", response);
+}
+```
 
-const keys = createApiKeyValidator([
-  { key: "sk-read-only", scopes: ["read"] },
-  { key: "sk-admin", scopes: ["read", "write", "delete"] },
-]);
+## Rate Limiting
 
-// Direct validation
-keys.validate("sk-read-only");
-// -> { authenticated: true, key: "sk-read-only", scopes: ["read"] }
+```ts
+import { rateLimit, InMemoryRateLimitStore, keyByApiKey } from "@joinremba/gate";
 
-// Request authentication middleware
-const auth = keys.authenticate({ requiredScopes: ["write"], header: "Authorization" });
-const result = auth(request);
-if (!result.authenticated) throw new AuthenticationError(result.error);
-```
+const limiter = rateLimit({ windowMs: 60_000, max: 100 });
 
-**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.
+// 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 }
 
-**When not to use it:** You need key rotation, hashed storage, per-user API keys, expiry/revocation, or rate limiting per key. For those cases, use the hashed or DB-backed stores below.
+// Check with a custom key string
+const result = await limiter.check("user:42");
 
-#### Hashed API Keys
+// Key by API key (Bearer token) instead of IP
+const limiter2 = rateLimit({ keyFn: keyByApiKey });
+```
 
-Store SHA-256 hashes instead of plaintext keys. Protects against memory dumps.
+**Via `createGate`:**
 
 ```ts
-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"] }
+const gate = createGate({ rateLimit: { windowMs: 60_000, max: 100 } });
+const result = await gate.rateLimit.check(req);
 ```
 
-#### DB-backed API Key Stores
-
-Validate keys against Postgres or Redis. Keys can be added/removed at runtime.
+## API Keys
 
 ```ts
-import { PostgresApiKeyStore } from "@joinremba/gate/stores/postgres-api-keys";
+import { createApiKeyValidator } from "@joinremba/gate";
 
-const store = new PostgresApiKeyStore(pgClient);
-await store.ensureTable();
+const validator = createApiKeyValidator([
+  { key: "sk-admin", scopes: ["admin"] },
+  { key: "sk-read", scopes: ["read"] },
+]);
 
-// Add a key
-await store.setKey({ key: "sk-live-abc", scopes: ["read"] }, expiresAt);
+// Direct key validation
+const result = validator.validate("sk-admin");
+// { authenticated: true, key: "sk-admin", scopes: ["admin"] }
 
-// Validate
-const result = await store.verify("sk-live-abc");
+// Verifying against hashed keys (SHA-256)
+const hashedValidator = createApiKeyValidator(
+  [{ key: "sk-admin", scopes: ["admin"] }],
+  { hashKeys: true }
+);
+const result = await hashedValidator.verify("sk-admin");
 
-// Remove
-await store.deleteKey("sk-live-abc");
+// Request authentication with scope checking
+const authFn = validator.authenticate({ requiredScopes: ["admin"] });
+const result = await authFn(new Request("http://localhost", {
+  headers: { Authorization: "Bearer sk-admin" },
+}));
 ```
 
-```ts
-import { RedisApiKeyStore } from "@joinremba/gate/stores/redis-api-keys";
+**Via `createGate`:**
 
-const store = new RedisApiKeyStore(redisClient);
-await store.setKey({ key: "sk-redis-key", scopes: ["admin"] });
-const result = await store.verify("sk-redis-key");
+```ts
+const gate = createGate({ apiKeys: [{ key: "sk-admin", scopes: ["admin"] }] });
+const result = await gate.apiKeys.verify("sk-admin");
 ```
 
-### Combined Middleware
+## Combined Middleware
 
-Run auth, rate limiting, and idempotency in a single middleware call:
+Run auth, rate limiting, and idempotency in a single pass. Returns a middleware function compatible with any framework.
 
 ```ts
-const gate = createGate({
-  apiKeys: [{ key: "sk-admin" }],
-  rateLimit: { windowMs: 60_000, max: 100 },
+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
 });
-
-app.use(
-  gate.middleware({
-    auth: true,
-    requiredScopes: ["write"],
-    rateLimit: true,
-    idempotency: true,
-    excludePaths: ["/health", "/metrics"],
-  })
-);
 ```
 
-The middleware returns 401 for invalid/missing keys, 429 when rate limited, and caches idempotent responses automatically.
+**Play nice with Hono:**
 
-### Per-key Rate Limiting
+```ts
+import { Hono } from "hono";
+const app = new Hono();
+app.use("*", (c, next) => gate.middleware()(c.req.raw, () => next()));
+```
 
-Rate-limit by API key instead of IP:
+**Access pass-through state via WeakMap:**
 
 ```ts
-import { rateLimit, keyByApiKey } from "@joinremba/gate/rate-limit";
+import { getGateAuth, getGateRateLimit, getGateIdempotencyKey } from "@joinremba/gate";
 
-const limiter = rateLimit({
-  windowMs: 60_000,
-  max: 30,
-  keyFn: keyByApiKey,
-});
+// Inside your request handler
+const auth = getGateAuth(req);           // { authenticated, key, scopes }
+const rl = getGateRateLimit(req);        // { allowed, remaining, reset }
+const idemKey = getGateIdempotencyKey(req); // string | undefined
 ```
 
-### Errors (`@joinremba/gate/errors`)
-
-Standard error types for consistent error handling.
+## Stores
 
-| Error                 | Status | Code                   | When                       |
-| --------------------- | ------ | ---------------------- | -------------------------- |
-| `GateError`           | 500    | `GATE_ERROR`           | Base error type            |
-| `ValidationError`     | 400    | `VALIDATION_ERROR`     | Invalid request input      |
-| `AuthenticationError` | 401    | `AUTHENTICATION_ERROR` | Missing or invalid API key |
-| `RateLimitError`      | 429    | `RATE_LIMIT_ERROR`     | Rate limit exceeded        |
-| `IdempotencyError`    | 409    | `IDEMPOTENCY_ERROR`    | Idempotency key conflict   |
+### InMemory (default)
 
-## TypeScript Types
+Built-in stores for development and single-process deployments.
 
 ```ts
-import type {
-  Gate,
-  GateOptions,
-  Middleware,
-  ValidationSchemas,
-  ValidationResult,
-  SuccessResponse,
-  ErrorResponse,
-  PaginatedResponse,
-  ProblemDetails,
-  IdempotencyStore,
-  IdempotencyOptions,
-  RateLimitStore,
-  RateLimitOptions,
-  RateLimitStrategy,
-  ApiKeyEntry,
-  AuthenticateOptions,
-  AuthenticateResult,
-} from "@joinremba/gate";
-```
+import { InMemoryStore, InMemoryRateLimitStore } from "@joinremba/gate";
 
-## Examples
+const idemStore = new InMemoryStore();
+const rlStore = new InMemoryRateLimitStore();
+```
 
-### Express middleware
+### Redis
 
 ```ts
-import express from "express";
-import { createGate, ok } from "@joinremba/gate";
-import { z } from "zod";
-
-const app = express();
-const gate = createGate({ rateLimit: { windowMs: 60_000, max: 30 } });
-
-app.post(
-  "/api/orders",
-  (req, res, next) => {
-    const result = gate.validate(
-      { body: z.object({ productId: z.string(), quantity: z.number() }) },
-      { body: req.body }
-    );
-    if (!result.success) {
-      return res.status(400).json(gate.fail("Validation failed", undefined, result.errors));
-    }
-    req.body = result.data.body;
-    next();
-  },
-  async (req, res) => {
-    const order = await createOrder(req.body);
-    res.json(ok(order));
-  }
-);
+import { RedisIdempotencyStore, RedisRateLimitStore } from "@joinremba/gate/stores/redis";
+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);
 ```
 
-### Hono middleware
+### PostgreSQL
 
 ```ts
-import { Hono } from "hono";
-import { createGate, ok } from "@joinremba/gate";
+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 app = new Hono();
-const gate = createGate({ apiKeys: [{ key: "sk-admin" }] });
+const sql: PostgresClient = {
+  query: (text, params) => pool.query(text, params),
+};
 
-app.use("/api/*", async (c, next) => {
-  const auth = gate.apiKeys.authenticate()(c.req.raw);
-  if (!auth.authenticated) {
-    return c.json(gate.fail("Unauthorized"), 401);
-  }
-  await next();
-});
+const idemStore = new PostgresIdempotencyStore(sql);
+const rlStore = new PostgresRateLimitStore(sql);
+const apiKeyStore = new PostgresApiKeyStore(sql);
+
+// Auto-create tables
+await idemStore.ensureTable();
+await rlStore.ensureTable();
+await apiKeyStore.ensureTable();
 ```
 
-### Combining multiple features
+## Error Classes
 
 ```ts
-const gate = createGate({
-  apiKeys: [{ key: "sk-admin", scopes: ["write"] }],
-  idempotency: { store: new InMemoryStore(), ttl: 86_400_000 },
-  rateLimit: { windowMs: 60_000, max: 50 },
-});
+import {
+  GateError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+  IdempotencyError,
+} from "@joinremba/gate";
 
-app.post("/orders", async (req, res, next) => {
-  // Rate limit
-  const rl = await gate.rateLimit.check(req);
-  if (!rl.allowed) return res.status(429).json(gate.fail("Too many requests"));
+// Base class
+throw new GateError("Something went wrong", "INTERNAL_ERROR", 500);
 
-  // Idempotency
-  const idemKey = req.headers.get(gate.idempotency.keyHeader);
-  if (idemKey) {
-    const cached = await gate.idempotency.getResponse(idemKey);
-    if (cached) return res.json(cached);
-  }
+// Validation — 400
+throw new ValidationError("Invalid email", [{ path: "email", message: "Invalid format" }]);
 
-  // Validate
-  const result = gate.validate({ body: z.object({ amount: z.number() }) }, { body: req.body });
-  if (!result.success) return res.status(400).json(gate.fail("Validation failed"));
+// Authentication — 401
+throw new AuthenticationError("Invalid API key");
 
-  const response = ok(await processOrder(result.data.body));
+// Rate limiting — 429
+throw new RateLimitError(30); // retry after 30 seconds
 
-  if (idemKey) await gate.idempotency.setResponse(idemKey, response);
-  res.json(response);
-});
+// Idempotency conflict — 409
+throw new IdempotencyError("Idempotency key already in use");
 ```
 
-## Roadmap
+## Remote Delegation (client)
 
-**MVP** (current)
+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.
 
-- Request validation (body, query, params, headers)
-- Standard success/error responses
-- Problem-details error format (RFC 9457)
-- Pagination helper
-- Request ID support
-- Express and Hono middleware examples
-- In-memory idempotency store
-- In-memory rate limiting store
-
-**V1** (current)
-
-- Redis and Postgres stores for idempotency and rate limiting
-- API key hashing and validation
-- DB-backed API key stores (Redis, Postgres)
-- Combined middleware (auth + rate limit + idempotency)
-- Per-key rate limiting helper
-
-**V2**
-
-- API key dashboard
-- Usage analytics
-- Abuse detection
-- Team API key management
-- Hosted key verification
-- Organisation-level quotas
-
-## Related Packages
-
-- [@joinremba/beacon](https://github.com/joinremba/beacon) — Environment validation, config, secrets, and feature gates.
-- [@joinremba/catalog](https://github.com/joinremba/catalog) — Production-ready logging and error event layer built on Pino.
+```ts
+import { createClient } from "@joinremba/core";
+import { createGate } from "@joinremba/gate";
 
-## Contributing
+const gate = createGate({
+  client: createClient({ apiKey: "api_core_live_..." }),
+  rateLimit: { max: 100 },  // local fallback
+  idempotency: { ttl: 86_400_000 },
+});
+```
 
-Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, development workflow, and pull request process.
+## 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 — see [LICENSE](LICENSE).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/gate",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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": [

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.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",
+        }
+      );
+    }
+
+    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 any, 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/stores/redis.ts

@@ -1,6 +1,41 @@
 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>;