@mandujs/core 0.53.3 → 0.54.0

package/src/middleware/rate-limit/index.ts

@@ -1,522 +1,522 @@
-/**
- * @mandujs/core/middleware/rate-limit
- *
- * Sliding-window rate limiter (Phase 6.1) with pluggable stores. Ships two
- * backends out of the box:
- *
- *   - {@link createInMemoryStore} — process-local `Map`, zero deps, dies on
- *     restart. The right choice for a single-process dev server or a small
- *     production deployment where a dropped-on-restart limiter is acceptable.
- *   - {@link createSqliteStore} — shared-file SQLite via `@mandujs/core/db`,
- *     WAL mode (per RFC 0001 Appendix D.4). Survives restarts and covers
- *     same-host multi-process; still NOT a distributed limiter (no
- *     multi-host coordination — add Redis in a follow-up phase if needed).
- *
- * ## Algorithm — sliding window via fixed bucket
- *
- * Each key owns a bucket `{ windowStart, count }`. On each hit:
- *
- *   - If `now - windowStart >= windowMs` → bucket rolls over: the new window
- *     starts at `now` with `count = 1`.
- *   - Else → `count++` inside the existing window.
- *
- * The request is `allowed` when `count <= limit`. `resetAt = windowStart +
- * windowMs`; `retryAfterSeconds = ceil((resetAt - now) / 1000)` when blocked.
- *
- * This is *not* a rolling-queue implementation (which would track every hit's
- * timestamp). For typical bursty traffic the observable behaviour is the
- * same — 1/ε the memory, 1/ε the work per hit, and no edge cases at the
- * window boundary. Token-bucket is explicitly deferred to v2 as an
- * alternative algorithm once a real-world use case justifies it.
- *
- * ## Usage
- *
- * ### As middleware
- *
- * ```ts
- * import { rateLimit } from "@mandujs/core/middleware/rate-limit";
- *
- * export default Mandu.filling()
- *   .use(rateLimit({ limit: 60, windowMs: 60_000 }))
- *   .post((ctx) => ctx.ok({ ok: true }));
- * ```
- *
- * ### As a guard for non-HTTP call sites
- *
- * The auth flows in Phase 5.3 (`verify.send`, `reset.send`) documented their
- * lack of rate limiting explicitly. Wrap them with the guard:
- *
- * ```ts
- * const sendGuard = createRateLimitGuard({ limit: 1, windowMs: 60_000 });
- * // later, at a POST handler:
- * await sendGuard.enforce(`verify:${userId}`);
- * await verify.send(userId, email);
- * ```
- *
- * Throwing {@link RateLimitError} carries the full {@link RateLimitResult}
- * so the caller can shape its own 429 response.
- *
- * @module middleware/rate-limit
- */
-
-import type { ManduContext } from "../../filling/context";
-
-// ─── Public types ───────────────────────────────────────────────────────────
-
-/** Outcome of a single `hit()` on a rate-limit store. */
-export interface RateLimitResult {
-  /** Whether the hit stayed within the configured budget. */
-  allowed: boolean;
-  /**
-   * Remaining budget in the current window, after this hit. Always clamped
-   * to `>= 0` — a blocked hit reports `0`.
-   */
-  remaining: number;
-  /** Unix ms at which the current window ends and a fresh one begins. */
-  resetAt: number;
-  /**
-   * `Math.ceil((resetAt - now) / 1000)` when blocked, `0` when allowed.
-   * Consumed directly as the `Retry-After` header value on 429 responses.
-   */
-  retryAfterSeconds: number;
-}
-
-/**
- * Pluggable backing store. Each call to {@link hit} atomically records a
- * single request against `key` and returns the resulting state — there is no
- * separate "read then increment" path to avoid race conditions.
- */
-export interface RateLimitStore {
-  /**
-   * Record one hit against `key` with `limit` / `windowMs` in effect. MUST
-   * be atomic: concurrent callers racing on the same key must observe a
-   * strictly-increasing count up to the rollover, never a lost update.
-   */
-  hit(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
-  /**
-   * Delete entries whose window is older than `olderThanMs` ago. Returns
-   * the number of entries purged. Safe to call on a hot store — the cron
-   * schedulers may do so on a fixed tick.
-   */
-  gcNow(olderThanMs: number): Promise<number>;
-  /** Release any held resources. Optional; safe to omit for in-memory stores. */
-  close?(): Promise<void>;
-}
-
-/** Construction options for {@link rateLimit}. */
-export interface RateLimitMiddlewareOptions {
-  /** Maximum hits per window. Required. Must be a positive integer. */
-  limit: number;
-  /** Window duration in ms. Required. Must be a positive integer. */
-  windowMs: number;
-  /** Store backend. Default: a fresh in-memory store (per middleware instance). */
-  store?: RateLimitStore;
-  /**
-   * Compute the rate-limit key for the current request. Returning `null`
-   * skips limiting for this request — the middleware passes through
-   * without touching the store.
-   *
-   * Default: first entry of `x-forwarded-for` header → `x-real-ip` →
-   * `"unknown"`. Production behind a trusted proxy should set XFF; otherwise
-   * use a session-user-id key via a custom `keyFn` to limit authenticated
-   * traffic per account instead of per (shared) IP.
-   */
-  keyFn?: (ctx: ManduContext) => string | null;
-  /**
-   * Predicate to bypass limiting for specific requests. Return `true` to
-   * skip entirely — the store is not consulted, no headers are emitted.
-   * Default: never skips.
-   */
-  skip?: (ctx: ManduContext) => boolean;
-  /**
-   * Build the 429 response body on block. Default: JSON
-   * `{ error: "rate_limited", retryAfterSeconds }`. Callers can override to
-   * match their app's error envelope.
-   */
-  handler?: (ctx: ManduContext, result: RateLimitResult) => Response;
-}
-
-/** Middleware signature matching `csrf.ts` / `session.ts`. */
-export type RateLimitMiddleware = (
-  ctx: ManduContext,
-) => Promise<Response | void>;
-
-/** Construction options for {@link createRateLimitGuard}. */
-export interface RateLimitGuardOptions {
-  limit: number;
-  windowMs: number;
-  /** Store backend. Default: a fresh in-memory store (per guard instance). */
-  store?: RateLimitStore;
-}
-
-/**
- * Imperative rate-limit handle for non-middleware call sites. Use
- * {@link RateLimitGuard.enforce} to wrap sensitive operations like
- * `verify.send(userId)` that don't live behind HTTP middleware.
- */
-export interface RateLimitGuard {
-  /**
-   * Record one hit and return the full result. Never throws — inspect
-   * `result.allowed` to branch.
-   */
-  check(key: string): Promise<RateLimitResult>;
-  /**
-   * Record one hit and throw {@link RateLimitError} when blocked. Resolves
-   * silently when allowed. Ideal for `await guard.enforce(...)` prologues.
-   */
-  enforce(key: string): Promise<void>;
-}
-
-/**
- * Error thrown by {@link RateLimitGuard.enforce} when a hit is blocked.
- * Carries the full {@link RateLimitResult} so the caller can format the
- * response with accurate `Retry-After` / `X-RateLimit-Reset` information.
- */
-export class RateLimitError extends Error {
-  /** Public so handlers can derive `Retry-After` without downcasting. */
-  readonly result: RateLimitResult;
-  constructor(result: RateLimitResult, message?: string) {
-    super(
-      message ??
-        `rate_limited: retry after ${result.retryAfterSeconds}s (reset at ${new Date(
-          result.resetAt,
-        ).toISOString()})`,
-    );
-    this.name = "RateLimitError";
-    this.result = result;
-  }
-}
-
-// ─── Constants ──────────────────────────────────────────────────────────────
-
-const DEFAULT_KEY_UNKNOWN = "unknown";
-
-/**
- * Clock injector. Kept module-scoped (not per-store) so tests can freeze time
- * across both the middleware and any stores it calls during a single
- * scenario. Override via {@link _setClockForTests}; production callers never
- * touch this.
- *
- * @internal
- */
-let __now: () => number = () => Date.now();
-
-/**
- * Replace the module-level clock. Test-only hook; not exported from the
- * package surface.
- *
- * @internal
- */
-export function _setClockForTests(fn: (() => number) | null): void {
-  __now = fn ?? (() => Date.now());
-}
-
-// ─── Key derivation ─────────────────────────────────────────────────────────
-
-/**
- * Default key derivation. Reads the first hop of `x-forwarded-for` (the
- * client IP when a trusted reverse proxy is in front), falling back to
- * `x-real-ip`, and finally a literal `"unknown"` bucket.
- *
- * The `"unknown"` fallback is intentionally a single shared bucket: when the
- * edge has not forwarded either header, we cannot tell callers apart, and a
- * hostile client could otherwise bypass the limit by simply stripping the
- * header. Shared throttling keeps the limiter safe but may be harsh on
- * no-proxy dev setups — set a custom `keyFn` that uses a session id, API
- * key, or user id for production traffic.
- */
-function defaultKeyFn(ctx: ManduContext): string {
-  const xff = ctx.request.headers.get("x-forwarded-for");
-  if (typeof xff === "string" && xff.length > 0) {
-    // XFF is a comma-separated chain; the client is the first entry.
-    const first = xff.split(",")[0]?.trim();
-    if (first && first.length > 0) return first;
-  }
-  const realIp = ctx.request.headers.get("x-real-ip");
-  if (typeof realIp === "string" && realIp.length > 0) return realIp.trim();
-  return DEFAULT_KEY_UNKNOWN;
-}
-
-// ─── Middleware factory ─────────────────────────────────────────────────────
-
-function assertPositiveInt(name: string, value: number): void {
-  if (
-    typeof value !== "number" ||
-    !Number.isFinite(value) ||
-    value <= 0 ||
-    Math.floor(value) !== value
-  ) {
-    throw new TypeError(
-      `[@mandujs/core/middleware/rate-limit] '${name}' must be a positive integer; got ${String(
-        value,
-      )}.`,
-    );
-  }
-}
-
-/**
- * Sliding-window rate-limit middleware.
- *
- * Behaviour:
- *   1. If `skip(ctx)` returns `true`, the middleware returns void immediately
- *      — no store access, no headers.
- *   2. Otherwise, `keyFn(ctx)` produces a key. `null` skips the store (useful
- *      for "only limit authenticated traffic" policies).
- *   3. `store.hit(key, limit, windowMs)` records and evaluates.
- *   4. On block: returns 429 with `Retry-After` + `X-RateLimit-*` headers and
- *      a JSON body (or whatever `handler` returns). The caller's handler
- *      pipeline is short-circuited.
- *   5. On allow: returns void. No response mutation is performed here — the
- *      middleware surface has no afterHandle hook on this variant. Callers
- *      who want `X-RateLimit-*` headers on allowed responses should use
- *      {@link rateLimitPlugin} (exposes beforeHandle + afterHandle) instead.
- */
-export function rateLimit(
-  options: RateLimitMiddlewareOptions,
-): RateLimitMiddleware {
-  if (!options || typeof options !== "object") {
-    throw new TypeError(
-      "[@mandujs/core/middleware/rate-limit] rateLimit: options object required.",
-    );
-  }
-  assertPositiveInt("limit", options.limit);
-  assertPositiveInt("windowMs", options.windowMs);
-
-  const limit = options.limit;
-  const windowMs = options.windowMs;
-  const store = options.store ?? createInMemoryStore();
-  const keyFn = options.keyFn ?? defaultKeyFn;
-  const skip = options.skip;
-  const handler = options.handler ?? defaultBlockedHandler;
-
-  return async (ctx: ManduContext): Promise<Response | void> => {
-    if (skip && skip(ctx)) {
-      return;
-    }
-    const key = keyFn(ctx);
-    if (key === null) {
-      // Caller's key function explicitly opts out for this request.
-      return;
-    }
-
-    const result = await store.hit(key, limit, windowMs);
-
-    if (!result.allowed) {
-      const res = handler(ctx, result);
-      // The caller's `handler` may return a pre-built Response that already
-      // carries rate-limit headers. We only stamp them when absent so a
-      // custom handler that wants to hide the Retry-After (rare) can do so.
-      return applyRateLimitHeaders(res, limit, result);
-    }
-
-    // Allowed: pass through. Callers who need `X-RateLimit-*` headers on
-    // successful responses should layer {@link rateLimitPlugin} on top of
-    // the filling chain — this plain-middleware variant cannot mutate the
-    // outgoing Response without an afterHandle hook.
-    return;
-  };
-}
-
-/**
- * Default 429 response body. Intentionally small — exposes only what a
- * well-behaved client legitimately needs. `resetAt` is Unix-ms so clients
- * don't have to negotiate timezone interpretation.
- */
-function defaultBlockedHandler(
-  _ctx: ManduContext,
-  result: RateLimitResult,
-): Response {
-  return Response.json(
-    {
-      error: "rate_limited",
-      retryAfterSeconds: result.retryAfterSeconds,
-      resetAt: result.resetAt,
-    },
-    { status: 429 },
-  );
-}
-
-/**
- * Stamp `Retry-After` + `X-RateLimit-*` headers on a blocked response. The
- * `X-RateLimit-Reset` value is Unix-seconds (not ms) to match the informal
- * convention used by GitHub / Twitter / Stripe — see GitHub's API docs.
- *
- * Preserves any header the caller's handler has already set (checked with
- * `Headers.has`) so custom handlers can override values at will.
- */
-function applyRateLimitHeaders(
-  response: Response,
-  limit: number,
-  result: RateLimitResult,
-): Response {
-  const headers = new Headers(response.headers);
-  if (!headers.has("Retry-After")) {
-    headers.set("Retry-After", String(result.retryAfterSeconds));
-  }
-  if (!headers.has("X-RateLimit-Limit")) {
-    headers.set("X-RateLimit-Limit", String(limit));
-  }
-  if (!headers.has("X-RateLimit-Remaining")) {
-    headers.set("X-RateLimit-Remaining", String(result.remaining));
-  }
-  if (!headers.has("X-RateLimit-Reset")) {
-    headers.set(
-      "X-RateLimit-Reset",
-      String(Math.floor(result.resetAt / 1000)),
-    );
-  }
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
-}
-
-// ─── Guard (imperative) ─────────────────────────────────────────────────────
-
-/**
- * Construct an imperative rate-limit guard. Use when the protected operation
- * is NOT an HTTP handler — e.g. an outbound email from a server-side action.
- *
- * Every guard owns its own store by default, so two guards with the same
- * `{ limit, windowMs }` are independent. Share a store explicitly when two
- * guards must consume the same budget.
- */
-export function createRateLimitGuard(
-  options: RateLimitGuardOptions,
-): RateLimitGuard {
-  if (!options || typeof options !== "object") {
-    throw new TypeError(
-      "[@mandujs/core/middleware/rate-limit] createRateLimitGuard: options object required.",
-    );
-  }
-  assertPositiveInt("limit", options.limit);
-  assertPositiveInt("windowMs", options.windowMs);
-
-  const limit = options.limit;
-  const windowMs = options.windowMs;
-  const store = options.store ?? createInMemoryStore();
-
-  return {
-    async check(key: string): Promise<RateLimitResult> {
-      if (typeof key !== "string" || key.length === 0) {
-        throw new TypeError(
-          "[@mandujs/core/middleware/rate-limit] check: key must be a non-empty string.",
-        );
-      }
-      return await store.hit(key, limit, windowMs);
-    },
-    async enforce(key: string): Promise<void> {
-      if (typeof key !== "string" || key.length === 0) {
-        throw new TypeError(
-          "[@mandujs/core/middleware/rate-limit] enforce: key must be a non-empty string.",
-        );
-      }
-      const result = await store.hit(key, limit, windowMs);
-      if (!result.allowed) {
-        throw new RateLimitError(result);
-      }
-    },
-  };
-}
-
-// ─── In-memory store ────────────────────────────────────────────────────────
-
-interface Bucket {
-  windowStart: number;
-  count: number;
-}
-
-/**
- * Process-local in-memory store. No external dependencies, no persistence
- * across restarts. Concurrency-safe within a single event loop (Map reads
- * and writes are not preempted mid-operation in JS); no locking needed.
- *
- * Not safe across processes or hosts — use {@link createSqliteStore} for
- * same-host multi-process, or a distributed store (future Redis backend)
- * for multi-host.
- */
-export function createInMemoryStore(): RateLimitStore {
-  const buckets = new Map<string, Bucket>();
-  let closed = false;
-
-  return {
-    async hit(
-      key: string,
-      limit: number,
-      windowMs: number,
-    ): Promise<RateLimitResult> {
-      if (closed) {
-        throw new Error(
-          "[@mandujs/core/middleware/rate-limit] in-memory store is closed.",
-        );
-      }
-      const now = __now();
-      const existing = buckets.get(key);
-
-      let bucket: Bucket;
-      if (!existing || now - existing.windowStart >= windowMs) {
-        // Window rollover (or first hit). Start a fresh window anchored at
-        // `now` — the simplest model that still reports a precise resetAt.
-        bucket = { windowStart: now, count: 1 };
-      } else {
-        // Still inside the current window — increment.
-        bucket = { windowStart: existing.windowStart, count: existing.count + 1 };
-      }
-      buckets.set(key, bucket);
-
-      const resetAt = bucket.windowStart + windowMs;
-      const allowed = bucket.count <= limit;
-      // `remaining` reports post-hit budget; clamped at 0 so a blocked hit
-      // never reports negative remaining (would confuse clients rendering a
-      // progress indicator).
-      const remaining = Math.max(0, limit - bucket.count);
-      const retryAfterSeconds = allowed
-        ? 0
-        : Math.max(1, Math.ceil((resetAt - now) / 1000));
-
-      return { allowed, remaining, resetAt, retryAfterSeconds };
-    },
-
-    async gcNow(olderThanMs: number): Promise<number> {
-      if (closed) return 0;
-      if (typeof olderThanMs !== "number" || olderThanMs < 0) {
-        throw new TypeError(
-          "[@mandujs/core/middleware/rate-limit] gcNow: olderThanMs must be a non-negative number.",
-        );
-      }
-      const now = __now();
-      let deleted = 0;
-      // Iterating + deleting from a Map during traversal is safe per the
-      // ES spec — entries visited before deletion yield, already-visited
-      // entries are skipped. We still collect keys into a throwaway array
-      // to keep the hot-path clean across engines.
-      const stale: string[] = [];
-      for (const [key, bucket] of buckets) {
-        if (now - bucket.windowStart > olderThanMs) {
-          stale.push(key);
-        }
-      }
-      for (const key of stale) {
-        buckets.delete(key);
-        deleted++;
-      }
-      return deleted;
-    },
-
-    async close(): Promise<void> {
-      if (closed) return;
-      closed = true;
-      buckets.clear();
-    },
-  };
-}
-
-// ─── SQLite store (re-export) ───────────────────────────────────────────────
-
-// The SQLite store lives in its own module so callers who never need it
-// don't pay the import cost of `@mandujs/core/db`.
-export {
-  createSqliteStore,
-  type SqliteRateLimitStoreOptions,
-} from "./sqlite-store";
+/**
+ * @mandujs/core/middleware/rate-limit
+ *
+ * Sliding-window rate limiter (Phase 6.1) with pluggable stores. Ships two
+ * backends out of the box:
+ *
+ *   - {@link createInMemoryStore} — process-local `Map`, zero deps, dies on
+ *     restart. The right choice for a single-process dev server or a small
+ *     production deployment where a dropped-on-restart limiter is acceptable.
+ *   - {@link createSqliteStore} — shared-file SQLite via `@mandujs/core/db`,
+ *     WAL mode (per RFC 0001 Appendix D.4). Survives restarts and covers
+ *     same-host multi-process; still NOT a distributed limiter (no
+ *     multi-host coordination — add Redis in a follow-up phase if needed).
+ *
+ * ## Algorithm — sliding window via fixed bucket
+ *
+ * Each key owns a bucket `{ windowStart, count }`. On each hit:
+ *
+ *   - If `now - windowStart >= windowMs` → bucket rolls over: the new window
+ *     starts at `now` with `count = 1`.
+ *   - Else → `count++` inside the existing window.
+ *
+ * The request is `allowed` when `count <= limit`. `resetAt = windowStart +
+ * windowMs`; `retryAfterSeconds = ceil((resetAt - now) / 1000)` when blocked.
+ *
+ * This is *not* a rolling-queue implementation (which would track every hit's
+ * timestamp). For typical bursty traffic the observable behaviour is the
+ * same — 1/ε the memory, 1/ε the work per hit, and no edge cases at the
+ * window boundary. Token-bucket is explicitly deferred to v2 as an
+ * alternative algorithm once a real-world use case justifies it.
+ *
+ * ## Usage
+ *
+ * ### As middleware
+ *
+ * ```ts
+ * import { rateLimit } from "@mandujs/core/middleware/rate-limit";
+ *
+ * export default Mandu.filling()
+ *   .use(rateLimit({ limit: 60, windowMs: 60_000 }))
+ *   .post((ctx) => ctx.ok({ ok: true }));
+ * ```
+ *
+ * ### As a guard for non-HTTP call sites
+ *
+ * The auth flows in Phase 5.3 (`verify.send`, `reset.send`) documented their
+ * lack of rate limiting explicitly. Wrap them with the guard:
+ *
+ * ```ts
+ * const sendGuard = createRateLimitGuard({ limit: 1, windowMs: 60_000 });
+ * // later, at a POST handler:
+ * await sendGuard.enforce(`verify:${userId}`);
+ * await verify.send(userId, email);
+ * ```
+ *
+ * Throwing {@link RateLimitError} carries the full {@link RateLimitResult}
+ * so the caller can shape its own 429 response.
+ *
+ * @module middleware/rate-limit
+ */
+
+import type { ManduContext } from "../../filling/context";
+
+// ─── Public types ───────────────────────────────────────────────────────────
+
+/** Outcome of a single `hit()` on a rate-limit store. */
+export interface RateLimitResult {
+  /** Whether the hit stayed within the configured budget. */
+  allowed: boolean;
+  /**
+   * Remaining budget in the current window, after this hit. Always clamped
+   * to `>= 0` — a blocked hit reports `0`.
+   */
+  remaining: number;
+  /** Unix ms at which the current window ends and a fresh one begins. */
+  resetAt: number;
+  /**
+   * `Math.ceil((resetAt - now) / 1000)` when blocked, `0` when allowed.
+   * Consumed directly as the `Retry-After` header value on 429 responses.
+   */
+  retryAfterSeconds: number;
+}
+
+/**
+ * Pluggable backing store. Each call to {@link hit} atomically records a
+ * single request against `key` and returns the resulting state — there is no
+ * separate "read then increment" path to avoid race conditions.
+ */
+export interface RateLimitStore {
+  /**
+   * Record one hit against `key` with `limit` / `windowMs` in effect. MUST
+   * be atomic: concurrent callers racing on the same key must observe a
+   * strictly-increasing count up to the rollover, never a lost update.
+   */
+  hit(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+  /**
+   * Delete entries whose window is older than `olderThanMs` ago. Returns
+   * the number of entries purged. Safe to call on a hot store — the cron
+   * schedulers may do so on a fixed tick.
+   */
+  gcNow(olderThanMs: number): Promise<number>;
+  /** Release any held resources. Optional; safe to omit for in-memory stores. */
+  close?(): Promise<void>;
+}
+
+/** Construction options for {@link rateLimit}. */
+export interface RateLimitMiddlewareOptions {
+  /** Maximum hits per window. Required. Must be a positive integer. */
+  limit: number;
+  /** Window duration in ms. Required. Must be a positive integer. */
+  windowMs: number;
+  /** Store backend. Default: a fresh in-memory store (per middleware instance). */
+  store?: RateLimitStore;
+  /**
+   * Compute the rate-limit key for the current request. Returning `null`
+   * skips limiting for this request — the middleware passes through
+   * without touching the store.
+   *
+   * Default: first entry of `x-forwarded-for` header → `x-real-ip` →
+   * `"unknown"`. Production behind a trusted proxy should set XFF; otherwise
+   * use a session-user-id key via a custom `keyFn` to limit authenticated
+   * traffic per account instead of per (shared) IP.
+   */
+  keyFn?: (ctx: ManduContext) => string | null;
+  /**
+   * Predicate to bypass limiting for specific requests. Return `true` to
+   * skip entirely — the store is not consulted, no headers are emitted.
+   * Default: never skips.
+   */
+  skip?: (ctx: ManduContext) => boolean;
+  /**
+   * Build the 429 response body on block. Default: JSON
+   * `{ error: "rate_limited", retryAfterSeconds }`. Callers can override to
+   * match their app's error envelope.
+   */
+  handler?: (ctx: ManduContext, result: RateLimitResult) => Response;
+}
+
+/** Middleware signature matching `csrf.ts` / `session.ts`. */
+export type RateLimitMiddleware = (
+  ctx: ManduContext,
+) => Promise<Response | void>;
+
+/** Construction options for {@link createRateLimitGuard}. */
+export interface RateLimitGuardOptions {
+  limit: number;
+  windowMs: number;
+  /** Store backend. Default: a fresh in-memory store (per guard instance). */
+  store?: RateLimitStore;
+}
+
+/**
+ * Imperative rate-limit handle for non-middleware call sites. Use
+ * {@link RateLimitGuard.enforce} to wrap sensitive operations like
+ * `verify.send(userId)` that don't live behind HTTP middleware.
+ */
+export interface RateLimitGuard {
+  /**
+   * Record one hit and return the full result. Never throws — inspect
+   * `result.allowed` to branch.
+   */
+  check(key: string): Promise<RateLimitResult>;
+  /**
+   * Record one hit and throw {@link RateLimitError} when blocked. Resolves
+   * silently when allowed. Ideal for `await guard.enforce(...)` prologues.
+   */
+  enforce(key: string): Promise<void>;
+}
+
+/**
+ * Error thrown by {@link RateLimitGuard.enforce} when a hit is blocked.
+ * Carries the full {@link RateLimitResult} so the caller can format the
+ * response with accurate `Retry-After` / `X-RateLimit-Reset` information.
+ */
+export class RateLimitError extends Error {
+  /** Public so handlers can derive `Retry-After` without downcasting. */
+  readonly result: RateLimitResult;
+  constructor(result: RateLimitResult, message?: string) {
+    super(
+      message ??
+        `rate_limited: retry after ${result.retryAfterSeconds}s (reset at ${new Date(
+          result.resetAt,
+        ).toISOString()})`,
+    );
+    this.name = "RateLimitError";
+    this.result = result;
+  }
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const DEFAULT_KEY_UNKNOWN = "unknown";
+
+/**
+ * Clock injector. Kept module-scoped (not per-store) so tests can freeze time
+ * across both the middleware and any stores it calls during a single
+ * scenario. Override via {@link _setClockForTests}; production callers never
+ * touch this.
+ *
+ * @internal
+ */
+let __now: () => number = () => Date.now();
+
+/**
+ * Replace the module-level clock. Test-only hook; not exported from the
+ * package surface.
+ *
+ * @internal
+ */
+export function _setClockForTests(fn: (() => number) | null): void {
+  __now = fn ?? (() => Date.now());
+}
+
+// ─── Key derivation ─────────────────────────────────────────────────────────
+
+/**
+ * Default key derivation. Reads the first hop of `x-forwarded-for` (the
+ * client IP when a trusted reverse proxy is in front), falling back to
+ * `x-real-ip`, and finally a literal `"unknown"` bucket.
+ *
+ * The `"unknown"` fallback is intentionally a single shared bucket: when the
+ * edge has not forwarded either header, we cannot tell callers apart, and a
+ * hostile client could otherwise bypass the limit by simply stripping the
+ * header. Shared throttling keeps the limiter safe but may be harsh on
+ * no-proxy dev setups — set a custom `keyFn` that uses a session id, API
+ * key, or user id for production traffic.
+ */
+function defaultKeyFn(ctx: ManduContext): string {
+  const xff = ctx.request.headers.get("x-forwarded-for");
+  if (typeof xff === "string" && xff.length > 0) {
+    // XFF is a comma-separated chain; the client is the first entry.
+    const first = xff.split(",")[0]?.trim();
+    if (first && first.length > 0) return first;
+  }
+  const realIp = ctx.request.headers.get("x-real-ip");
+  if (typeof realIp === "string" && realIp.length > 0) return realIp.trim();
+  return DEFAULT_KEY_UNKNOWN;
+}
+
+// ─── Middleware factory ─────────────────────────────────────────────────────
+
+function assertPositiveInt(name: string, value: number): void {
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value <= 0 ||
+    Math.floor(value) !== value
+  ) {
+    throw new TypeError(
+      `[@mandujs/core/middleware/rate-limit] '${name}' must be a positive integer; got ${String(
+        value,
+      )}.`,
+    );
+  }
+}
+
+/**
+ * Sliding-window rate-limit middleware.
+ *
+ * Behaviour:
+ *   1. If `skip(ctx)` returns `true`, the middleware returns void immediately
+ *      — no store access, no headers.
+ *   2. Otherwise, `keyFn(ctx)` produces a key. `null` skips the store (useful
+ *      for "only limit authenticated traffic" policies).
+ *   3. `store.hit(key, limit, windowMs)` records and evaluates.
+ *   4. On block: returns 429 with `Retry-After` + `X-RateLimit-*` headers and
+ *      a JSON body (or whatever `handler` returns). The caller's handler
+ *      pipeline is short-circuited.
+ *   5. On allow: returns void. No response mutation is performed here — the
+ *      middleware surface has no afterHandle hook on this variant. Callers
+ *      who want `X-RateLimit-*` headers on allowed responses should use
+ *      {@link rateLimitPlugin} (exposes beforeHandle + afterHandle) instead.
+ */
+export function rateLimit(
+  options: RateLimitMiddlewareOptions,
+): RateLimitMiddleware {
+  if (!options || typeof options !== "object") {
+    throw new TypeError(
+      "[@mandujs/core/middleware/rate-limit] rateLimit: options object required.",
+    );
+  }
+  assertPositiveInt("limit", options.limit);
+  assertPositiveInt("windowMs", options.windowMs);
+
+  const limit = options.limit;
+  const windowMs = options.windowMs;
+  const store = options.store ?? createInMemoryStore();
+  const keyFn = options.keyFn ?? defaultKeyFn;
+  const skip = options.skip;
+  const handler = options.handler ?? defaultBlockedHandler;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    if (skip && skip(ctx)) {
+      return;
+    }
+    const key = keyFn(ctx);
+    if (key === null) {
+      // Caller's key function explicitly opts out for this request.
+      return;
+    }
+
+    const result = await store.hit(key, limit, windowMs);
+
+    if (!result.allowed) {
+      const res = handler(ctx, result);
+      // The caller's `handler` may return a pre-built Response that already
+      // carries rate-limit headers. We only stamp them when absent so a
+      // custom handler that wants to hide the Retry-After (rare) can do so.
+      return applyRateLimitHeaders(res, limit, result);
+    }
+
+    // Allowed: pass through. Callers who need `X-RateLimit-*` headers on
+    // successful responses should layer {@link rateLimitPlugin} on top of
+    // the filling chain — this plain-middleware variant cannot mutate the
+    // outgoing Response without an afterHandle hook.
+    return;
+  };
+}
+
+/**
+ * Default 429 response body. Intentionally small — exposes only what a
+ * well-behaved client legitimately needs. `resetAt` is Unix-ms so clients
+ * don't have to negotiate timezone interpretation.
+ */
+function defaultBlockedHandler(
+  _ctx: ManduContext,
+  result: RateLimitResult,
+): Response {
+  return Response.json(
+    {
+      error: "rate_limited",
+      retryAfterSeconds: result.retryAfterSeconds,
+      resetAt: result.resetAt,
+    },
+    { status: 429 },
+  );
+}
+
+/**
+ * Stamp `Retry-After` + `X-RateLimit-*` headers on a blocked response. The
+ * `X-RateLimit-Reset` value is Unix-seconds (not ms) to match the informal
+ * convention used by GitHub / Twitter / Stripe — see GitHub's API docs.
+ *
+ * Preserves any header the caller's handler has already set (checked with
+ * `Headers.has`) so custom handlers can override values at will.
+ */
+function applyRateLimitHeaders(
+  response: Response,
+  limit: number,
+  result: RateLimitResult,
+): Response {
+  const headers = new Headers(response.headers);
+  if (!headers.has("Retry-After")) {
+    headers.set("Retry-After", String(result.retryAfterSeconds));
+  }
+  if (!headers.has("X-RateLimit-Limit")) {
+    headers.set("X-RateLimit-Limit", String(limit));
+  }
+  if (!headers.has("X-RateLimit-Remaining")) {
+    headers.set("X-RateLimit-Remaining", String(result.remaining));
+  }
+  if (!headers.has("X-RateLimit-Reset")) {
+    headers.set(
+      "X-RateLimit-Reset",
+      String(Math.floor(result.resetAt / 1000)),
+    );
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// ─── Guard (imperative) ─────────────────────────────────────────────────────
+
+/**
+ * Construct an imperative rate-limit guard. Use when the protected operation
+ * is NOT an HTTP handler — e.g. an outbound email from a server-side action.
+ *
+ * Every guard owns its own store by default, so two guards with the same
+ * `{ limit, windowMs }` are independent. Share a store explicitly when two
+ * guards must consume the same budget.
+ */
+export function createRateLimitGuard(
+  options: RateLimitGuardOptions,
+): RateLimitGuard {
+  if (!options || typeof options !== "object") {
+    throw new TypeError(
+      "[@mandujs/core/middleware/rate-limit] createRateLimitGuard: options object required.",
+    );
+  }
+  assertPositiveInt("limit", options.limit);
+  assertPositiveInt("windowMs", options.windowMs);
+
+  const limit = options.limit;
+  const windowMs = options.windowMs;
+  const store = options.store ?? createInMemoryStore();
+
+  return {
+    async check(key: string): Promise<RateLimitResult> {
+      if (typeof key !== "string" || key.length === 0) {
+        throw new TypeError(
+          "[@mandujs/core/middleware/rate-limit] check: key must be a non-empty string.",
+        );
+      }
+      return await store.hit(key, limit, windowMs);
+    },
+    async enforce(key: string): Promise<void> {
+      if (typeof key !== "string" || key.length === 0) {
+        throw new TypeError(
+          "[@mandujs/core/middleware/rate-limit] enforce: key must be a non-empty string.",
+        );
+      }
+      const result = await store.hit(key, limit, windowMs);
+      if (!result.allowed) {
+        throw new RateLimitError(result);
+      }
+    },
+  };
+}
+
+// ─── In-memory store ────────────────────────────────────────────────────────
+
+interface Bucket {
+  windowStart: number;
+  count: number;
+}
+
+/**
+ * Process-local in-memory store. No external dependencies, no persistence
+ * across restarts. Concurrency-safe within a single event loop (Map reads
+ * and writes are not preempted mid-operation in JS); no locking needed.
+ *
+ * Not safe across processes or hosts — use {@link createSqliteStore} for
+ * same-host multi-process, or a distributed store (future Redis backend)
+ * for multi-host.
+ */
+export function createInMemoryStore(): RateLimitStore {
+  const buckets = new Map<string, Bucket>();
+  let closed = false;
+
+  return {
+    async hit(
+      key: string,
+      limit: number,
+      windowMs: number,
+    ): Promise<RateLimitResult> {
+      if (closed) {
+        throw new Error(
+          "[@mandujs/core/middleware/rate-limit] in-memory store is closed.",
+        );
+      }
+      const now = __now();
+      const existing = buckets.get(key);
+
+      let bucket: Bucket;
+      if (!existing || now - existing.windowStart >= windowMs) {
+        // Window rollover (or first hit). Start a fresh window anchored at
+        // `now` — the simplest model that still reports a precise resetAt.
+        bucket = { windowStart: now, count: 1 };
+      } else {
+        // Still inside the current window — increment.
+        bucket = { windowStart: existing.windowStart, count: existing.count + 1 };
+      }
+      buckets.set(key, bucket);
+
+      const resetAt = bucket.windowStart + windowMs;
+      const allowed = bucket.count <= limit;
+      // `remaining` reports post-hit budget; clamped at 0 so a blocked hit
+      // never reports negative remaining (would confuse clients rendering a
+      // progress indicator).
+      const remaining = Math.max(0, limit - bucket.count);
+      const retryAfterSeconds = allowed
+        ? 0
+        : Math.max(1, Math.ceil((resetAt - now) / 1000));
+
+      return { allowed, remaining, resetAt, retryAfterSeconds };
+    },
+
+    async gcNow(olderThanMs: number): Promise<number> {
+      if (closed) return 0;
+      if (typeof olderThanMs !== "number" || olderThanMs < 0) {
+        throw new TypeError(
+          "[@mandujs/core/middleware/rate-limit] gcNow: olderThanMs must be a non-negative number.",
+        );
+      }
+      const now = __now();
+      let deleted = 0;
+      // Iterating + deleting from a Map during traversal is safe per the
+      // ES spec — entries visited before deletion yield, already-visited
+      // entries are skipped. We still collect keys into a throwaway array
+      // to keep the hot-path clean across engines.
+      const stale: string[] = [];
+      for (const [key, bucket] of buckets) {
+        if (now - bucket.windowStart > olderThanMs) {
+          stale.push(key);
+        }
+      }
+      for (const key of stale) {
+        buckets.delete(key);
+        deleted++;
+      }
+      return deleted;
+    },
+
+    async close(): Promise<void> {
+      if (closed) return;
+      closed = true;
+      buckets.clear();
+    },
+  };
+}
+
+// ─── SQLite store (re-export) ───────────────────────────────────────────────
+
+// The SQLite store lives in its own module so callers who never need it
+// don't pay the import cost of `@mandujs/core/db`.
+export {
+  createSqliteStore,
+  type SqliteRateLimitStoreOptions,
+} from "./sqlite-store";