@daloyjs/core 0.36.0 → 0.37.0

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;
+        },
+    };
+}

package/dist/bot-guard.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Bot / User-Agent management middleware. Mirrors the bot-rule layer that
+ * Nginx, Cloudflare, and other WAFs run at the edge, but inside the app where
+ * the framework already owns request parsing and client-IP resolution.
+ *
+ * {@link botGuard} does three opt-in jobs:
+ *
+ * 1. **Block empty / missing `User-Agent`** — a common signature of crude
+ *    scrapers and vulnerability scanners (on by default).
+ * 2. **Block known-abusive `User-Agent` strings** — caller-supplied substrings
+ *    or `RegExp`s.
+ * 3. **Verify declared crawlers** — when a request *claims* to be Googlebot or
+ *    Bingbot, confirm it via reverse-DNS + forward-confirm (the method Google
+ *    and Bing themselves document) so a spoofed `User-Agent` can't impersonate a
+ *    trusted crawler. Verification results are cached per IP to keep DNS off the
+ *    hot path.
+ *
+ * The middleware is dependency-free and runtime-portable. The default DNS
+ * resolver is lazily imported from `node:dns/promises`; supply a custom
+ * {@link BotResolver} on non-Node runtimes or in tests.
+ *
+ * @example
+ * ```ts
+ * import { botGuard, WELL_KNOWN_BOTS } from "@daloyjs/core";
+ *
+ * app.use(
+ *   botGuard({
+ *     trustProxyHeaders: true,
+ *     blockedUserAgents: [/sqlmap/i, /nikto/i, "masscan"],
+ *     verifiedBots: WELL_KNOWN_BOTS, // spoofed Googlebot/Bingbot → 403
+ *   }),
+ * );
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Pluggable DNS resolver used to verify declared crawlers. The default
+ * implementation lazily imports `node:dns/promises`; provide your own on
+ * runtimes without it (Workers, Deno without `--allow-net`) or in tests.
+ *
+ * @since 0.37.0
+ */
+export interface BotResolver {
+    /**
+     * Reverse-resolve an IP address to its PTR hostname(s).
+     *
+     * @param ip - The client IP address.
+     * @returns The PTR hostnames (may be empty).
+     */
+    reverse(ip: string): Promise<readonly string[]>;
+    /**
+     * Forward-resolve a hostname to its IP address(es).
+     *
+     * @param hostname - The hostname returned by {@link BotResolver.reverse}.
+     * @returns The resolved IP addresses (may be empty).
+     */
+    forward(hostname: string): Promise<readonly string[]>;
+}
+/**
+ * A declared-crawler verification rule. When the request `User-Agent` matches
+ * {@link VerifiedBotRule.userAgent}, the client's reverse-DNS hostname must end
+ * with one of {@link VerifiedBotRule.domains} and forward-resolve back to the
+ * same IP — otherwise the request is treated as a spoofed crawler.
+ *
+ * @since 0.37.0
+ */
+export interface VerifiedBotRule {
+    /** Human-readable bot name, surfaced in {@link BotGuardEvent.botName}. */
+    name: string;
+    /** Pattern that identifies a request claiming to be this crawler. */
+    userAgent: RegExp;
+    /**
+     * Allowed reverse-DNS domain suffixes (e.g. `.googlebot.com`). A leading dot
+     * is recommended so `evilgooglebot.com` cannot match `googlebot.com`.
+     */
+    domains: readonly string[];
+}
+/**
+ * Why a request was flagged by {@link botGuard}. Passed to
+ * {@link BotGuardOptions.onBlock} and used to build the rejection.
+ *
+ * @since 0.37.0
+ */
+export interface BotGuardEvent {
+    /** The specific rule that fired. */
+    reason: "empty-user-agent" | "blocked-user-agent" | "spoofed-bot" | "unverifiable-bot";
+    /** The request `User-Agent` (empty string when missing). */
+    userAgent: string;
+    /** The resolved client IP, when available. */
+    ip?: string;
+    /** The declared bot name, for `spoofed-bot` / `unverifiable-bot`. */
+    botName?: string;
+}
+/**
+ * Configuration for {@link botGuard}.
+ *
+ * @since 0.37.0
+ */
+export interface BotGuardOptions {
+    /**
+     * Block requests whose `User-Agent` is missing or empty. Default `true`.
+     */
+    blockEmptyUserAgent?: boolean;
+    /**
+     * Known-abusive `User-Agent` patterns. A plain string matches
+     * case-insensitively as a substring; a `RegExp` is tested as-is.
+     */
+    blockedUserAgents?: readonly (string | RegExp)[];
+    /**
+     * Allowlist that bypasses **all** checks (including empty-UA and verified-bot
+     * verification). A plain string matches case-insensitively as a substring; a
+     * `RegExp` is tested as-is. Checked first.
+     */
+    allowUserAgents?: readonly (string | RegExp)[];
+    /**
+     * Declared-crawler verification rules. When provided, an IP source is
+     * required (`resolveIp` or `trustProxyHeaders`), otherwise construction
+     * throws.
+     */
+    verifiedBots?: readonly VerifiedBotRule[];
+    /**
+     * Block a declared crawler that cannot be verified (no client IP, or a DNS
+     * lookup failure). Default `true` — the secure-by-default posture, since an
+     * unverifiable "Googlebot" might be an impersonator. Set `false` to fail open
+     * and let unverifiable crawlers through.
+     */
+    blockUnverifiableBots?: boolean;
+    /**
+     * Trust `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Only
+     * enable behind a trusted proxy that overwrites these headers.
+     */
+    trustProxyHeaders?: boolean;
+    /**
+     * Custom client-IP resolver. Overrides {@link BotGuardOptions.trustProxyHeaders}.
+     */
+    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    /**
+     * Custom DNS resolver for crawler verification. Defaults to a lazy
+     * `node:dns/promises`-backed resolver.
+     */
+    resolver?: BotResolver;
+    /**
+     * `"block"` (default) throws a {@link ForbiddenError}; `"log"` only invokes
+     * {@link BotGuardOptions.onBlock} and lets the request continue (monitor mode).
+     */
+    mode?: "block" | "log";
+    /** Detail string for the `403` problem+json. Default `"Bot access denied"`. */
+    message?: string;
+    /**
+     * TTL for cached crawler-verification results, in ms. Default 1 hour.
+     */
+    cacheTtlMs?: number;
+    /** Max cached IPs before opportunistic pruning. Default `10_000`. */
+    cacheMaxEntries?: number;
+    /** Called whenever a request is flagged (in both `block` and `log` modes). */
+    onBlock?: (event: BotGuardEvent) => void;
+}
+/**
+ * Built-in {@link VerifiedBotRule} for Googlebot (and other Google crawlers),
+ * verified against Google's documented `*.googlebot.com` / `*.google.com`
+ * reverse-DNS domains.
+ *
+ * @since 0.37.0
+ */
+export declare const GOOGLEBOT: VerifiedBotRule;
+/**
+ * Built-in {@link VerifiedBotRule} for Bingbot, verified against Microsoft's
+ * documented `*.search.msn.com` reverse-DNS domain.
+ *
+ * @since 0.37.0
+ */
+export declare const BINGBOT: VerifiedBotRule;
+/**
+ * Convenience bundle of the built-in verified-crawler rules
+ * ({@link GOOGLEBOT}, {@link BINGBOT}).
+ *
+ * @since 0.37.0
+ */
+export declare const WELL_KNOWN_BOTS: readonly VerifiedBotRule[];
+/**
+ * Build the default DNS resolver backed by a lazily-imported
+ * `node:dns/promises`. Used internally by {@link botGuard} when no custom
+ * {@link BotGuardOptions.resolver} is supplied, and exported for tests. Throws
+ * on runtimes without `node:dns/promises` so callers are told to supply their
+ * own resolver.
+ *
+ * @returns A {@link BotResolver} backed by the platform's DNS.
+ * @internal
+ */
+export declare function _createDefaultBotResolver(): BotResolver;
+/**
+ * Bot / User-Agent management middleware. Blocks empty or known-abusive
+ * `User-Agent` strings and verifies declared crawlers (Googlebot/Bingbot) via
+ * reverse-DNS + forward-confirm, so a spoofed `User-Agent` cannot impersonate a
+ * trusted crawler.
+ *
+ * All checks are opt-in and allowlist-friendly: {@link BotGuardOptions.allowUserAgents}
+ * is consulted first and bypasses every other rule.
+ *
+ * @param opts - Bot-guard configuration.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @throws Error when `verifiedBots` is set without an IP source
+ *   (`resolveIp` or `trustProxyHeaders`), or when `mode` is invalid.
+ * @since 0.37.0
+ */
+export declare function botGuard(opts?: BotGuardOptions): Hooks;