@voyant-travel/hono 0.109.1

package/dist/middleware/public-cache.js

@@ -0,0 +1,205 @@
+import { tryGetExecutionCtx } from "../lib/execution-ctx.js";
+const DEFAULT_PREFIXES = ["/v1/public/"];
+const DEFAULT_MAX_KV_BODY_BYTES = 2 * 1024 * 1024;
+const KV_KEY_PREFIX = "respcache:v1:";
+/** Cloudflare KV rejects expirationTtl below 60 seconds. */
+const KV_MIN_TTL_SECONDS = 60;
+/**
+ * Headers never persisted into the shared cache: per-request identifiers
+ * and CORS grants are recomputed for every requester (the cors middleware
+ * runs upstream and decorates cache hits like any other response).
+ */
+function isUncacheableHeader(name) {
+    const lower = name.toLowerCase();
+    return lower === "set-cookie" || lower === "x-request-id" || lower.startsWith("access-control-");
+}
+function parseCacheControl(value) {
+    if (!value)
+        return { isPublic: false, sMaxage: null };
+    let isPublic = false;
+    let sMaxage = null;
+    for (const part of value.split(",")) {
+        const directive = part.trim().toLowerCase();
+        if (directive === "public")
+            isPublic = true;
+        else if (directive === "private" || directive === "no-store") {
+            return { isPublic: false, sMaxage: null };
+        }
+        else if (directive.startsWith("s-maxage=")) {
+            const parsed = Number.parseInt(directive.slice("s-maxage=".length), 10);
+            if (Number.isFinite(parsed) && parsed > 0)
+                sMaxage = parsed;
+        }
+    }
+    return { isPublic, sMaxage };
+}
+/**
+ * `caches.default` is available on regular Cloudflare Workers but
+ * DISABLED inside Workers-for-Platforms namespaced scripts (access or
+ * use throws). Probe once, and demote to "unavailable" on any runtime
+ * failure so namespaced deployments settle on the KV fallback after a
+ * single failed attempt.
+ */
+let cacheApiState = "unknown";
+function getCacheApi() {
+    if (cacheApiState === "unavailable")
+        return undefined;
+    try {
+        const candidate = globalThis.caches?.default;
+        if (candidate && typeof candidate.match === "function") {
+            cacheApiState = "available";
+            return candidate;
+        }
+    }
+    catch {
+        // fall through to unavailable
+    }
+    cacheApiState = "unavailable";
+    return undefined;
+}
+function markCacheApiUnavailable() {
+    cacheApiState = "unavailable";
+}
+/** Test hook — resets the memoized Cache API probe state. */
+export function resetPublicCacheStateForTests() {
+    cacheApiState = "unknown";
+}
+function sanitizedResponseCopy(res) {
+    const headers = new Headers();
+    res.headers.forEach((value, name) => {
+        if (!isUncacheableHeader(name))
+            headers.set(name, value);
+    });
+    headers.set("x-voyant-cache", "hit");
+    return new Response(res.body, { status: res.status, headers });
+}
+function kvKeyFor(url) {
+    return `${KV_KEY_PREFIX}${url}`;
+}
+async function kvMatch(kv, url) {
+    try {
+        const entry = await kv.get(kvKeyFor(url), { type: "json" });
+        if (!entry || typeof entry.body !== "string")
+            return undefined;
+        const headers = new Headers(entry.headers);
+        headers.set("x-voyant-cache", "hit");
+        return new Response(entry.body, { status: entry.status, headers });
+    }
+    catch {
+        return undefined;
+    }
+}
+async function kvStore(kv, url, res, ttlSeconds, maxBodyBytes) {
+    try {
+        const body = await res.text();
+        if (body.length > maxBodyBytes)
+            return;
+        const headers = [];
+        res.headers.forEach((value, name) => {
+            if (!isUncacheableHeader(name))
+                headers.push([name, value]);
+        });
+        const entry = { status: res.status, headers, body };
+        await kv.put(kvKeyFor(url), JSON.stringify(entry), {
+            expirationTtl: Math.max(KV_MIN_TTL_SECONDS, ttlSeconds),
+        });
+    }
+    catch {
+        // cache writes are best-effort — never surface to the request
+    }
+}
+/**
+ * Shared response cache for the public API surface.
+ *
+ * Fail-closed by design: a response is only ever cached when the route
+ * explicitly marked it shareable — `Cache-Control` containing `public`
+ * AND a positive `s-maxage` — and it carries no `Set-Cookie`. Routes
+ * emit `private`/`no-store` (or nothing) to opt out, so personalized
+ * endpoints under `/v1/public/*` (customer portal, verification) are
+ * never cached by accident.
+ *
+ * Cache hits are served before auth, the DB middleware, and the runtime
+ * bootstrap — a hit costs no Postgres connection, no session lookup,
+ * and no module-graph instantiation, which is the entire point under
+ * storefront load (#1686).
+ *
+ * Backend selection: Cache API (`caches.default`) where the runtime
+ * provides it; otherwise the `env.CACHE` KV binding when present;
+ * otherwise the middleware is a transparent no-op.
+ */
+export function publicResponseCache(options = {}) {
+    const prefixes = options.pathPrefixes ?? DEFAULT_PREFIXES;
+    const maxKvBodyBytes = options.maxKvBodyBytes ?? DEFAULT_MAX_KV_BODY_BYTES;
+    return async (c, next) => {
+        if (c.req.method !== "GET")
+            return next();
+        const path = c.req.path;
+        if (!prefixes.some((prefix) => path.startsWith(prefix)))
+            return next();
+        // Standard escape hatch: a requester (or a debugging operator) can
+        // force revalidation with `Cache-Control: no-cache`.
+        const requestDirective = c.req.header("cache-control")?.toLowerCase() ?? "";
+        const bypass = requestDirective.includes("no-cache") || requestDirective.includes("no-store");
+        const url = c.req.url;
+        const cacheApi = getCacheApi();
+        const kv = !cacheApi ? c.env.CACHE : undefined;
+        if (!bypass) {
+            if (cacheApi) {
+                try {
+                    const hit = await cacheApi.match(url);
+                    if (hit)
+                        return sanitizedResponseCopy(hit);
+                }
+                catch {
+                    markCacheApiUnavailable();
+                }
+            }
+            else if (kv) {
+                const hit = await kvMatch(kv, url);
+                if (hit)
+                    return hit;
+            }
+        }
+        await next();
+        const res = c.res;
+        if (!res || res.status !== 200)
+            return;
+        if (res.headers.has("set-cookie"))
+            return;
+        const { isPublic, sMaxage } = parseCacheControl(res.headers.get("cache-control"));
+        if (!isPublic || !sMaxage)
+            return;
+        const backendCacheApi = getCacheApi();
+        const backendKv = !backendCacheApi ? c.env.CACHE : undefined;
+        if (!backendCacheApi && !backendKv)
+            return;
+        const copy = res.clone();
+        const store = (async () => {
+            if (backendCacheApi) {
+                try {
+                    const headers = new Headers();
+                    copy.headers.forEach((value, name) => {
+                        if (!isUncacheableHeader(name))
+                            headers.set(name, value);
+                    });
+                    await backendCacheApi.put(url, new Response(copy.body, { status: copy.status, headers }));
+                    return;
+                }
+                catch {
+                    markCacheApiUnavailable();
+                }
+            }
+            const fallbackKv = backendKv ?? c.env.CACHE;
+            if (fallbackKv) {
+                await kvStore(fallbackKv, url, copy, sMaxage, maxKvBodyBytes);
+            }
+        })();
+        const executionCtx = tryGetExecutionCtx(c);
+        if (executionCtx) {
+            executionCtx.waitUntil(store);
+        }
+        else {
+            await store;
+        }
+    };
+}

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,214 @@
+import type { KVStore } from "@voyant-travel/utils/cache";
+import type { MiddlewareHandler } from "hono";
+/**
+ * Distributed-capable rate limiting (security finding C2).
+ *
+ * The limiter is split into two halves:
+ *
+ * - a {@link RateLimitStore} — the counting backend. Three implementations
+ *   ship with the framework: the Cloudflare native Rate Limiting binding
+ *   (truly distributed, limits configured in wrangler), a KV-backed
+ *   fixed-window counter (best-effort — see {@link createKvRateLimitStore}),
+ *   and an in-memory Map for Node/dev/tests (per-isolate).
+ * - the enforcement surface — the {@link rateLimit} Hono middleware and the
+ *   imperative {@link enforceRateLimit} helper that route packages
+ *   (storefront, bookings, …) call directly inside handlers.
+ *
+ * Keys always carry a client dimension: `lim:<bucket>:<clientKey>` where
+ * `clientKey` is derived by {@link clientIpKey} (`cf-connecting-ip`, then
+ * the first hop of `x-forwarded-for`, else `"anon"`). Window-keying is the
+ * store's responsibility — the KV backend appends `:<windowKey>` so its
+ * stored keys read `lim:<bucket>:<clientKey>:<windowKey>`; the CF binding
+ * tracks its own configured period per key; the memory store keeps a
+ * `resetAt` per key.
+ *
+ * `createApp` mounts default policies (tight on `/auth/*` POSTs, moderate
+ * on unauthenticated public writes) — see `config.rateLimit` in types.ts.
+ */
+/** Result of a single limit check against a {@link RateLimitStore}. */
+export interface RateLimitResult {
+    allowed: boolean;
+    /** Requests left in the current window, when the backend can tell. */
+    remaining?: number;
+    /** Seconds until the caller should retry, when the backend can tell. */
+    retryAfterSeconds?: number;
+}
+/**
+ * A counting backend for the limiter. `limit()` records one hit for `key`
+ * and reports whether the caller is still within `max` per `windowSeconds`.
+ */
+export interface RateLimitStore {
+    limit(key: string, opts: {
+        max: number;
+        windowSeconds: number;
+    }): Promise<RateLimitResult>;
+}
+/** A named limit applied to one logical traffic class. */
+export interface RateLimitPolicy {
+    /**
+     * Namespace for the counter — requests in different buckets never share
+     * a window (e.g. `"auth"`, `"public-write"`, `"booking-lookup"`).
+     */
+    bucket: string;
+    /** Maximum requests per window per client. */
+    max: number;
+    /** Window length in seconds. */
+    windowSeconds: number;
+    /**
+     * Explicit backend. When omitted, {@link enforceRateLimit} resolves one
+     * from the environment via {@link resolveRateLimitStore}.
+     */
+    store?: RateLimitStore;
+    /** Override the client dimension (defaults to {@link clientIpKey}). */
+    clientKey?: (c: RateLimitRequestContext) => string;
+}
+/**
+ * `createApp({ rateLimit })` configuration. Defaults (when the key is
+ * omitted entirely) are: `auth` = 10 POSTs/min/IP on `/auth/*`,
+ * `publicWrite` = 60 writes/min/IP on `/v1/public/*` + `publicPaths`.
+ * Set the whole config to `false` to disable, or set an individual
+ * policy to `false` to disable just that policy.
+ */
+export interface RateLimitConfig {
+    /**
+     * Explicit store, or a function-of-bindings for stores built from env
+     * bindings (Workers env is only available per request). When omitted —
+     * or when the function returns `undefined` — resolution falls through
+     * to `c.env.RATE_LIMITER` (CF binding) → `c.env.RATE_LIMIT` (KV) →
+     * in-memory.
+     */
+    store?: RateLimitStore | ((env: unknown) => RateLimitStore | undefined);
+    /** POSTs to `/auth/*`. Default `{ max: 10, windowSeconds: 60 }`. */
+    auth?: false | RateLimitRule;
+    /**
+     * Writes (POST/PUT/PATCH/DELETE) to `/v1/public/*` and to
+     * `config.publicPaths`. Default `{ max: 60, windowSeconds: 60 }`.
+     */
+    publicWrite?: false | RateLimitRule;
+}
+/** A bare max-per-window pair for the built-in `createApp` policies. */
+export interface RateLimitRule {
+    max: number;
+    windowSeconds: number;
+}
+/**
+ * The Cloudflare native Rate Limiting binding shape (wrangler
+ * `[[ratelimits]]`). The binding's `limit`/`period` are fixed in wrangler
+ * config — the policy's `max`/`windowSeconds` are advisory for headers
+ * only. One shared binding works across policies because the bucket is
+ * part of the key; deployments wanting different limits per policy bind
+ * one ratelimiter per policy and pass it via `policy.store`.
+ */
+export interface CloudflareRateLimiterBinding {
+    limit(opts: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+/**
+ * Minimal structural view of a Hono context — enough for key derivation,
+ * store resolution, and response headers — so route packages can call
+ * {@link enforceRateLimit} without generics gymnastics.
+ */
+export interface RateLimitRequestContext {
+    req: {
+        method: string;
+        url: string;
+        header(name: string): string | undefined;
+    };
+    env: unknown;
+    header(name: string, value: string): void;
+}
+/**
+ * Derive the client dimension for rate-limit keys: `cf-connecting-ip`
+ * (set by Cloudflare, not spoofable through the edge), else the first
+ * hop of `x-forwarded-for`, else `"anon"`. Exported so route packages
+ * key their own limiters and idempotency scopes consistently.
+ */
+export declare function clientIpKey(c: {
+    req: {
+        header(name: string): string | undefined;
+    };
+}): string;
+/**
+ * In-memory fixed-window store for Node, dev, and tests. Per-isolate —
+ * on Workers every isolate counts independently, so treat it as a last
+ * resort (still vastly better than nothing: an abusive client hammering
+ * one isolate is throttled by that isolate). Expired windows are pruned
+ * periodically on access; a hard `maxEntries` cap bounds memory.
+ */
+export declare function createMemoryRateLimitStore(options?: {
+    maxEntries?: number;
+}): RateLimitStore;
+/**
+ * KV-backed fixed-window store.
+ *
+ * **Best-effort by construction**: KV is eventually consistent and the
+ * counter is a non-atomic read-modify-write, so concurrent requests
+ * across PoPs undercount — a determined attacker gets somewhat more than
+ * `max` through before the window converges. With per-client keys this
+ * is still a real brake on brute force and write floods; deployments
+ * needing exact distributed limits should bind the Cloudflare Rate
+ * Limiting binding (`RATE_LIMITER`) instead.
+ *
+ * Stored keys are `lim:<bucket>:<clientKey>:<windowKey>` (the window
+ * suffix is appended here) with a TTL of `max(60, windowSeconds * 2)` —
+ * KV's TTL floor is 60s.
+ */
+export declare function createKvRateLimitStore(kv: KVStore): RateLimitStore;
+/**
+ * Adapter for the Cloudflare native Rate Limiting binding. Truly
+ * distributed and atomic; the actual limit/period are fixed in wrangler
+ * config, so the policy's `max`/`windowSeconds` only inform the
+ * `Retry-After` hint. `remaining` is never reported (the binding does
+ * not expose it).
+ */
+export declare function createCloudflareRateLimitStore(binding: CloudflareRateLimiterBinding): RateLimitStore;
+/** Test-only: re-arm the once-per-isolate missing-store warning. */
+export declare function resetRateLimitWarningsForTests(): void;
+/**
+ * Resolve the best available store from the environment:
+ * `c.env.RATE_LIMITER` (CF Rate Limiting binding) → `c.env.RATE_LIMIT`
+ * (KV) → in-memory fallback. **Fails open into the memory store** —
+ * rate limiting must never break Node/headless deployments that bind
+ * neither — but warns once per isolate outside dev/test so a
+ * production deploy without a distributed backend is visible in logs.
+ */
+export declare function resolveRateLimitStore(c: {
+    env: unknown;
+}, memoryFallback?: RateLimitStore): RateLimitStore;
+/**
+ * Imperative limit check for route handlers. Records one hit for the
+ * calling client against `policy` and returns `null` when allowed or a
+ * ready-to-return `429` Response (with `Retry-After` and the
+ * `X-RateLimit-*` headers the backend can populate) when over the limit.
+ *
+ * Fails open when the store itself errors — a broken KV namespace must
+ * not take the API down.
+ *
+ * @example
+ * const limited = await enforceRateLimit(c, {
+ *   bucket: "booking-lookup",
+ *   max: 20,
+ *   windowSeconds: 60,
+ * })
+ * if (limited) return limited
+ */
+export declare function enforceRateLimit(c: RateLimitRequestContext, policy: RateLimitPolicy): Promise<Response | null>;
+/**
+ * Hono middleware form of {@link enforceRateLimit}. Mount on a route or
+ * group:
+ *
+ *     app.post("/v1/public/leads", rateLimit({ bucket: "leads", max: 30, windowSeconds: 60 }), handler)
+ */
+export declare function rateLimit(policy: RateLimitPolicy): MiddlewareHandler;
+/**
+ * @deprecated Legacy constants from the pre-C2 limiter, retained for
+ * import compatibility. Configure limits per policy instead.
+ */
+export declare const LIVE_LIMITS: {
+    readonly burst: 30;
+    readonly rpm: 3000;
+};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/middleware/rate-limit.js

@@ -0,0 +1,240 @@
+/**
+ * Derive the client dimension for rate-limit keys: `cf-connecting-ip`
+ * (set by Cloudflare, not spoofable through the edge), else the first
+ * hop of `x-forwarded-for`, else `"anon"`. Exported so route packages
+ * key their own limiters and idempotency scopes consistently.
+ */
+export function clientIpKey(c) {
+    const cfIp = c.req.header("cf-connecting-ip")?.trim();
+    if (cfIp)
+        return cfIp;
+    const firstHop = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+    if (firstHop)
+        return firstHop;
+    return "anon";
+}
+// ---- Stores ----
+/**
+ * In-memory fixed-window store for Node, dev, and tests. Per-isolate —
+ * on Workers every isolate counts independently, so treat it as a last
+ * resort (still vastly better than nothing: an abusive client hammering
+ * one isolate is throttled by that isolate). Expired windows are pruned
+ * periodically on access; a hard `maxEntries` cap bounds memory.
+ */
+export function createMemoryRateLimitStore(options) {
+    const windows = new Map();
+    const maxEntries = options?.maxEntries ?? 10_000;
+    let lastPruneMs = 0;
+    function prune(nowMs) {
+        if (nowMs - lastPruneMs < 30_000 && windows.size <= maxEntries)
+            return;
+        lastPruneMs = nowMs;
+        for (const [key, win] of windows) {
+            if (win.resetAtMs <= nowMs)
+                windows.delete(key);
+        }
+        if (windows.size > maxEntries) {
+            // Still over after dropping expired windows — evict in insertion
+            // order (oldest windows first) to stay bounded.
+            const overflow = windows.size - maxEntries;
+            let dropped = 0;
+            for (const key of windows.keys()) {
+                windows.delete(key);
+                if (++dropped >= overflow)
+                    break;
+            }
+        }
+    }
+    return {
+        async limit(key, { max, windowSeconds }) {
+            const nowMs = Date.now();
+            prune(nowMs);
+            const existing = windows.get(key);
+            const win = existing && existing.resetAtMs > nowMs
+                ? existing
+                : { count: 0, resetAtMs: nowMs + windowSeconds * 1000 };
+            win.count += 1;
+            windows.set(key, win);
+            return {
+                allowed: win.count <= max,
+                remaining: Math.max(0, max - win.count),
+                retryAfterSeconds: Math.max(1, Math.ceil((win.resetAtMs - nowMs) / 1000)),
+            };
+        },
+    };
+}
+/**
+ * KV-backed fixed-window store.
+ *
+ * **Best-effort by construction**: KV is eventually consistent and the
+ * counter is a non-atomic read-modify-write, so concurrent requests
+ * across PoPs undercount — a determined attacker gets somewhat more than
+ * `max` through before the window converges. With per-client keys this
+ * is still a real brake on brute force and write floods; deployments
+ * needing exact distributed limits should bind the Cloudflare Rate
+ * Limiting binding (`RATE_LIMITER`) instead.
+ *
+ * Stored keys are `lim:<bucket>:<clientKey>:<windowKey>` (the window
+ * suffix is appended here) with a TTL of `max(60, windowSeconds * 2)` —
+ * KV's TTL floor is 60s.
+ */
+export function createKvRateLimitStore(kv) {
+    return {
+        async limit(key, { max, windowSeconds }) {
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            const windowKey = Math.floor(nowSeconds / windowSeconds);
+            const storageKey = `${key}:${windowKey}`;
+            const raw = await kv.get(storageKey);
+            const current = raw ? Number(raw) || 0 : 0;
+            const next = current + 1;
+            await kv.put(storageKey, String(next), {
+                expirationTtl: Math.max(60, windowSeconds * 2),
+            });
+            return {
+                allowed: next <= max,
+                remaining: Math.max(0, max - next),
+                retryAfterSeconds: Math.max(1, windowSeconds - (nowSeconds % windowSeconds)),
+            };
+        },
+    };
+}
+/**
+ * Adapter for the Cloudflare native Rate Limiting binding. Truly
+ * distributed and atomic; the actual limit/period are fixed in wrangler
+ * config, so the policy's `max`/`windowSeconds` only inform the
+ * `Retry-After` hint. `remaining` is never reported (the binding does
+ * not expose it).
+ */
+export function createCloudflareRateLimitStore(binding) {
+    return {
+        async limit(key, { windowSeconds }) {
+            const { success } = await binding.limit({ key });
+            return success
+                ? { allowed: true }
+                : { allowed: false, retryAfterSeconds: Math.max(1, windowSeconds) };
+        },
+    };
+}
+// ---- Store resolution ----
+const bindingStoreCache = new WeakMap();
+const kvStoreCache = new WeakMap();
+const sharedMemoryStore = createMemoryRateLimitStore();
+let warnedNoDistributedStore = false;
+function isDevLikeEnv() {
+    const proc = globalThis.process;
+    const nodeEnv = proc?.env?.NODE_ENV;
+    return nodeEnv === "test" || nodeEnv === "development";
+}
+/** Test-only: re-arm the once-per-isolate missing-store warning. */
+export function resetRateLimitWarningsForTests() {
+    warnedNoDistributedStore = false;
+}
+/**
+ * Resolve the best available store from the environment:
+ * `c.env.RATE_LIMITER` (CF Rate Limiting binding) → `c.env.RATE_LIMIT`
+ * (KV) → in-memory fallback. **Fails open into the memory store** —
+ * rate limiting must never break Node/headless deployments that bind
+ * neither — but warns once per isolate outside dev/test so a
+ * production deploy without a distributed backend is visible in logs.
+ */
+export function resolveRateLimitStore(c, memoryFallback = sharedMemoryStore) {
+    const env = (c.env ?? {});
+    const binding = env.RATE_LIMITER;
+    if (binding && typeof binding.limit === "function") {
+        let store = bindingStoreCache.get(binding);
+        if (!store) {
+            store = createCloudflareRateLimitStore(binding);
+            bindingStoreCache.set(binding, store);
+        }
+        return store;
+    }
+    const kv = env.RATE_LIMIT;
+    if (kv && typeof kv.get === "function" && typeof kv.put === "function") {
+        let store = kvStoreCache.get(kv);
+        if (!store) {
+            store = createKvRateLimitStore(kv);
+            kvStoreCache.set(kv, store);
+        }
+        return store;
+    }
+    if (!warnedNoDistributedStore && !isDevLikeEnv()) {
+        warnedNoDistributedStore = true;
+        console.warn("[voyant] rate-limit: no distributed store available (bind a Cloudflare " +
+            "ratelimiter as RATE_LIMITER or a KV namespace as RATE_LIMIT). " +
+            "Falling back to a per-isolate in-memory limiter — limits apply " +
+            "per instance, not fleet-wide.");
+    }
+    return memoryFallback;
+}
+// ---- Enforcement ----
+/**
+ * Imperative limit check for route handlers. Records one hit for the
+ * calling client against `policy` and returns `null` when allowed or a
+ * ready-to-return `429` Response (with `Retry-After` and the
+ * `X-RateLimit-*` headers the backend can populate) when over the limit.
+ *
+ * Fails open when the store itself errors — a broken KV namespace must
+ * not take the API down.
+ *
+ * @example
+ * const limited = await enforceRateLimit(c, {
+ *   bucket: "booking-lookup",
+ *   max: 20,
+ *   windowSeconds: 60,
+ * })
+ * if (limited) return limited
+ */
+export async function enforceRateLimit(c, policy) {
+    const store = policy.store ?? resolveRateLimitStore(c);
+    const clientKey = (policy.clientKey ?? clientIpKey)(c);
+    const key = `lim:${policy.bucket}:${clientKey}`;
+    let result;
+    try {
+        result = await store.limit(key, { max: policy.max, windowSeconds: policy.windowSeconds });
+    }
+    catch {
+        // Fail open: the limiter is a brake, not a load-bearing dependency.
+        return null;
+    }
+    c.header("X-RateLimit-Limit", String(policy.max));
+    if (result.remaining !== undefined) {
+        c.header("X-RateLimit-Remaining", String(result.remaining));
+    }
+    if (result.allowed)
+        return null;
+    const retryAfterSeconds = result.retryAfterSeconds ?? policy.windowSeconds;
+    return new Response(JSON.stringify({ error: "Too Many Requests", code: "rate_limited" }), {
+        status: 429,
+        headers: {
+            "content-type": "application/json",
+            "x-content-type-options": "nosniff",
+            "retry-after": String(retryAfterSeconds),
+            "x-ratelimit-limit": String(policy.max),
+            "x-ratelimit-remaining": "0",
+        },
+    });
+}
+/**
+ * Hono middleware form of {@link enforceRateLimit}. Mount on a route or
+ * group:
+ *
+ *     app.post("/v1/public/leads", rateLimit({ bucket: "leads", max: 30, windowSeconds: 60 }), handler)
+ */
+export function rateLimit(policy) {
+    return async (c, next) => {
+        if (c.req.method === "OPTIONS")
+            return next();
+        const limited = await enforceRateLimit(c, policy);
+        if (limited)
+            return limited;
+        return next();
+    };
+}
+/**
+ * @deprecated Legacy constants from the pre-C2 limiter, retained for
+ * import compatibility. Configure limits per policy instead.
+ */
+export const LIVE_LIMITS = {
+    burst: 30,
+    rpm: 3000,
+};