@joinremba/gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# @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)
+
+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.
+
+## 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.
+- **Request ID** — Automatic request ID generation and propagation.
+- **Idempotency** — Prevent duplicate writes with idempotency keys. Ships with in-memory store; plug in Redis or Postgres.
+- **Rate limiting** — Protect endpoints from abuse with configurable windows and limits.
+- **API key management** — Rotatable, scoped API key authentication with Bearer token support.
+- **Framework-agnostic** — Use with Express, Hono, Fastify, Elysia, or raw Bun.
+
+## Installation
+
+```sh
+bun add @joinremba/gate
+```
+
+## Quick Start
+
+```ts
+import { createGate, ok } from "@joinremba/gate";
+import { z } from "zod";
+
+const gate = createGate({
+  apiKeys: [{ key: "sk-abc123", scopes: ["write"] }],
+  rateLimit: { windowMs: 60_000, max: 100 },
+});
+
+app.post("/transfers", gate.middleware(), async (req, res) => {
+  return ok({ message: "Transfer queued" });
+});
+```
+
+## Modules
+
+Gate is organised into sub-modules that can be imported individually:
+
+```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";
+```
+
+### `createGate(options?)`
+
+Factory function that returns a `Gate` instance with all modules pre-configured.
+
+```ts
+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 },
+});
+```
+
+### Validate (`@joinremba/gate/validate`)
+
+Validate request body, query, params, and headers against Zod schemas.
+
+```ts
+import { validateRequest } from "@joinremba/gate/validate";
+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);
+}
+```
+
+### Respond (`@joinremba/gate/respond`)
+
+Build consistent API responses.
+
+```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",
+});
+```
+
+### Idempotency (`@joinremba/gate/idempotency`)
+
+Prevent duplicate processing of the same request using idempotency keys.
+
+```ts
+import { idempotency, InMemoryStore } from "@joinremba/gate/idempotency";
+
+const guard = idempotency({
+  store: new InMemoryStore(),
+  keyHeader: "Idempotency-Key",
+  ttl: 86_400_000, // 24 hours
+});
+
+// Check if a request has been processed
+const existing = await guard.getResponse(idempotencyKey);
+if (existing) return existing;
+
+// Store the response after processing
+await guard.setResponse(idempotencyKey, response);
+```
+
+Bring your own store by implementing the `IdempotencyStore` interface (Redis, Postgres, etc.).
+
+### Rate Limiting (`@joinremba/gate/rate-limit`)
+
+Protect endpoints from abuse.
+
+```ts
+import { rateLimit, InMemoryRateLimitStore } from "@joinremba/gate/rate-limit";
+
+const limiter = rateLimit({
+  windowMs: 60_000, // 1 minute
+  max: 30,
+  keyFn: (req) => req.headers.get("x-forwarded-for") ?? "global",
+});
+
+const { allowed, remaining } = await limiter.check(req);
+if (!allowed) throw new RateLimitError();
+```
+
+Customise the key function to rate-limit by user ID, API key, or IP.
+
+### API Keys (`@joinremba/gate/api-keys`)
+
+Validate API keys with optional scoped permissions.
+
+```ts
+import { createApiKeyValidator } from "@joinremba/gate/api-keys";
+
+const keys = createApiKeyValidator([
+  { key: "sk-read-only", scopes: ["read"] },
+  { key: "sk-admin", scopes: ["read", "write", "delete"] },
+]);
+
+// Direct validation
+keys.validate("sk-read-only");
+// -> { authenticated: true, key: "sk-read-only", scopes: ["read"] }
+
+// Request authentication middleware
+const auth = keys.authenticate({ requiredScopes: ["write"], header: "Authorization" });
+const result = auth(request);
+if (!result.authenticated) throw new AuthenticationError(result.error);
+```
+
+### Errors (`@joinremba/gate/errors`)
+
+Standard error types for consistent error handling.
+
+| 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   |
+
+## TypeScript Types
+
+```ts
+import type {
+  Gate,
+  GateOptions,
+  Middleware,
+  ValidationSchemas,
+  ValidationResult,
+  SuccessResponse,
+  ErrorResponse,
+  PaginatedResponse,
+  ProblemDetails,
+  IdempotencyStore,
+  IdempotencyOptions,
+  RateLimitStore,
+  RateLimitOptions,
+  RateLimitStrategy,
+  ApiKeyEntry,
+  AuthenticateOptions,
+  AuthenticateResult,
+} from "@joinremba/gate";
+```
+
+## Examples
+
+### Express middleware
+
+```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));
+  }
+);
+```
+
+### Hono middleware
+
+```ts
+import { Hono } from "hono";
+import { createGate, ok } from "@joinremba/gate";
+
+const app = new Hono();
+const gate = createGate({ apiKeys: [{ key: "sk-admin" }] });
+
+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();
+});
+```
+
+### Combining multiple features
+
+```ts
+const gate = createGate({
+  apiKeys: [{ key: "sk-admin", scopes: ["write"] }],
+  idempotency: { store: new InMemoryStore(), ttl: 86_400_000 },
+  rateLimit: { windowMs: 60_000, max: 50 },
+});
+
+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"));
+
+  // Idempotency
+  const idemKey = req.headers.get(gate.idempotency.keyHeader);
+  if (idemKey) {
+    const cached = await gate.idempotency.getResponse(idemKey);
+    if (cached) return res.json(cached);
+  }
+
+  // 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"));
+
+  const response = ok(await processOrder(result.data.body));
+
+  if (idemKey) await gate.idempotency.setResponse(idemKey, response);
+  res.json(response);
+});
+```
+
+## Roadmap
+
+**MVP** (current)
+
+- 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**
+
+- Idempotency middleware
+- Redis idempotency store
+- Postgres idempotency store
+- Rate limiting middleware
+- API key hashing and validation
+- Scopes and permissions middleware
+- Usage tracking hooks
+
+**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.
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, development workflow, and pull request process.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@joinremba/gate",
+  "version": "0.1.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",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./validate": {
+      "types": "./src/validate.ts",
+      "import": "./src/validate.ts",
+      "default": "./src/validate.ts"
+    },
+    "./respond": {
+      "types": "./src/respond.ts",
+      "import": "./src/respond.ts",
+      "default": "./src/respond.ts"
+    },
+    "./idempotency": {
+      "types": "./src/idempotency.ts",
+      "import": "./src/idempotency.ts",
+      "default": "./src/idempotency.ts"
+    },
+    "./rate-limit": {
+      "types": "./src/rate-limit.ts",
+      "import": "./src/rate-limit.ts",
+      "default": "./src/rate-limit.ts"
+    },
+    "./api-keys": {
+      "types": "./src/api-keys.ts",
+      "import": "./src/api-keys.ts",
+      "default": "./src/api-keys.ts"
+    },
+    "./errors": {
+      "types": "./src/errors.ts",
+      "import": "./src/errors.ts",
+      "default": "./src/errors.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm",
+    "dev": "bun --watch ./src/index.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "prepublishOnly": "bun run build",
+    "check": "bun lint && bun format:check && bun typecheck && bun test"
+  },
+  "author": {
+    "name": "Benson Isaac",
+    "email": "bensxnisaac@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joinremba/gate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joinremba/gate/issues"
+  },
+  "homepage": "https://github.com/joinremba/gate#readme",
+  "keywords": [
+    "api",
+    "middleware",
+    "validation",
+    "request-validation",
+    "rate-limiting",
+    "idempotency",
+    "api-keys",
+    "security"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.1"
+  },
+  "dependencies": {
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/api-keys.ts

@@ -0,0 +1,59 @@
+export interface ApiKeyEntry {
+  key: string;
+  scopes?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface AuthenticateOptions {
+  requiredScopes?: string[];
+  header?: string;
+}
+
+export interface AuthenticateResult {
+  authenticated: boolean;
+  key?: string;
+  scopes?: string[];
+  error?: string;
+}
+
+export function createApiKeyValidator(keys: ApiKeyEntry[]) {
+  const keyMap = new Map(keys.map((k) => [k.key, k]));
+
+  return {
+    validate(providedKey: string): AuthenticateResult {
+      const entry = keyMap.get(providedKey);
+      if (!entry) {
+        return { authenticated: false, error: "Invalid API key" };
+      }
+      return { authenticated: true, key: entry.key, scopes: entry.scopes };
+    },
+
+    authenticate(options: AuthenticateOptions = {}) {
+      const header = options.header ?? "Authorization";
+      const requiredScopes = options.requiredScopes ?? [];
+
+      return (req: Request): 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);
+
+        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;
+      };
+    },
+  };
+}
+
+export type ApiKeyValidator = ReturnType<typeof createApiKeyValidator>;

package/src/errors.ts

@@ -0,0 +1,45 @@
+export class GateError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(message: string, code: string, status = 500) {
+    super(message);
+    this.name = "GateError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export class ValidationError extends GateError {
+  readonly issues: unknown[];
+
+  constructor(message: string, issues: unknown[] = []) {
+    super(message, "VALIDATION_ERROR", 400);
+    this.name = "ValidationError";
+    this.issues = issues;
+  }
+}
+
+export class AuthenticationError extends GateError {
+  constructor(message = "Unauthorized") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class RateLimitError extends GateError {
+  readonly retryAfter: number;
+
+  constructor(retryAfter = 60) {
+    super("Too many requests", "RATE_LIMIT_ERROR", 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class IdempotencyError extends GateError {
+  constructor(message = "Idempotency key conflict") {
+    super(message, "IDEMPOTENCY_ERROR", 409);
+    this.name = "IdempotencyError";
+  }
+}

package/src/idempotency.ts

@@ -0,0 +1,54 @@
+export interface IdempotencyStore {
+  get(key: string): Promise<unknown | null>;
+  set(key: string, value: unknown, ttl: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export class InMemoryStore implements IdempotencyStore {
+  private store = new Map<string, { value: unknown; expires: number }>();
+
+  async get(key: string): Promise<unknown | null> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expires) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: unknown, ttl: number): Promise<void> {
+    this.store.set(key, { value, expires: Date.now() + ttl });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+
+export interface IdempotencyOptions {
+  store: IdempotencyStore;
+  keyHeader?: string;
+  ttl?: number;
+}
+
+export function idempotency(options: IdempotencyOptions) {
+  const keyHeader = options.keyHeader ?? "Idempotency-Key";
+  const ttl = options.ttl ?? 86_400_000; // 24 hours
+
+  return {
+    keyHeader,
+    ttl,
+    store: options.store,
+
+    async getResponse(key: string) {
+      return options.store.get(`idemp:${key}`);
+    },
+
+    async setResponse(key: string, response: unknown) {
+      await options.store.set(`idemp:${key}`, response, ttl);
+    },
+  };
+}
+
+export type IdempotencyInstance = ReturnType<typeof idempotency>;

package/src/index.test.ts

@@ -0,0 +1,116 @@
+import { expect, test, describe } from "bun:test";
+import { z } from "zod";
+import { createGate, ok, fail, paginated, problem, validateRequest } from "./index";
+
+test("createGate returns a gate instance", () => {
+  const gate = createGate();
+  expect(gate).toBeDefined();
+  expect(typeof gate.validate).toBe("function");
+  expect(typeof gate.ok).toBe("function");
+  expect(typeof gate.fail).toBe("function");
+});
+
+describe("respond", () => {
+  test("ok returns success response", () => {
+    const res = ok({ id: 1, name: "Alice" });
+    expect(res).toEqual({ success: true, data: { id: 1, name: "Alice" } });
+  });
+
+  test("fail returns error response", () => {
+    const res = fail("Not found", "NOT_FOUND");
+    expect(res).toEqual({
+      success: false,
+      error: { message: "Not found", code: "NOT_FOUND", details: undefined },
+    });
+  });
+
+  test("paginated returns paginated response", () => {
+    const res = paginated([{ id: 1 }], 25, 1, 10);
+    expect(res.success).toBe(true);
+    expect(res.pagination).toEqual({ total: 25, page: 1, limit: 10, pages: 3 });
+  });
+
+  test("problem returns problem-details response", () => {
+    const res = problem({
+      type: "https://errors.remba.com/rate-limit",
+      title: "Rate Limit Exceeded",
+      status: 429,
+      detail: "Too many requests, please retry later",
+    });
+    expect(res.success).toBe(false);
+    expect(res.problem.title).toBe("Rate Limit Exceeded");
+  });
+});
+
+describe("validate", () => {
+  test("returns success for valid input", () => {
+    const schema = z.object({ name: z.string() });
+    const result = validateRequest({ body: schema }, { body: { name: "Alice" } });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ body: { name: "Alice" } });
+    }
+  });
+
+  test("returns errors for invalid input", () => {
+    const schema = z.object({ name: z.string().min(1) });
+    const result = validateRequest({ body: schema }, { body: { name: "" } });
+    expect(result.success).toBe(false);
+  });
+
+  test("validates query params", () => {
+    const schema = z.object({ page: z.coerce.number().int().positive() });
+    const result = validateRequest({ query: schema }, { query: { page: "2" } });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("idempotency", () => {
+  test("creates idempotency instance", () => {
+    const gate = createGate();
+    expect(gate.idempotency.store).toBeDefined();
+    expect(gate.idempotency.keyHeader).toBe("Idempotency-Key");
+  });
+
+  test("stores and retrieves responses", async () => {
+    const gate = createGate({
+      idempotency: { ttl: 60000 },
+    });
+
+    const response = { status: 201, body: { id: "order-1" } };
+    await gate.idempotency.setResponse("test-key", response);
+    const cached = await gate.idempotency.getResponse("test-key");
+    expect(cached).toEqual(response);
+  });
+});
+
+describe("rate limit", () => {
+  test("allows requests within limit", async () => {
+    const gate = createGate({
+      rateLimit: { windowMs: 60000, max: 100 },
+    });
+
+    const req = new Request("http://localhost/test");
+    const result = await gate.rateLimit.check(req);
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(99);
+  });
+});
+
+describe("api keys", () => {
+  test("validates correct API key", () => {
+    const gate = createGate({
+      apiKeys: [{ key: "sk-valid", scopes: ["read"] }],
+    });
+
+    const result = gate.apiKeys.validate("sk-valid");
+    expect(result.authenticated).toBe(true);
+    expect(result.scopes).toEqual(["read"]);
+  });
+
+  test("rejects invalid API key", () => {
+    const gate = createGate({ apiKeys: [{ key: "sk-valid" }] });
+    const result = gate.apiKeys.validate("sk-invalid");
+    expect(result.authenticated).toBe(false);
+  });
+});

package/src/index.ts

@@ -0,0 +1,120 @@
+import { validateRequest } from "./validate";
+import { ok, fail, paginated, problem } from "./respond";
+import { idempotency, InMemoryStore } from "./idempotency";
+import { rateLimit, InMemoryRateLimitStore } from "./rate-limit";
+import { createApiKeyValidator } from "./api-keys";
+import type { ApiKeyEntry } from "./api-keys";
+import type { IdempotencyStore } from "./idempotency";
+import {
+  GateError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+  IdempotencyError,
+} from "./errors";
+
+export {
+  validateRequest,
+  ok,
+  fail,
+  paginated,
+  problem,
+  idempotency,
+  InMemoryStore,
+  rateLimit,
+  InMemoryRateLimitStore,
+  createApiKeyValidator,
+  GateError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+  IdempotencyError,
+};
+
+export type { ValidationSchemas, ValidationResult, ValidatedRequest } from "./validate";
+export type {
+  SuccessResponse,
+  ErrorResponse,
+  ErrorPayload,
+  PaginatedResponse,
+  ProblemDetails,
+  StructuredResponse,
+} from "./respond";
+export type { IdempotencyStore, IdempotencyOptions, IdempotencyInstance } from "./idempotency";
+export type {
+  RateLimitStore,
+  RateLimitOptions,
+  RateLimitStrategy,
+  RateLimitInstance,
+} from "./rate-limit";
+export type {
+  ApiKeyEntry,
+  AuthenticateOptions,
+  AuthenticateResult,
+  ApiKeyValidator,
+} from "./api-keys";
+
+export type Middleware = (req: Request, next?: () => Promise<Response>) => Promise<Response | null>;
+
+export interface GateOptions {
+  apiKeys?: ApiKeyEntry[];
+  idempotency?: {
+    store?: IdempotencyStore;
+    keyHeader?: string;
+    ttl?: number;
+  };
+  rateLimit?: {
+    windowMs?: number;
+    max?: number;
+    strategy?: "fixed" | "sliding";
+  };
+}
+
+export interface Gate {
+  validate: typeof validateRequest;
+  ok: typeof ok;
+  fail: typeof fail;
+  paginated: typeof paginated;
+  problem: typeof problem;
+  idempotency: ReturnType<typeof idempotency>;
+  rateLimit: ReturnType<typeof rateLimit>;
+  apiKeys: ReturnType<typeof createApiKeyValidator>;
+  middleware(): Middleware;
+}
+
+export function createGate(options: GateOptions = {}): Gate {
+  const idempInstance = idempotency({
+    store: options.idempotency?.store ?? new InMemoryStore(),
+    keyHeader: options.idempotency?.keyHeader,
+    ttl: options.idempotency?.ttl,
+  });
+
+  const rlInstance = rateLimit({
+    windowMs: options.rateLimit?.windowMs,
+    max: options.rateLimit?.max,
+  });
+
+  const apiKeyValidator = createApiKeyValidator(options.apiKeys ?? []);
+
+  const gate: Gate = {
+    validate: validateRequest,
+    ok,
+    fail,
+    paginated,
+    problem,
+    idempotency: idempInstance,
+    rateLimit: rlInstance,
+    apiKeys: apiKeyValidator,
+
+    middleware() {
+      return async (req: Request, next?: () => Promise<Response>) => {
+        if (!next) return null;
+        return next();
+      };
+    },
+  };
+
+  return gate;
+}
+
+export default createGate;

package/src/rate-limit.ts

@@ -0,0 +1,67 @@
+export interface RateLimitStore {
+  increment(key: string, windowMs: number): Promise<{ count: number; reset: number }>;
+  reset(key: string): Promise<void>;
+}
+
+export class InMemoryRateLimitStore implements RateLimitStore {
+  private store = new Map<string, { count: number; reset: number }>();
+
+  async increment(key: string, windowMs: number): Promise<{ count: number; reset: number }> {
+    const now = Date.now();
+    const entry = this.store.get(key);
+
+    if (!entry || now > entry.reset) {
+      const reset = now + windowMs;
+      this.store.set(key, { count: 1, reset });
+      return { count: 1, reset };
+    }
+
+    entry.count += 1;
+    return { count: entry.count, reset: entry.reset };
+  }
+
+  async reset(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+
+export type RateLimitStrategy = "fixed" | "sliding";
+
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  strategy?: RateLimitStrategy;
+  store?: RateLimitStore;
+  keyFn?: (req: Request) => string;
+}
+
+export function rateLimit(options: RateLimitOptions = {}) {
+  const windowMs = options.windowMs ?? 60_000;
+  const max = options.max ?? 100;
+  const store = options.store ?? new InMemoryRateLimitStore();
+  const keyFn =
+    options.keyFn ??
+    ((req: Request) => {
+      const forwarded = req.headers.get("x-forwarded-for");
+      return forwarded ?? "global";
+    });
+
+  return {
+    windowMs,
+    max,
+    store,
+    keyFn,
+
+    async check(req: Request): Promise<{ allowed: boolean; remaining: number; reset: number }> {
+      const key = keyFn(req);
+      const { count, reset } = await store.increment(`rl:${key}`, windowMs);
+      return {
+        allowed: count <= max,
+        remaining: Math.max(0, max - count),
+        reset,
+      };
+    },
+  };
+}
+
+export type RateLimitInstance = ReturnType<typeof rateLimit>;

package/src/respond.ts

@@ -0,0 +1,77 @@
+export interface SuccessResponse<T = unknown> {
+  success: true;
+  data: T;
+}
+
+export interface ErrorPayload {
+  message: string;
+  code?: string;
+  details?: unknown;
+}
+
+export interface ErrorResponse {
+  success: false;
+  error: ErrorPayload;
+}
+
+export interface PaginatedResponse<T = unknown> {
+  success: true;
+  data: T[];
+  pagination: {
+    total: number;
+    page: number;
+    limit: number;
+    pages: number;
+  };
+}
+
+export interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail: string;
+  instance?: string;
+}
+
+export type StructuredResponse<T = unknown> = SuccessResponse<T> | ErrorResponse;
+
+export function ok<T>(data: T): SuccessResponse<T> {
+  return { success: true, data };
+}
+
+export function fail(message: string, code?: string, details?: unknown): ErrorResponse {
+  return {
+    success: false,
+    error: { message, code, details },
+  };
+}
+
+export function paginated<T>(
+  data: T[],
+  total: number,
+  page: number,
+  limit: number
+): PaginatedResponse<T> {
+  return {
+    success: true,
+    data,
+    pagination: {
+      total,
+      page,
+      limit,
+      pages: Math.ceil(total / limit),
+    },
+  };
+}
+
+export function problem(detail: ProblemDetails): ErrorResponse & { problem: ProblemDetails } {
+  return {
+    success: false,
+    error: {
+      message: detail.title,
+      code: detail.type,
+      details: detail.detail,
+    },
+    problem: detail,
+  };
+}

package/src/validate.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+export interface ValidationSchemas {
+  body?: z.ZodType;
+  query?: z.ZodType;
+  params?: z.ZodType;
+  headers?: z.ZodType;
+}
+
+export interface ValidationResult {
+  success: boolean;
+  data?: Record<string, unknown>;
+  errors?: Record<string, string[]>;
+}
+
+export interface ValidatedRequest {
+  body?: unknown;
+  query?: unknown;
+  params?: unknown;
+  headers?: unknown;
+}
+
+function parseSchema(
+  schema: z.ZodType,
+  value: unknown,
+  label: string
+): { success: true; data: unknown } | { success: false; errors: string[] } {
+  try {
+    const data = schema.parse(value);
+    return { success: true, data };
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      const errors = err.issues.map((i) => `${label}.${i.path.join(".")}: ${i.message}`);
+      return { success: false, errors };
+    }
+    return { success: false, errors: [`${label}: Invalid value`] };
+  }
+}
+
+export function validateRequest(
+  schemas: ValidationSchemas,
+  request: { body?: unknown; query?: unknown; params?: unknown; headers?: unknown }
+): ValidationResult {
+  const allErrors: Record<string, string[]> = {};
+  const result: Record<string, unknown> = {};
+
+  for (const [key, schema] of Object.entries(schemas)) {
+    if (!schema) continue;
+    const input = request[key as keyof typeof request];
+    const parsed = parseSchema(schema, input, key);
+    if (!parsed.success) {
+      allErrors[key] = parsed.errors;
+    } else {
+      result[key] = parsed.data;
+    }
+  }
+
+  if (Object.keys(allErrors).length > 0) {
+    return { success: false, errors: allErrors };
+  }
+
+  return { success: true, data: result };
+}
+
+export function validate(schemas: ValidationSchemas) {
+  return (req: Request) => {
+    const url = new URL(req.url);
+
+    const searchParams: Record<string, string> = {};
+    url.searchParams.forEach((v, k) => {
+      searchParams[k] = v;
+    });
+
+    const result = validateRequest(schemas, {
+      body: req.body,
+      query: searchParams,
+      headers: Object.fromEntries(req.headers.entries()),
+    });
+
+    return result;
+  };
+}