@daloyjs/core 0.35.2 → 0.37.0

package/dist/asyncapi.js

@@ -0,0 +1,212 @@
+/**
+ * AsyncAPI 3.0 document generator for WebSocket surfaces.
+ *
+ * Built-in, dependency-free, and a deliberate mirror of the OpenAPI 3.1
+ * generator in `./openapi.ts`: it turns every `app.ws()` route into an
+ * AsyncAPI **channel** (the socket address + path parameters) and one or more
+ * **operations** (`receive` for client→server messages, `send` for
+ * server→client messages). The RFC 6455 stack and its CSWSH defenses finally
+ * get a contract/doc artifact, extending the contract-first story past HTTP.
+ *
+ * If a message schema exposes a `toJSONSchema()` method (Zod 4, Valibot, ...)
+ * we use it; otherwise we emit a permissive `{}` placeholder rather than fail
+ * — docs and tooling still work, just with looser types for that payload.
+ */
+import { openapiToYAML } from "./openapi.js";
+/**
+ * Convert a Standard Schema to JSON Schema for an AsyncAPI message payload.
+ *
+ * Mirrors the OpenAPI generator's permissive strategy: use `toJSONSchema()`
+ * when the schema exposes it (Zod 4, Valibot, ...), and otherwise fall back to
+ * a permissive `{}` so generation never throws on an unconvertible schema.
+ *
+ * @param schema - The Standard Schema to convert, or `undefined`.
+ * @returns A JSON-Schema-shaped object, or `undefined` when no schema given.
+ */
+function toPayloadSchema(schema) {
+    if (!schema)
+        return undefined;
+    const anySchema = schema;
+    if (typeof anySchema.toJSONSchema === "function") {
+        try {
+            return anySchema.toJSONSchema();
+        }
+        catch {
+            /* fall through to permissive placeholder */
+        }
+    }
+    return {};
+}
+/**
+ * Derive a stable, unique channel/operation key from a WebSocket path.
+ *
+ * Strips the leading slash, drops `:param` / `{param}` markers, and camelCases
+ * the remaining segments (`/chat/:room/feed` → `chatRoomFeed`). Falls back to
+ * `root` for `/`. Collisions are de-duplicated by the caller.
+ *
+ * @param path - The registered WebSocket route path.
+ * @returns A safe identifier base for AsyncAPI keys.
+ */
+function pathToKey(path) {
+    const segments = path
+        .split("/")
+        .map((s) => s.replace(/[:{}]/g, ""))
+        .filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return "root";
+    return segments
+        .map((seg, i) => {
+        const clean = seg.replace(/[^A-Za-z0-9]+/g, " ").trim();
+        const parts = clean.split(/\s+/).filter(Boolean);
+        return parts
+            .map((part, j) => i === 0 && j === 0
+            ? part.charAt(0).toLowerCase() + part.slice(1)
+            : part.charAt(0).toUpperCase() + part.slice(1))
+            .join("");
+    })
+        .join("");
+}
+/**
+ * Extract `:param` names from a WebSocket route path in declaration order.
+ *
+ * @param path - The registered WebSocket route path.
+ * @returns The list of path-parameter names (without the leading colon).
+ */
+function extractParams(path) {
+    const names = [];
+    for (const match of path.matchAll(/:([A-Za-z0-9_]+)/g)) {
+        names.push(match[1]);
+    }
+    return names;
+}
+/**
+ * Generate an AsyncAPI 3.0 document from a registered {@link App}'s WebSocket
+ * routes.
+ *
+ * Every `app.ws()` route becomes one channel (its address + path parameters)
+ * and one or more operations:
+ *
+ * - a `receive` operation for client→server messages — payload taken from the
+ *   route's `meta.receive` schema, falling back to the handler's
+ *   `request.body` schema (the same schema used for payload-size checks).
+ * - a `send` operation for server→client messages — emitted only when the
+ *   route declares a `meta.send` schema.
+ *
+ * The output is a plain JSON-serializable object: hand it to AsyncAPI Studio,
+ * write it to disk for codegen, or serve it from a route. When the app has no
+ * WebSocket routes the document still validates, with empty `channels` and
+ * `operations` maps.
+ *
+ * @example
+ * ```ts
+ * import { generateAsyncAPI } from "@daloyjs/core/asyncapi";
+ * import { writeFileSync } from "node:fs";
+ *
+ * const doc = generateAsyncAPI(app, {
+ *   info: { title: "Realtime API", version: "1.0.0" },
+ *   servers: { production: { host: "api.example.com", protocol: "wss" } },
+ * });
+ * writeFileSync("./generated/asyncapi.json", JSON.stringify(doc, null, 2));
+ * ```
+ *
+ * @param app - The application whose WebSocket routes are documented.
+ * @param options - Document metadata and optional named servers.
+ * @returns A JSON-serializable AsyncAPI 3.0 document.
+ * @since 0.37.0
+ */
+export function generateAsyncAPI(app, options) {
+    const channels = {};
+    const operations = {};
+    const messages = {};
+    const usedKeys = new Set();
+    const entries = app.webSocketRoutes.list();
+    for (const entry of entries) {
+        const path = entry.path;
+        const meta = entry.handler.meta;
+        // Derive a unique channel key (operationId override > path-derived slug).
+        let key = meta?.operationId ?? pathToKey(path);
+        if (usedKeys.has(key)) {
+            let suffix = 2;
+            while (usedKeys.has(`${key}${suffix}`))
+                suffix += 1;
+            key = `${key}${suffix}`;
+        }
+        usedKeys.add(key);
+        const address = path.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+        const paramNames = extractParams(path);
+        const channelMessages = {};
+        // Inbound: a WebSocket route can always receive client messages, so a
+        // `receive` operation is always emitted (permissive payload when no schema).
+        const receiveSchema = meta?.receive ?? entry.handler.request?.body;
+        const receiveMsgKey = `${key}Receive`;
+        messages[receiveMsgKey] = {
+            name: receiveMsgKey,
+            title: `${key} inbound message`,
+            payload: toPayloadSchema(receiveSchema) ?? {},
+        };
+        channelMessages.receiveMessage = {
+            $ref: `#/components/messages/${receiveMsgKey}`,
+        };
+        operations[receiveMsgKey] = {
+            action: "receive",
+            channel: { $ref: `#/channels/${key}` },
+            ...(meta?.summary ? { summary: meta.summary } : {}),
+            ...(meta?.description ? { description: meta.description } : {}),
+            ...(meta?.tags ? { tags: meta.tags.map((t) => ({ name: t })) } : {}),
+            messages: [{ $ref: `#/channels/${key}/messages/receiveMessage` }],
+        };
+        // Outbound: only emitted when the route declares an outbound schema.
+        const sendSchema = meta?.send;
+        if (sendSchema) {
+            const sendMsgKey = `${key}Send`;
+            messages[sendMsgKey] = {
+                name: sendMsgKey,
+                title: `${key} outbound message`,
+                payload: toPayloadSchema(sendSchema) ?? {},
+            };
+            channelMessages.sendMessage = {
+                $ref: `#/components/messages/${sendMsgKey}`,
+            };
+            operations[sendMsgKey] = {
+                action: "send",
+                channel: { $ref: `#/channels/${key}` },
+                ...(meta?.summary ? { summary: meta.summary } : {}),
+                ...(meta?.tags ? { tags: meta.tags.map((t) => ({ name: t })) } : {}),
+                messages: [{ $ref: `#/channels/${key}/messages/sendMessage` }],
+            };
+        }
+        const parameters = {};
+        for (const name of paramNames) {
+            parameters[name] = { description: `Path parameter \`${name}\`.` };
+        }
+        channels[key] = {
+            address,
+            ...(meta?.summary ? { summary: meta.summary } : {}),
+            ...(meta?.description ? { description: meta.description } : {}),
+            ...(paramNames.length ? { parameters } : {}),
+            messages: channelMessages,
+        };
+    }
+    return {
+        asyncapi: "3.0.0",
+        info: options.info,
+        ...(options.servers ? { servers: options.servers } : {}),
+        channels,
+        operations,
+        components: { messages },
+    };
+}
+/**
+ * Serialize an AsyncAPI document to YAML.
+ *
+ * Thin alias over the dependency-free YAML 1.2 emitter shared with the
+ * OpenAPI generator ({@link openapiToYAML}) — AsyncAPI and OpenAPI documents
+ * are both plain JSON-compatible objects, so the same emitter applies.
+ *
+ * @param doc - The AsyncAPI document produced by {@link generateAsyncAPI}.
+ * @returns The document rendered as a YAML string.
+ * @since 0.37.0
+ */
+export function asyncapiToYAML(doc) {
+    return openapiToYAML(doc);
+}

package/dist/auto-ban.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Adaptive auto-ban (fail2ban-style) middleware. Where {@link "./middleware.js".loginThrottle}
+ * only protects credential-entry routes, {@link autoBan} generalizes the idea
+ * into a reusable, escalating, decaying ban primitive: when a single client
+ * trips too many "suspicious" responses (by default `401` / `403` / `429`) inside
+ * a rolling window, it is temporarily banned. Repeat offenders earn
+ * exponentially longer bans, and the record decays away once the client goes
+ * quiet — so a one-off burst is forgiven while a persistent attacker is shut out
+ * for progressively longer.
+ *
+ * The middleware is dependency-free and runtime-portable. It observes outgoing
+ * responses via the {@link "./types.js".Hooks.onSend} hook (so it counts the
+ * status produced by *any* later middleware or handler, not just its own) and
+ * enforces the ban in {@link "./types.js".Hooks.beforeHandle}. The ban state
+ * lives in a pluggable {@link AutoBanStore} — the in-memory default mirrors the
+ * `rateLimit()` store and is single-process only; supply a shared (e.g. Redis)
+ * implementation for multi-instance deployments.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * One client's auto-ban bookkeeping. A record tracks the current strike count
+ * inside the rolling strike window, when that window expires, the timestamp the
+ * client is banned until (`0` when not banned), and how many bans the client
+ * has accumulated while the record has stayed alive (drives escalation).
+ *
+ * @since 0.37.0
+ */
+export interface AutoBanRecord {
+    /** Suspicious responses seen inside the current strike window. */
+    strikes: number;
+    /** Epoch ms at which the current strike window resets (strikes decay to 0). */
+    strikeExpiresMs: number;
+    /** Epoch ms the client is banned until; `0` when the client is not banned. */
+    bannedUntilMs: number;
+    /** Total bans issued while this record stayed alive; drives escalation. */
+    banCount: number;
+}
+/**
+ * Pluggable backend for {@link autoBan}, mirroring the `rateLimit()` store
+ * contract. Implementations persist one {@link AutoBanRecord} per key and must
+ * treat an entry whose `ttlMs` has elapsed as absent (so bans and escalation
+ * decay automatically). The built-in default is in-memory and single-process;
+ * back it with Redis (or another shared store) for multi-instance deployments.
+ *
+ * @since 0.37.0
+ */
+export interface AutoBanStore {
+    /** Resolve the current record for `key`, or `undefined` when none/expired. */
+    get(key: string): Promise<AutoBanRecord | undefined>;
+    /**
+     * Persist `record` for `key`, expiring it after `ttlMs`. Implementations
+     * should set the backing TTL so an idle key is reclaimed automatically.
+     */
+    set(key: string, record: AutoBanRecord, ttlMs: number): Promise<void>;
+    /** Forget `key` entirely (e.g. an operator manually lifting a ban). */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Emitted via {@link AutoBanOptions.onBan} when a client crosses the strike
+ * threshold and a (possibly escalated) ban is issued. Useful for alerting,
+ * structured audit logging, or feeding an external denylist.
+ *
+ * @since 0.37.0
+ */
+export interface AutoBanEvent {
+    /** The store key the ban applies to (group prefix + client identity). */
+    key: string;
+    /** How many times this client has been banned while its record stayed alive. */
+    banCount: number;
+    /** The duration of this ban in milliseconds. */
+    banDurationMs: number;
+    /** Epoch ms the client is banned until. */
+    bannedUntilMs: number;
+}
+/**
+ * Emitted via {@link AutoBanOptions.onStrike} every time a suspicious response
+ * is attributed to a client (before any resulting ban). Lets callers observe
+ * pressure building without waiting for the ban itself.
+ *
+ * @since 0.37.0
+ */
+export interface AutoBanStrikeEvent {
+    /** The store key the strike applies to. */
+    key: string;
+    /** The strike count after recording this strike, inside the current window. */
+    strikes: number;
+    /** The response status that triggered the strike. */
+    status: number;
+}
+/**
+ * Configuration for {@link autoBan}. Every field is optional except that the
+ * middleware must be able to identify clients: supply a {@link keyGenerator} or
+ * set {@link trustProxyHeaders} (otherwise construction throws, to avoid
+ * accidentally banning every client through a shared `"global"` bucket).
+ *
+ * @since 0.37.0
+ */
+export interface AutoBanOptions {
+    /** Rolling strike window in ms; strikes older than this decay. Default: 10 minutes. */
+    windowMs?: number;
+    /** Suspicious responses inside `windowMs` that trigger a ban. Default: 5. */
+    maxStrikes?: number;
+    /** Base ban duration in ms (first offence). Default: 15 minutes. */
+    banMs?: number;
+    /** Hard cap on an escalated ban duration in ms. Default: 24 hours. */
+    maxBanMs?: number;
+    /**
+     * Double the ban duration on each repeat ban while the record stays alive
+     * (`banMs`, `2×banMs`, `4×banMs`, … capped at `maxBanMs`). Default: `true`.
+     * When `false`, every ban lasts exactly `banMs`.
+     */
+    escalate?: boolean;
+    /**
+     * Response status codes treated as suspicious. Default: `[401, 403, 429]`.
+     * Add `400` / `422` to also count request-validation failures, but be aware
+     * those can include honest client mistakes.
+     */
+    watchStatuses?: readonly number[];
+    /**
+     * Status used for the ban rejection: `429` (default, carries `Retry-After`)
+     * or `403`. `403` surfaces {@link AutoBanOptions.message}.
+     */
+    banStatus?: 403 | 429;
+    /**
+     * Derive the client identity from `ctx`, or `undefined` to skip the request
+     * (fail-open — never banned, never counted). Defaults to the proxy-header
+     * resolver when {@link trustProxyHeaders} is set.
+     */
+    keyGenerator?: (ctx: BaseContext<any, any>) => string | undefined;
+    /**
+     * Read `X-Forwarded-For` / `X-Real-IP` in the default key generator. Off by
+     * default because those headers are client-spoofable unless every request
+     * reaches the app through a proxy chain you control.
+     */
+    trustProxyHeaders?: boolean;
+    /** Pluggable ban store. Default: a shared in-memory store keyed by `groupId`. */
+    store?: AutoBanStore;
+    /**
+     * Share one ban store across every `autoBan()` mounted with the same
+     * `groupId`, so a client banned on one route group is banned on all of them.
+     * Default: `"auto-ban"`. Only meaningful for the in-memory default store.
+     */
+    groupId?: string;
+    /** Send `Retry-After` on a `429` ban rejection. Default: `true`. */
+    retryAfter?: boolean;
+    /** Message for the `403` ban variant. Default: `"Temporarily banned"`. */
+    message?: string;
+    /** Called when a ban is issued (alerting / audit / external denylist). */
+    onBan?: (event: AutoBanEvent) => void;
+    /** Called for every recorded strike, before any resulting ban. */
+    onStrike?: (event: AutoBanStrikeEvent) => void;
+}
+/**
+ * Test-only helper that clears the process-wide shared auto-ban stores. Not part
+ * of the documented public API.
+ *
+ * @internal
+ */
+export declare function _resetAutoBanStoresForTests(): void;
+/**
+ * Default in-memory {@link AutoBanStore}. Single-process only; entries are
+ * reclaimed lazily on access and opportunistically when the map grows large, so
+ * an idle attacker's record decays without an explicit timer.
+ *
+ * @since 0.37.0
+ */
+export declare class MemoryAutoBanStore implements AutoBanStore {
+    private map;
+    /** {@inheritDoc AutoBanStore.get} */
+    get(key: string): Promise<AutoBanRecord | undefined>;
+    /** {@inheritDoc AutoBanStore.set} */
+    set(key: string, record: AutoBanRecord, ttlMs: number): Promise<void>;
+    /** {@inheritDoc AutoBanStore.delete} */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Adaptive, escalating, decaying auto-ban middleware (fail2ban-style). Counts
+ * suspicious outgoing responses per client and temporarily bans repeat
+ * offenders; bans grow exponentially for persistent abuse and decay once the
+ * client goes quiet.
+ *
+ * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
+ * set {@link AutoBanOptions.trustProxyHeaders}, otherwise construction throws so
+ * a misconfiguration can never collapse every caller into one shared bucket and
+ * ban the whole world at once. A request the key generator cannot attribute is
+ * skipped (never counted, never banned).
+ *
+ * @example
+ * ```ts
+ * import { autoBan } from "@daloyjs/core";
+ *
+ * // Five 401/403/429s within 10 min → 15 min ban, doubling for repeat offenders.
+ * app.use(autoBan({ trustProxyHeaders: true }));
+ * ```
+ *
+ * @param opts - Auto-ban configuration.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @throws Error when neither `keyGenerator` nor `trustProxyHeaders` is provided,
+ *   or when a numeric option is out of range.
+ * @since 0.37.0
+ */
+export declare function autoBan(opts?: AutoBanOptions): Hooks;

package/dist/auto-ban.js

@@ -0,0 +1,222 @@
+/**
+ * Adaptive auto-ban (fail2ban-style) middleware. Where {@link "./middleware.js".loginThrottle}
+ * only protects credential-entry routes, {@link autoBan} generalizes the idea
+ * into a reusable, escalating, decaying ban primitive: when a single client
+ * trips too many "suspicious" responses (by default `401` / `403` / `429`) inside
+ * a rolling window, it is temporarily banned. Repeat offenders earn
+ * exponentially longer bans, and the record decays away once the client goes
+ * quiet — so a one-off burst is forgiven while a persistent attacker is shut out
+ * for progressively longer.
+ *
+ * The middleware is dependency-free and runtime-portable. It observes outgoing
+ * responses via the {@link "./types.js".Hooks.onSend} hook (so it counts the
+ * status produced by *any* later middleware or handler, not just its own) and
+ * enforces the ban in {@link "./types.js".Hooks.beforeHandle}. The ban state
+ * lives in a pluggable {@link AutoBanStore} — the in-memory default mirrors the
+ * `rateLimit()` store and is single-process only; supply a shared (e.g. Redis)
+ * implementation for multi-instance deployments.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { ForbiddenError, TooManyRequestsError } from "./errors.js";
+const DEFAULT_WINDOW_MS = 10 * 60_000;
+const DEFAULT_MAX_STRIKES = 5;
+const DEFAULT_BAN_MS = 15 * 60_000;
+const DEFAULT_MAX_BAN_MS = 24 * 60 * 60_000;
+const DEFAULT_WATCH_STATUSES = [401, 403, 429];
+const DEFAULT_GROUP_ID = "auto-ban";
+const STATE_KEY = "__autoBanKey";
+const STATE_REJECTED = "__autoBanRejected";
+/**
+ * Process-wide registry of shared in-memory stores keyed by `groupId`, so two
+ * `autoBan({ groupId })` mounts cooperate on one ban map.
+ *
+ * @internal
+ */
+const SHARED_AUTO_BAN_STORES = new Map();
+/**
+ * Test-only helper that clears the process-wide shared auto-ban stores. Not part
+ * of the documented public API.
+ *
+ * @internal
+ */
+export function _resetAutoBanStoresForTests() {
+    SHARED_AUTO_BAN_STORES.clear();
+}
+/**
+ * Default in-memory {@link AutoBanStore}. Single-process only; entries are
+ * reclaimed lazily on access and opportunistically when the map grows large, so
+ * an idle attacker's record decays without an explicit timer.
+ *
+ * @since 0.37.0
+ */
+export class MemoryAutoBanStore {
+    map = new Map();
+    /** {@inheritDoc AutoBanStore.get} */
+    async get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresMs <= Date.now()) {
+            this.map.delete(key);
+            return undefined;
+        }
+        return entry.record;
+    }
+    /** {@inheritDoc AutoBanStore.set} */
+    async set(key, record, ttlMs) {
+        const now = Date.now();
+        this.map.set(key, { record, expiresMs: now + ttlMs });
+        if (this.map.size > 10_000) {
+            for (const [k, v] of this.map)
+                if (v.expiresMs <= now)
+                    this.map.delete(k);
+        }
+    }
+    /** {@inheritDoc AutoBanStore.delete} */
+    async delete(key) {
+        this.map.delete(key);
+    }
+}
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`autoBan(): ${name} must be a positive integer.`);
+    }
+}
+function forwardedKey(ctx) {
+    const forwarded = ctx.request.headers.get("x-forwarded-for");
+    const first = forwarded ? forwarded.split(",")[0].trim() : "";
+    if (first)
+        return first;
+    return ctx.request.headers.get("x-real-ip") ?? undefined;
+}
+/**
+ * Adaptive, escalating, decaying auto-ban middleware (fail2ban-style). Counts
+ * suspicious outgoing responses per client and temporarily bans repeat
+ * offenders; bans grow exponentially for persistent abuse and decay once the
+ * client goes quiet.
+ *
+ * Identity attribution is mandatory: pass {@link AutoBanOptions.keyGenerator} or
+ * set {@link AutoBanOptions.trustProxyHeaders}, otherwise construction throws so
+ * a misconfiguration can never collapse every caller into one shared bucket and
+ * ban the whole world at once. A request the key generator cannot attribute is
+ * skipped (never counted, never banned).
+ *
+ * @example
+ * ```ts
+ * import { autoBan } from "@daloyjs/core";
+ *
+ * // Five 401/403/429s within 10 min → 15 min ban, doubling for repeat offenders.
+ * app.use(autoBan({ trustProxyHeaders: true }));
+ * ```
+ *
+ * @param opts - Auto-ban configuration.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @throws Error when neither `keyGenerator` nor `trustProxyHeaders` is provided,
+ *   or when a numeric option is out of range.
+ * @since 0.37.0
+ */
+export function autoBan(opts = {}) {
+    const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
+    const maxStrikes = opts.maxStrikes ?? DEFAULT_MAX_STRIKES;
+    const banMs = opts.banMs ?? DEFAULT_BAN_MS;
+    const maxBanMs = opts.maxBanMs ?? DEFAULT_MAX_BAN_MS;
+    assertPositiveInteger("windowMs", windowMs);
+    assertPositiveInteger("maxStrikes", maxStrikes);
+    assertPositiveInteger("banMs", banMs);
+    assertPositiveInteger("maxBanMs", maxBanMs);
+    if (maxBanMs < banMs) {
+        throw new Error("autoBan(): maxBanMs must be >= banMs.");
+    }
+    const escalate = opts.escalate ?? true;
+    const banStatus = opts.banStatus ?? 429;
+    if (banStatus !== 403 && banStatus !== 429) {
+        throw new Error("autoBan(): banStatus must be 403 or 429.");
+    }
+    const retryAfter = opts.retryAfter !== false;
+    const message = opts.message ?? "Temporarily banned";
+    const watchStatuses = opts.watchStatuses ?? DEFAULT_WATCH_STATUSES;
+    if (watchStatuses.length === 0) {
+        throw new Error("autoBan(): watchStatuses must list at least one status code.");
+    }
+    for (const status of watchStatuses) {
+        if (!Number.isInteger(status) || status < 100 || status > 599) {
+            throw new Error("autoBan(): watchStatuses must be integer HTTP status codes (100-599).");
+        }
+    }
+    const watch = new Set(watchStatuses);
+    if (!opts.keyGenerator && !opts.trustProxyHeaders) {
+        throw new Error("autoBan(): provide keyGenerator or set trustProxyHeaders so clients can be identified; " +
+            "otherwise every caller shares one bucket and a single offender would ban everyone.");
+    }
+    const keyOf = opts.keyGenerator ?? forwardedKey;
+    const groupId = opts.groupId ?? DEFAULT_GROUP_ID;
+    let store;
+    if (opts.store) {
+        store = opts.store;
+    }
+    else {
+        let shared = SHARED_AUTO_BAN_STORES.get(groupId);
+        if (!shared) {
+            shared = new MemoryAutoBanStore();
+            SHARED_AUTO_BAN_STORES.set(groupId, shared);
+        }
+        store = shared;
+    }
+    const prefix = `${groupId}:`;
+    return {
+        async beforeHandle(ctx) {
+            const identity = keyOf(ctx);
+            if (identity === undefined)
+                return undefined;
+            const key = `${prefix}${identity}`;
+            const state = ctx.state;
+            state[STATE_KEY] = key;
+            const record = await store.get(key);
+            const now = Date.now();
+            if (record && record.bannedUntilMs > now) {
+                state[STATE_REJECTED] = true;
+                if (banStatus === 403)
+                    throw new ForbiddenError(message);
+                const retry = Math.ceil((record.bannedUntilMs - now) / 1000);
+                throw new TooManyRequestsError(retryAfter ? retry : undefined);
+            }
+            return undefined;
+        },
+        async onSend(res, ctx) {
+            if (!ctx)
+                return undefined;
+            const state = ctx.state;
+            // Never count the ban rejection we just produced — that would let an
+            // active ban perpetually re-arm itself.
+            if (state[STATE_REJECTED] === true)
+                return undefined;
+            const key = state[STATE_KEY];
+            if (key === undefined)
+                return undefined;
+            if (!watch.has(res.status))
+                return undefined;
+            const now = Date.now();
+            const record = await store.get(key);
+            const windowActive = record !== undefined && record.strikeExpiresMs > now;
+            let strikes = (windowActive ? record.strikes : 0) + 1;
+            let banCount = record?.banCount ?? 0;
+            let bannedUntilMs = record?.bannedUntilMs ?? 0;
+            const strikeExpiresMs = now + windowMs;
+            opts.onStrike?.({ key, strikes, status: res.status });
+            if (strikes >= maxStrikes) {
+                banCount += 1;
+                const duration = escalate
+                    ? Math.min(maxBanMs, banMs * 2 ** (banCount - 1))
+                    : banMs;
+                bannedUntilMs = now + duration;
+                strikes = 0;
+                opts.onBan?.({ key, banCount, banDurationMs: duration, bannedUntilMs });
+            }
+            const ttlMs = Math.max(strikeExpiresMs, bannedUntilMs) - now;
+            await store.set(key, { strikes, strikeExpiresMs, bannedUntilMs, banCount }, ttlMs);
+            return undefined;
+        },
+    };
+}