@osqd/bothandlerjs 0.3.0

package/dist/notify/redact.d.ts

@@ -0,0 +1,48 @@
+import type { BotEvent } from "./types.js";
+export interface RedactionOptions {
+    /**
+     * Replace client addresses with a coarse network (`/24`, `/64`) before the event
+     * leaves the process. Default true.
+     *
+     * On by default because a notification sink is usually a third party — Slack, a
+     * webhook, an aggregator — and an IP address is personal data in most of the world.
+     * The network is enough to recognise a pattern and to correlate repeat offenders,
+     * which is what an alert is for; the exact address is only needed when you are
+     * ready to act on one, and that belongs in your own logs.
+     */
+    maskIp?: boolean;
+    /** Drop the full User-Agent, keeping only the parsed shape. Default false. */
+    dropUserAgent?: boolean;
+    /** Headers never included in an outbound event, whatever else is configured. */
+    neverSend?: readonly string[];
+    /**
+     * Replace query-string *values* with a placeholder, keeping the parameter names.
+     * Default true.
+     *
+     * A query string is where password-reset tokens, invitation links, email addresses
+     * and session ids actually live, and it was the one client-supplied structure this
+     * module passed through untouched while stripping cookies and credential headers
+     * beside it. The names are what make an alert legible — a burst of `?export=` is the
+     * pattern worth seeing — and the values are what you do not want in a third party's
+     * message history.
+     */
+    maskQuery?: boolean;
+}
+/** Always stripped. Each of these carries a credential or a session. */
+/**
+ * Always stripped, wherever a request is shown to somebody other than the engine.
+ *
+ * Exported because the dashboard's header inspector needs the same list: a panel that
+ * prints the request as it arrived would otherwise print session cookies and bearer
+ * tokens onto an operator's screen, and into whatever screenshot they paste into a
+ * ticket.
+ */
+export declare const CREDENTIAL_HEADERS: readonly string[];
+/**
+ * Produces the version of an event that is safe to send somewhere else.
+ *
+ * This runs on the way *out*, not on the way in: detection sees everything, and only
+ * the copy handed to a sink is reduced. Getting that order wrong would trade
+ * detection quality for a privacy property you can have for free.
+ */
+export declare function redactEvent(event: BotEvent, options?: RedactionOptions): BotEvent;

package/dist/notify/sinks.d.ts

@@ -0,0 +1,62 @@
+import type { Notifier } from "./types.js";
+export interface ConsoleNotifierOptions {
+    /** `"pretty"` for humans, `"json"` for a log pipeline. Default `"pretty"`. */
+    format?: "pretty" | "json";
+    /** Where to write. Default `console`. */
+    target?: Pick<Console, "log" | "warn" | "error">;
+}
+/** Writes events to the console. The default sink, and the right one to start with. */
+export declare function consoleNotifier(options?: ConsoleNotifierOptions): Notifier;
+export interface WebhookNotifierOptions {
+    url: string;
+    /**
+     * Shared secret. When set, each request carries `X-BotHandler-Signature` as
+     * `sha256=<hex-free base64url HMAC>` over the exact body, plus a timestamp header.
+     *
+     * Sign your webhooks. An unsigned endpoint accepting bot alerts is an endpoint
+     * anyone on the internet can fill with fabricated ones.
+     */
+    secret?: string;
+    /** Extra headers, e.g. an API token. */
+    headers?: Record<string, string>;
+    /** Per-attempt timeout, ms. Default 5000. */
+    timeoutMs?: number;
+    /** Retries after the first attempt. Default 2, with exponential backoff. */
+    retries?: number;
+    /** `fetch` implementation. Defaults to the global. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * POSTs events as JSON.
+ *
+ * Delivery is best-effort by design. This runs outside the request path, so a slow or
+ * unreachable endpoint costs a visitor nothing — but it also means an alert can be
+ * lost, and it is not a substitute for logging events where you can query them.
+ */
+export declare function webhookNotifier(options: WebhookNotifierOptions): Notifier;
+export interface SlackNotifierOptions {
+    /** Incoming-webhook URL. */
+    url: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/** Posts a compact, readable message to a Slack incoming webhook. */
+export declare function slackNotifier(options: SlackNotifierOptions): Notifier;
+export interface NotifyJsOptions {
+    /** Base URL of your NotifyJS hub. */
+    endpoint: string;
+    /** Hub API token. */
+    token: string;
+    /** Channel or topic to publish under. Default "bothandler". */
+    topic?: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Publishes to a NotifyJS hub, so bot alerts arrive on the same devices as the rest
+ * of your operational notifications.
+ *
+ * Written against the hub's HTTP surface rather than importing the client, so this
+ * adds no dependency and works whichever version of the hub you run.
+ */
+export declare function notifyJsNotifier(options: NotifyJsOptions): Notifier;

package/dist/notify/types.d.ts

@@ -0,0 +1,56 @@
+import type { Assessment } from "../types.js";
+import type { Decision } from "../policy/types.js";
+import type { TrafficAnomaly } from "../audit.js";
+/** Why a notification was raised. */
+export type BotEventType = 
+/** An assessment concluded something other than "unknown". */
+"detection"
+/** An action was taken that withheld or altered the response. */
+ | "action"
+/** The safety guard replaced a terminal action with something recoverable. */
+ | "downgrade"
+/** A detector, sink or store failed. Operational, not about traffic. */
+ | "error"
+/**
+ * The audit noticed the *shape* of your traffic change — a spike in automation, a
+ * collapse in human traffic, a policy suddenly denying far more than usual.
+ *
+ * The one event type that is not about a single request, which is why
+ * {@link BotEvent.assessment} is optional.
+ */
+ | "anomaly";
+export interface BotEvent {
+    type: BotEventType;
+    /** ISO-8601 timestamp. */
+    at: string;
+    /** The request this is about. Absent on `anomaly`, which is about a stretch of time. */
+    assessment?: Assessment | undefined;
+    decision?: Decision | undefined;
+    /** Present on `error` events. */
+    error?: {
+        source: string;
+        message: string;
+    } | undefined;
+    /** Present on `anomaly` events. */
+    anomaly?: TrafficAnomaly | undefined;
+}
+export interface Notifier {
+    id: string;
+    /**
+     * Delivers an event.
+     *
+     * Called off the request path — the engine never awaits a sink — so taking time
+     * here is fine. Throwing is also fine: failures are caught, reported once through
+     * `onError`, and never surfaced to the client.
+     */
+    notify(event: BotEvent): void | Promise<void>;
+}
+/** Controls what a sink is told about. */
+export interface NotifyFilter {
+    /** Event types to deliver. Default: everything except `detection`. */
+    types?: readonly BotEventType[];
+    /** Minimum score for a `detection` event. Default 60. */
+    minScore?: number;
+    /** Only deliver proven detections. Default false. */
+    certainOnly?: boolean;
+}

package/dist/policy/index.d.ts

@@ -0,0 +1,7 @@
+export { Policy } from "./policy.js";
+export type { GuardSettings } from "./policy.js";
+export { compileMatch, independentStrongSignals } from "./match.js";
+export { monitorOnly, allowCrawlers, protectContent, declineAiTraining, protectData, protectApi, protectAuth, underAttack, PRESETS } from "./presets.js";
+export type { PresetName } from "./presets.js";
+export { ACTION_NAMES, TERMINAL_ACTIONS } from "./types.js";
+export type { ActionName, ActionParams, Decision, FalsePositivePolicy, MatchSpec, PolicyOptions, Rule } from "./types.js";

package/dist/policy/match.d.ts

@@ -0,0 +1,20 @@
+import type { Assessment } from "../types.js";
+import type { MatchSpec } from "./types.js";
+/**
+ * Compiles a {@link MatchSpec} into a predicate.
+ *
+ * Compiling once at policy-construction time rather than interpreting the spec per
+ * request keeps rule evaluation to a handful of set lookups, which matters when the
+ * policy is consulted on every request to the site.
+ */
+export declare function compileMatch(spec: MatchSpec): (assessment: Assessment) => boolean;
+/**
+ * Counts independent `strong`-or-better bot signals.
+ *
+ * "Independent" is approximated as "from different detectors", which is imperfect —
+ * `header-integrity` and `accept-signature` both read the same header block and are
+ * correlated — but it is a real bar that a single misfiring check cannot clear on its
+ * own. Used by the `balanced` guard, where it is the difference between "the score
+ * got high" and "several different things went wrong".
+ */
+export declare function independentStrongSignals(assessment: Assessment): number;

package/dist/policy/policy.d.ts

@@ -0,0 +1,123 @@
+import type { Assessment } from "../types.js";
+import type { ActionName, Decision, FalsePositivePolicy, PolicyOptions, Rule } from "./types.js";
+/** The settings that decide how far a rule may go. See {@link Policy.replaceGuard}. */
+export interface GuardSettings {
+    falsePositivePolicy: FalsePositivePolicy;
+    fallbackAction: ActionName;
+    defaultAction: ActionName;
+    terminalScoreThreshold: number;
+}
+/**
+ * Chooses an action for an assessment, then refuses to let that action be harsher
+ * than the evidence supports.
+ *
+ * The second half is the point. Rules are ordinary first-match-wins configuration and
+ * there is nothing clever about them. What makes the policy trustworthy is the guard
+ * that runs *after* a rule has been selected: under the default `strict` mode a
+ * terminal action survives only if `assessment.certain` is true, and otherwise is
+ * replaced by something recoverable, with the substitution recorded on the decision.
+ *
+ * That ordering is deliberate. The guard cannot be forgotten in a rule, cannot be
+ * bypassed by a cleverly-worded predicate, and does not depend on whoever wrote the
+ * rules understanding the certainty model. Turning it off is a single, explicit,
+ * greppable configuration change.
+ */
+export declare class Policy {
+    /**
+     * Compiled rules, in evaluation order.
+     *
+     * Mutable — and only ever replaced wholesale, never spliced. {@link replaceRules}
+     * swaps the array in one assignment, so a request evaluated during an update sees
+     * either the old list or the new one and never a half-applied policy.
+     */
+    private compiled;
+    /**
+     * The guard settings.
+     *
+     * Not `readonly` any more, and the reason is narrow enough to write down.
+     * {@link replaceGuard} exists so that an operator who has been *given* the power to
+     * change these can change them without a deploy — the dashboard gates it behind a
+     * control flag of its own that is off by default. Everything about how they are
+     * *used* is unchanged: `decide()` reads them on every request, so a change takes
+     * effect on the next one, and it can only ever be a whole valid set replacing
+     * another whole valid set.
+     */
+    private defaultAction;
+    private defaultParams;
+    private mode;
+    private fallbackAction;
+    private terminalScoreThreshold;
+    private readonly onDowngrade;
+    constructor(options?: PolicyOptions);
+    private static compile;
+    /** Ids of every configured rule, in evaluation order. For diagnostics and tests. */
+    get ruleIds(): string[];
+    /**
+     * The rule definitions themselves, in evaluation order.
+     *
+     * Exposed because two things outside the policy need to *read* rules rather than
+     * apply them: `robotsFromRules`, which turns the ones that deny crawlers into a
+     * `robots.txt`, and the dashboard, which shows an operator what is actually
+     * installed. Both want the spec as written, not the compiled predicate.
+     */
+    get rules(): readonly Rule[];
+    /**
+     * Replaces the rule list while the process runs.
+     *
+     * Deliberately narrow: this changes *which* rules exist, and nothing about how far
+     * they are allowed to go. The guard settings are a separate, separately-gated
+     * operation — see {@link replaceGuard} — so that "edit the rules" and "change what a
+     * rule is allowed to do" are never the same permission.
+     */
+    replaceRules(rules: readonly Rule[]): void;
+    /**
+     * Replaces the guard settings while the process runs.
+     *
+     * This is the one edit that can start denying people, so it is separated from
+     * {@link replaceRules} at every level: a different method here, a different control
+     * flag on the dashboard, a different endpoint, and a different event when it lands.
+     * A caller that may change rules does not thereby become a caller that may change
+     * this.
+     *
+     * Two things are refused outright rather than warned about, because both turn the
+     * guard into scenery while leaving it apparently switched on:
+     *
+     * - **A terminal `fallbackAction`.** The fallback is what a downgrade *becomes*.
+     *   Set it to `block` and every downgrade blocks, which is the exact outcome the
+     *   downgrade exists to prevent — and the decision would still be recorded as a
+     *   guard stop, so the metric that is supposed to catch this would report success.
+     * - **A `terminalScoreThreshold` outside 1–100.** Zero would let balanced mode
+     *   deny on any score at all.
+     *
+     * Fields left undefined keep their current value, so a caller can move one setting
+     * without restating the rest.
+     */
+    replaceGuard(settings: Partial<GuardSettings>): void;
+    /** Just the guard half of {@link describe}, in the shape {@link replaceGuard} accepts back. */
+    describeGuard(): GuardSettings;
+    /**
+     * The settings that decide how far a rule may go, for anything that reports on the
+     * policy rather than applying it — a dashboard, a diagnostic, a startup log.
+     *
+     * Worth surfacing rather than keeping private: `falsePositivePolicy` is the single
+     * setting that decides whether an unproven verdict can deny anybody, and a reader
+     * looking at a screen full of verdicts cannot interpret one without knowing it.
+     */
+    describe(): {
+        falsePositivePolicy: FalsePositivePolicy;
+        fallbackAction: ActionName;
+        defaultAction: ActionName;
+        terminalScoreThreshold: number;
+        rules: string[];
+    };
+    decide(assessment: Assessment): Decision;
+    /**
+     * The safety guard.
+     *
+     * Note what it does *not* consider: how confident the score is, how many detectors
+     * fired, or how badly the operator wants to block. Under `strict` there is exactly
+     * one question — is there proof? — and everything else is a downgrade.
+     */
+    private guard;
+    private downgrade;
+}

package/dist/policy/presets.d.ts

@@ -0,0 +1,161 @@
+import type { Rule } from "./types.js";
+/**
+ * Ready-made rule sets.
+ *
+ * Each is a starting point to read, adapt and own — not a black box. Every rule
+ * carries an id, so you can see exactly which one fired in a decision and replace
+ * just that one.
+ *
+ * All of them assume the default `strict` guard, which means even the harshest rule
+ * here cannot deny an unproven request. Choose a preset for the *shape* of the policy;
+ * the guard decides how far it is allowed to go.
+ */
+/**
+ * Watch and learn. Nothing is ever withheld from anybody.
+ *
+ * Run this first, for at least a week, on real traffic. Every bot policy that has
+ * ever caused an outage was deployed straight to enforcement by someone who was sure
+ * they knew what their traffic looked like.
+ */
+export declare function monitorOnly(): Rule[];
+/**
+ * Sensible defaults for a public content site.
+ *
+ * Keeps the crawlers that bring traffic, slows the ones that only take it, challenges
+ * what is probably automated, and blocks only what has proven itself.
+ */
+export declare function protectContent(): Rule[];
+/**
+ * For an application whose value is in its data — pricing, listings, inventory.
+ *
+ * The distinguishing move is that AI and SEO crawlers are challenged rather than
+ * allowed. That is a business decision rather than a security one, and it is exactly
+ * the kind of decision that should be a visible rule you can point at.
+ */
+export declare function protectData(): Rule[];
+/**
+ * For login, signup, password reset, checkout and anything else where automation is
+ * expensive to be wrong about in both directions.
+ *
+ * **Mount this on those routes only.** Applied site-wide it blocks your payment
+ * webhooks, your own server-side renderer and every honest crawler you have — all of
+ * which are proven automation, which is exactly what this preset refuses. That is
+ * correct behaviour on a login form and an outage anywhere else; the traffic corpus
+ * catches it, and it is the kind of mistake whose symptom is a support ticket about
+ * missing orders three days later.
+ *
+ * ```ts
+ * app.use("/login", botHandler(authDetector));
+ * app.use("/checkout", botHandler(authDetector));
+ * ```
+ *
+ * The unusual choice here is `delay` on merely-suspected traffic. A quarter of a
+ * second is imperceptible to a person filling in a form and ruinous to a credential
+ * stuffer working through a list — and, unlike a challenge, it excludes nobody.
+ */
+export declare function protectAuth(): Rule[];
+/**
+ * For a publisher whose problem is being *found*, not being scraped.
+ *
+ * The distinguishing move is that it allows more than it stops, explicitly and by
+ * name. Verified crawlers are allowed ahead of everything; declared benign
+ * automation — link unfurlers, feed readers, uptime monitors, the specialist search
+ * fleets — is allowed rather than merely tolerated; and the only things refused are
+ * the three that are refused everywhere, because they are proven and cannot be
+ * anything else.
+ *
+ * Reach for this when a bot policy has already cost you traffic, or when the site's
+ * whole purpose is to be indexed, quoted and shared. The cost is honest: bulk
+ * extraction gets rate-limited rather than challenged, so a determined scraper will
+ * get your content. On a site that wants to be read, that was always going to be
+ * true; what this preset refuses to do is trade away your search traffic to make it
+ * slightly less true.
+ */
+export declare function allowCrawlers(): Rule[];
+/**
+ * Keep the search engines. Decline the model trainers.
+ *
+ * This is the policy question of the moment, and it is a *business* decision rather
+ * than a security one — which is exactly the kind of decision this library thinks
+ * should be a visible rule you can point at rather than a threshold somebody tuned.
+ *
+ * The split it draws is the one the AI crawlers themselves publish. A crawler
+ * collecting a training corpus and a crawler fetching one page because a person asked
+ * a question about it are different jobs, often from the same operator under different
+ * product tokens, and a policy that cannot tell them apart either feeds the trainers or
+ * breaks the citations. Here the training fleet is declined and everything else is
+ * served.
+ *
+ * **`robots.txt` is the primary mechanism, not this.** The crawlers named here honour
+ * it, and a rule that blocks a crawler nobody told is a rule that produces load and no
+ * compliance. Generate the file from this policy — `robotsFromRules(declineAiTraining())`
+ * — publish it, and treat these rules as what happens to the ones that ignore it.
+ */
+export declare function declineAiTraining(): Rule[];
+/**
+ * For a JSON API rather than a site.
+ *
+ * One difference drives the whole shape of this preset: **a challenge is useless
+ * here.** A proof-of-work interstitial is solved by a browser running JavaScript, and
+ * an API client is not one. Challenging your customers' integrations does not slow an
+ * attacker down; it breaks the integrations and leaves the attacker to solve it once
+ * in a headless browser. So the escalation ladder is rate limiting, and the terminal
+ * actions stay where they always are — on proof.
+ *
+ * The second difference is about what bot detection is *for* on an API. Your
+ * authentication is the control that matters, and it already knows who the caller is.
+ * This preset therefore tags everything, so your own handlers can combine a verdict
+ * with a key, a plan and a quota; it does not try to be the access control.
+ *
+ * A bare HTTP client is not suspicious here — it is the normal case, and the rule that
+ * challenges one on a content site is deliberately absent.
+ */
+export declare function protectApi(): Rule[];
+/**
+ * For while it is happening.
+ *
+ * A deliberately impatient posture for an incident: a scrape in progress, a stuffing
+ * run, a scanner sweeping the range. Everything proven is refused, everything
+ * suspected is challenged at a much lower bar than usual, and *everyone* — including
+ * the people — is rate-limited, because a uniform ceiling is the one mitigation that
+ * cannot single anybody out.
+ *
+ * Three things to be clear about before turning it on.
+ *
+ * **It is temporary.** Nothing here is a good permanent policy: the low challenge
+ * threshold will interrupt real people on unusual browsers, and the uniform rate limit
+ * will interrupt your keenest readers. Turn it on during an incident, turn it off
+ * afterwards, and put it behind a switch you can flip without a deploy —
+ * `updatePolicy()` and the dashboard's editor exist for exactly this.
+ *
+ * **It still cannot deny anyone on a guess.** The guard applies here as everywhere
+ * else: the `challenge` on suspicion is a challenge because that is as far as
+ * unproven evidence may go, and asking for a block instead would simply be refused
+ * and recorded. An incident is precisely when people reach for `falsePositivePolicy:
+ * "aggressive"`, and precisely when the population getting caught is at its most
+ * unusual.
+ *
+ * **It is not DDoS protection.** This runs inside your process, after the connection
+ * has been accepted. Volume that hurts you at the network layer needs handling at the
+ * network layer; what this reduces is the *usefulness* of the traffic to whoever is
+ * sending it.
+ *
+ * And one practical warning the traffic corpus makes concrete: like `protect-auth`,
+ * this refuses proven automation, so **your own webhooks, health probes and
+ * server-side renderer are refused too** — thirteen of the corpus's infrastructure
+ * cases are, under this policy. Allowlist their addresses *before* you switch it on,
+ * not during the incident when you notice.
+ */
+export declare function underAttack(): Rule[];
+/** Every preset by name, for config-driven setups. */
+export declare const PRESETS: {
+    readonly "monitor-only": typeof monitorOnly;
+    readonly "allow-crawlers": typeof allowCrawlers;
+    readonly "protect-content": typeof protectContent;
+    readonly "decline-ai-training": typeof declineAiTraining;
+    readonly "protect-data": typeof protectData;
+    readonly "protect-api": typeof protectApi;
+    readonly "protect-auth": typeof protectAuth;
+    readonly "under-attack": typeof underAttack;
+};
+export type PresetName = keyof typeof PRESETS;

package/dist/policy/types.d.ts

@@ -0,0 +1,155 @@
+import type { Assessment, BotClass, Verdict } from "../types.js";
+import type { BotCategory } from "../detectors/known-bots.js";
+/**
+ * What the engine does about an assessment.
+ *
+ * Ordered roughly by how much they cost a client that turns out to be a person:
+ *
+ * - `allow` — nothing at all. The verdict is still emitted for logging.
+ * - `tag` — serve normally, attach headers describing the verdict so a downstream
+ *   service (your app, a cache, an edge worker) can decide for itself.
+ * - `log` — serve normally and raise a notification. Costs the client nothing.
+ * - `delay` — serve normally, but slowly. Invisible to a person, expensive at scale.
+ * - `rate-limit` — serve until a threshold, then reject with `429` and `Retry-After`.
+ *   Recovers on its own.
+ * - `challenge` — withhold the response until the client passes a check. Recoverable
+ *   by the client itself, which is what makes it the safe escalation. It does still
+ *   shut out anyone without JavaScript, so it is not free.
+ * - `redirect` — send the client somewhere else.
+ * - `block` — refuse, with a status and a body explaining it.
+ * - `drop` — close the connection without a response.
+ *
+ * `redirect`, `block` and `drop` are **terminal**: the client is denied and cannot
+ * recover on its own. Those are the three the safety guard governs.
+ */
+export type ActionName = "allow" | "tag" | "log" | "delay" | "rate-limit" | "challenge" | "redirect" | "block" | "drop" | "custom";
+/** Every action, ordered by how much it costs a client that turns out to be a person. */
+export declare const ACTION_NAMES: readonly ActionName[];
+/** Actions a client cannot recover from by itself. The guard's whole concern. */
+export declare const TERMINAL_ACTIONS: ReadonlySet<ActionName>;
+export interface ActionParams {
+    /** Status for `block`. Default 403. */
+    status?: number | undefined;
+    /** Response body for `block`. Defaults to a short plain-text explanation. */
+    body?: string | undefined;
+    contentType?: string | undefined;
+    /** Target for `redirect`. Must be same-origin or an absolute URL you control. */
+    location?: string | undefined;
+    /** Milliseconds for `delay`. */
+    delayMs?: number | undefined;
+    /** Ceiling for `rate-limit`. */
+    limit?: {
+        max: number;
+        windowMs: number;
+    } | undefined;
+    /** Extra response headers, merged after the engine's own. */
+    headers?: Record<string, string> | undefined;
+    /** Handler id for `custom`. */
+    handler?: string | undefined;
+}
+export interface Decision {
+    action: ActionName;
+    /** Id of the rule that produced it, or `"default"`. */
+    rule: string;
+    /** Sentence explaining the choice, safe to log and to show an operator. */
+    reason: string;
+    params: ActionParams;
+    /**
+     * Set when the safety guard replaced a stronger action. Both the original and the
+     * substitute are recorded, because a policy silently doing less than it says is
+     * worse than one that refuses loudly.
+     */
+    downgradedFrom?: ActionName | undefined;
+    /** Why the downgrade happened. */
+    downgradeReason?: string | undefined;
+}
+/** Declarative matcher. Every field present must match; absent fields are ignored. */
+export interface MatchSpec {
+    verdict?: Verdict | readonly Verdict[];
+    botClass?: BotClass | readonly BotClass[];
+    /** Established or claimed identity, e.g. `"googlebot"`. */
+    identity?: string | readonly string[];
+    /** Category of the matched signature, e.g. `"ai"`, `"seo"`. */
+    category?: BotCategory | readonly BotCategory[];
+    /**
+     * Require (or forbid) proven evidence.
+     *
+     * Note what this does *not* mean: `certain` is about the strength of the evidence,
+     * not its direction, so `{ certain: true }` also matches a proven **human** — a
+     * customer your application vouched for through `grantClearance`. A rule intended
+     * for automation must say so, either by putting an allow rule for `verdict: "human"`
+     * ahead of it or by naming the verdicts it means. Both shipped presets had this
+     * wrong until the traffic corpus caught it.
+     */
+    certain?: boolean;
+    minScore?: number;
+    maxScore?: number;
+    /** Request path. Strings match as a prefix; regexes are tested as written. */
+    path?: string | RegExp | readonly (string | RegExp)[];
+    method?: string | readonly string[];
+    /** Fires when any evidence came from one of these detectors. */
+    detector?: string | readonly string[];
+    /** Fires only when the actor has been proven a bot at least this many times before. */
+    minPriorConfirmations?: number;
+    /**
+     * Fires only when this actor has this many challenges outstanding — issued, and never
+     * answered.
+     *
+     * A rule rather than evidence, and the difference is the point. Somebody who abandons
+     * a challenge is somebody: a slow phone, a lost tab, a change of mind. It is only
+     * *repetition* that means anything, and how much it means depends on traffic the
+     * library cannot see — a checkout flow and a documentation site should read the same
+     * number differently. So the engine counts, and your policy decides.
+     *
+     * Solving one clears the count, so this never accumulates against a person who came
+     * back and proved it.
+     *
+     * ```ts
+     * { id: "persistent-refusers", match: { minUnsolvedChallenges: 3 }, action: "rate-limit" }
+     * ```
+     */
+    minUnsolvedChallenges?: number;
+}
+export interface Rule {
+    /** Stable id. Appears in every decision and log line this rule produces. */
+    id: string;
+    /** Declarative spec, or a predicate for anything the spec cannot express. */
+    match: MatchSpec | ((assessment: Assessment) => boolean);
+    action: ActionName;
+    params?: ActionParams;
+    /** Overrides the generated explanation. */
+    reason?: string;
+}
+/**
+ * How strictly the engine refuses to act on unproven evidence.
+ *
+ * - **`strict`** (default) — a terminal action requires `assessment.certain`. A rule
+ *   asking to block on a probabilistic verdict is downgraded to `fallbackAction` and
+ *   the substitution is recorded. This is the mode in which the library's central
+ *   claim holds: nothing is ever denied service on the strength of a guess.
+ * - **`balanced`** — terminal actions additionally allowed when the score clears
+ *   `terminalScoreThreshold` **and** at least two independent `strong` signals fired.
+ *   Two independent strong signals is a much higher bar than a score alone, which any
+ *   number of weak correlated observations can reach. It is still, unambiguously, a
+ *   probabilistic decision — some real people will be caught.
+ * - **`aggressive`** — rules run exactly as written. Choose this only with a way to
+ *   see who you turned away, and a way for them to reach you.
+ */
+export type FalsePositivePolicy = "strict" | "balanced" | "aggressive";
+export interface PolicyOptions {
+    /** Evaluated in order; the first match wins. */
+    rules?: readonly Rule[];
+    /** Used when no rule matches. Default `allow`. */
+    defaultAction?: ActionName;
+    defaultParams?: ActionParams;
+    falsePositivePolicy?: FalsePositivePolicy;
+    /**
+     * Substituted when the guard blocks a terminal action. Default `challenge` if a
+     * challenge is configured, otherwise `tag`.
+     */
+    fallbackAction?: ActionName;
+    /** Score needed for a terminal action under `balanced`. Default 85. */
+    terminalScoreThreshold?: number;
+    /** Called whenever the guard downgrades, so a mismatch between intent and effect is visible. */
+    onDowngrade?: ((decision: Decision, assessment: Assessment) => void) | undefined;
+}