@osqd/bothandlerjs 0.3.0

package/dist/robots.d.ts

@@ -0,0 +1,83 @@
+import type { BotCategory, BotSignature } from "./detectors/known-bots.js";
+import type { Rule } from "./policy/types.js";
+/**
+ * Generating `robots.txt` from what your policy actually does.
+ *
+ * Declining a crawler and not saying so is the worst of both worlds: the crawler
+ * keeps coming, wastes your bandwidth discovering it is unwelcome on every request,
+ * and you get no credit for having a policy. `robots.txt` is where you say it — and
+ * for the well-behaved crawlers, saying it is the *only* thing you need to do, since
+ * they will simply stop.
+ *
+ * Two things this file will not pretend. `robots.txt` is a request, not enforcement;
+ * everything that ignores it is exactly the population this library exists for. And a
+ * generated file can only reflect rules it can *read* — see {@link robotsFromRules}.
+ */
+export interface RobotsOptions {
+    /** Signature ids to disallow entirely, e.g. `["gptbot", "ccbot"]`. */
+    disallowBots?: readonly string[];
+    /** Whole categories to disallow, e.g. `["ai", "seo"]`. */
+    disallowCategories?: readonly BotCategory[];
+    /** Paths disallowed for every crawler. Put your trap paths here. */
+    disallowPaths?: readonly string[];
+    /** Paths explicitly allowed for every crawler, evaluated ahead of the disallows. */
+    allowPaths?: readonly string[];
+    /** `Sitemap:` lines. Absolute URLs, per the specification. */
+    sitemap?: string | readonly string[];
+    /** `Crawl-delay:` in seconds for the wildcard group. Not honoured by every crawler. */
+    crawlDelay?: number;
+    /** Signature database to resolve ids and categories against. */
+    signatures?: readonly BotSignature[];
+    /** Lines added verbatim at the top, each already comment-prefixed if you want comments. */
+    header?: readonly string[];
+}
+/**
+ * Renders a `robots.txt`.
+ *
+ * Group ordering follows RFC 9309: a crawler obeys the most specific group that names
+ * it and ignores every other, so the per-agent groups must repeat any global path
+ * rules that should still apply to them. That is handled here — forgetting it is the
+ * classic way a `robots.txt` accidentally *un*-blocks a trap path for exactly the
+ * crawlers you were most careful about.
+ */
+export declare function generateRobotsTxt(options?: RobotsOptions): string;
+/** The `User-agent:` token for a signature. Matching is case-insensitive, so the token works either way. */
+export declare function agentFor(signature: BotSignature): string;
+export interface RobotsFromRulesResult {
+    robotsTxt: string;
+    /**
+     * Every signature id the generated file declines, with categories expanded to the
+     * crawlers they cover. Reporting only the explicitly-named ids would say "0
+     * declined" for a policy that turns away an entire category.
+     */
+    declined: string[];
+    /**
+     * Signature ids a later rule would have declined, but an earlier rule serves.
+     *
+     * First match wins, so these are *not* in the file. Worth reporting rather than
+     * silently omitting: "why is GPTBot in my robots.txt but ChatGPT-User is not" has an
+     * answer, and it is your own rule order.
+     */
+    served: string[];
+    /**
+     * Rules that could not be read, with the reason.
+     *
+     * A rule whose `match` is a predicate function is opaque — we can run it, but we
+     * cannot ask it which crawlers it is about. Those are listed rather than guessed
+     * at, because a `robots.txt` that silently omits something you block is worse than
+     * no generated file at all: it tells crawlers they are welcome where they are not.
+     */
+    unreadable: Array<{
+        rule: string;
+        reason: string;
+    }>;
+}
+/**
+ * Derives a `robots.txt` from the declarative rules in a policy.
+ *
+ * Reads every rule whose action denies service and whose `match` names an `identity`
+ * or a `category`, and declines exactly those crawlers. Rules expressed as predicate
+ * functions cannot be introspected and are reported in `unreadable` — check that list
+ * before publishing, and add anything it names by hand.
+ */
+export declare function robotsFromRules(rules: readonly Rule[], options?: RobotsOptions): RobotsFromRulesResult;

package/dist/state.d.ts

@@ -0,0 +1,161 @@
+import type { Clock } from "./internal/clock.js";
+import type { ActorSnapshot, RequestFacts } from "./types.js";
+/**
+ * The ceilings a detector's thresholds have to live under.
+ *
+ * Exported because they are not an implementation detail to anyone configuring a
+ * threshold: an actor's arrival count and distinct-User-Agent count both saturate
+ * here, so a threshold above them can never be reached and the detector is silently
+ * switched off. That is the failure this library refuses to ship elsewhere — a
+ * control that looks configured and is not — so the detectors check against these and
+ * refuse to be built that way.
+ */
+export declare const MAX_TRACKED_ARRIVALS = 32;
+export declare const MAX_TRACKED_PATHS = 64;
+export declare const MAX_TRACKED_USER_AGENTS = 4;
+export declare class ActorState {
+    readonly key: string;
+    readonly firstSeen: number;
+    lastSeen: number;
+    /** Total requests seen in this actor's lifetime within the registry window. */
+    total: number;
+    /** Assessments *this process* concluded were `confirmed-bot`. */
+    confirmations: number;
+    /**
+     * Confirmations other replicas had already recorded when this instance first saw the
+     * actor, or `undefined` when nothing shared them.
+     *
+     * Kept apart from the local count rather than added into it, so that the two facts
+     * stay distinguishable: what we saw, and what we were told. `priorConfirmations` is
+     * their sum, which is the number a rule means when it says
+     * `minPriorConfirmations: 1`.
+     */
+    sharedConfirmations: number | undefined;
+    /** Epoch ms until which a valid human clearance token stands. */
+    clearedUntil: number;
+    /**
+     * Challenges issued to this actor that no solution ever came back for.
+     *
+     * Incremented when one is issued and cleared when one is solved, so it is the number
+     * *outstanding* rather than a lifetime total: an actor challenged five times that
+     * solved the fifth reads zero, and one challenged five times that solved none reads
+     * five.
+     *
+     * The distinction is the whole signal. A person who abandons one challenge is
+     * ordinary — a slow phone, a lost tab, a change of mind. A client that has been asked
+     * five times and never once come back is not abandoning; it is unable or unwilling,
+     * and both of those are facts about software.
+     */
+    unsolvedChallenges: number;
+    private readonly timestamps;
+    private ringLength;
+    private ringNext;
+    private readonly paths;
+    private pathsOverflowed;
+    private pathsSaturatedAtTotal;
+    private readonly userAgents;
+    constructor(key: string, now: number);
+    /** Records an arrival. Called exactly once per request, by the engine. */
+    record(facts: RequestFacts): void;
+    /** Distinct paths seen, by hash. Saturates at {@link PATH_CAP}; `pathsSaturated` says whether it did. */
+    get distinctPaths(): number;
+    get pathsSaturated(): boolean;
+    /**
+     * Requests seen when {@link distinctPaths} stopped being able to grow, or 0 if it
+     * still can. Over that many requests the distinct count is exact, so it is the only
+     * window in which a novelty ratio means anything.
+     */
+    get requestsWhenPathsSaturated(): number;
+    /** Distinct User-Agent strings. More than one from a single actor is unusual for a person. */
+    get distinctUserAgents(): number;
+    /** Milliseconds since the previous request, or `undefined` when this is the first. */
+    sinceLast(now: number): number | undefined;
+    /**
+     * Requests received in the last `windowMs`.
+     *
+     * Saturates at {@link TIMESTAMP_RING}: a very heavy actor is reported as exactly
+     * that number, not its true rate, and `ringSaturated` says so. That ceiling is
+     * deliberate. This series exists to *describe* an actor cheaply, and precise
+     * counting belongs to the rate-limit action, which uses the store and is exact.
+     */
+    requestsWithin(windowMs: number, now: number): number;
+    /** True when the ring is full, i.e. `requestsWithin` may be undercounting a heavy actor. */
+    get ringSaturated(): boolean;
+    /**
+     * Gaps between consecutive arrivals, oldest first. The cadence detector looks at
+     * the *variance* of these: a person's gaps are ragged, a `setInterval` loop's are
+     * not.
+     */
+    intervals(): number[];
+    /**
+     * Mean and dispersion of the arrival gaps, in one pass and without allocating.
+     *
+     * `intervals()` builds two arrays to answer the same question, and the cadence
+     * detector asks it on every request from every actor with enough history. Welford's
+     * algorithm gives the same numbers in a single walk of the ring with no garbage —
+     * and, incidentally, without the catastrophic cancellation that the naive
+     * sum-of-squares form suffers when gaps are large and their variance is small,
+     * which is precisely the machine-regular case this statistic exists to detect.
+     */
+    intervalStats(): {
+        count: number;
+        mean: number;
+        coefficientOfVariation: number;
+    };
+    snapshot(now: number): ActorSnapshot;
+}
+export interface ActorRegistryOptions {
+    /** How long an idle actor is remembered. Default 900000 (15 min). */
+    windowMs?: number;
+    /** Maximum actors tracked concurrently. Default 20000. See the cap arithmetic above. */
+    maxActors?: number;
+}
+/**
+ * One actor as a list can show it: the snapshot every rule reads, plus the two
+ * behavioural measures a person scanning for the worst offender actually wants.
+ */
+export interface ActorSummary extends ActorSnapshot {
+    /** Requests in the last minute — a rate, where `requests` is a total. */
+    recentRate: number;
+    distinctUserAgents: number;
+    /** Regularity of the gaps between requests. Near zero is metronomic; `undefined` is too few gaps to say. */
+    cadenceCv: number | undefined;
+}
+/** Bounded LRU of {@link ActorState}, keyed by whatever `actorKey` produced. */
+export declare class ActorRegistry {
+    private readonly clock;
+    private readonly actors;
+    constructor(clock: Clock, options?: ActorRegistryOptions);
+    get size(): number;
+    /** Fetches or creates the state for `key` and records this request against it. */
+    /**
+     * Called once for each actor this registry has not seen before.
+     *
+     * The hook exists so `BotHandler` can go and ask the store what other replicas know
+     * about a newcomer, without the registry itself learning what a store is. It fires
+     * exactly once per actor per instance — not once per request — which is the whole
+     * reason this is affordable: the thing `state.ts` refuses to do is a round trip on
+     * the request path, not a round trip ever.
+     */
+    onFirstSight?: (state: ActorState) => void;
+    observe(key: string, facts: RequestFacts): ActorState;
+    /** Reads without recording. Used by the clearance path, which must not inflate rates. */
+    peek(key: string): ActorState | undefined;
+    /**
+     * The busiest actors the registry is currently holding, most requests first.
+     *
+     * The registry knows about far more actors than any feed does — up to `maxActors`,
+     * each with its rate series, its path breadth and its confirmations — while a
+     * dashboard's ring holds a few hundred *requests*, which on a busy origin is a few
+     * seconds. "Who is hitting me hardest right now" is a question only this can answer,
+     * and until this method existed nothing could ask it.
+     *
+     * A read, and only a read: it neither records a request against an actor nor moves
+     * one up the LRU, so watching the list cannot change what it lists.
+     */
+    top(limit: number, now: number): ActorSummary[];
+    forget(key: string): void;
+    clear(): void;
+    /** Marks an actor as holding valid human clearance until `until`. */
+    clearUntil(key: string, until: number): void;
+}

package/dist/stores/index.d.ts

@@ -0,0 +1,5 @@
+export type { BotHandlerStore } from "./types.js";
+export { MemoryStore } from "./memory.js";
+export type { MemoryStoreOptions } from "./memory.js";
+export { RedisStore } from "./redis.js";
+export type { RedisLike, RedisStoreOptions } from "./redis.js";

package/dist/stores/memory.d.ts

@@ -0,0 +1,33 @@
+import type { Clock } from "../internal/clock.js";
+import type { BotHandlerStore } from "./types.js";
+export interface MemoryStoreOptions {
+    /** Maximum distinct counter keys held. Default 100000. */
+    maxCounters?: number;
+    /** Maximum single-use token keys held. Default 100000. */
+    maxTokens?: number;
+    /** Maximum general key/value entries held. Default 20000. */
+    maxValues?: number;
+    clock?: Clock;
+}
+/**
+ * In-process store. The default, and correct for a single instance.
+ *
+ * Every structure is a bounded LRU, so this cannot be grown without limit by a
+ * client sending unbounded distinct keys. That bounding has a consequence worth
+ * knowing: under heavy key churn an old single-use token can be evicted before it
+ * expires, and a replay of *that* token would then succeed. If replay resistance
+ * matters to you — and on more than one replica it definitely does — use
+ * {@link RedisStore}.
+ */
+export declare class MemoryStore implements BotHandlerStore {
+    private readonly counters;
+    private readonly tokens;
+    private readonly values;
+    private readonly clock;
+    constructor(options?: MemoryStoreOptions);
+    increment(key: string, windowMs: number): Promise<number>;
+    consumeOnce(key: string, ttlMs: number): Promise<boolean>;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/stores/redis.d.ts

@@ -0,0 +1,59 @@
+import type { BotHandlerStore } from "./types.js";
+import type { Clock } from "../internal/clock.js";
+/**
+ * The handful of commands this store needs, described structurally.
+ *
+ * Declaring the shape rather than importing a client keeps `ioredis` and `node-redis`
+ * out of this library's dependency tree — you pass whichever you already run. Both
+ * satisfy this interface as-is.
+ */
+export interface RedisLike {
+    incr(key: string): Promise<number>;
+    pexpire(key: string, ms: number): Promise<unknown>;
+    /**
+     * `SET key value PX ttl [NX]`.
+     *
+     * Both forms are needed and they are not interchangeable: `consumeOnce` requires
+     * `NX` (the atomic claim that makes replay protection work), while `set` must
+     * overwrite or it silently keeps the first value written under a key forever.
+     */
+    set(key: string, value: string, mode: "PX", ttl: number, condition?: "NX"): Promise<unknown>;
+    get(key: string): Promise<string | null>;
+    del(key: string): Promise<unknown>;
+}
+export interface RedisStoreOptions {
+    /** Prefix for every key. Default `"bh:"`. Change it if the instance is shared. */
+    prefix?: string;
+    /**
+     * Where the window boundary comes from. Defaults to the system clock.
+     *
+     * Present for the same reason every other stateful piece of this library takes one:
+     * a fixed window derived from `Date.now()` cannot be tested without sleeping, and a
+     * rate limit is exactly the thing you want to test at the boundary rather than
+     * near it. Pass the handler's own clock to keep one notion of time throughout.
+     */
+    clock?: Clock;
+}
+/**
+ * Redis-backed shared state, for deployments with more than one replica.
+ *
+ * This is the configuration in which single-use tokens and rate limits actually mean
+ * what they say — see {@link BotHandlerStore} for why per-instance memory silently
+ * weakens both.
+ *
+ * Note what is deliberately *not* here: nothing writes per-request behavioural data.
+ * Detection stays local and synchronous. A Redis round-trip happens only when a
+ * challenge is solved or a rate limit is consulted, so a slow or unavailable Redis
+ * costs you those two features and leaves everything else untouched.
+ */
+export declare class RedisStore implements BotHandlerStore {
+    private readonly client;
+    private readonly prefix;
+    private readonly clock;
+    constructor(client: RedisLike, options?: RedisStoreOptions);
+    increment(key: string, windowMs: number): Promise<number>;
+    consumeOnce(key: string, ttlMs: number): Promise<boolean>;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/stores/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared state, for the two things that genuinely need it across replicas.
+ *
+ * The library keeps its behavioural series in-process on purpose (see `state.ts`),
+ * so this interface is small by design. It exists for the cases where a per-instance
+ * answer is actually *wrong* rather than merely less precise:
+ *
+ * - **Single-use tokens.** A challenge solution accepted twice is a replay. With
+ *   per-instance memory a scraper simply retries against another replica until it
+ *   lands on one that has not seen the nonce, which defeats the mechanism entirely.
+ * - **Rate limiting.** A limit of 100/minute enforced independently by four replicas
+ *   is a limit of 400/minute.
+ *
+ * Every method may reject. Callers treat a rejection as "no answer" and fail *open* —
+ * a store outage must degrade detection, never take down the site it protects.
+ */
+export interface BotHandlerStore {
+    /**
+     * Adds one to a counter that expires `windowMs` after its first increment, and
+     * returns the new value. A fixed window, not a sliding one: it is one round trip
+     * instead of several, and the extra precision buys nothing for a mechanism whose
+     * job is to bound abuse rather than to measure it.
+     */
+    increment(key: string, windowMs: number): Promise<number>;
+    /**
+     * Atomically claims `key`. Returns `true` the first time and `false` for every
+     * subsequent call within `ttlMs`.
+     *
+     * Atomicity is the whole point — a `get` followed by a `set` has a window in which
+     * two concurrent replays both succeed. Implementations must use a single
+     * check-and-set operation.
+     */
+    consumeOnce(key: string, ttlMs: number): Promise<boolean>;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Core vocabulary. Everything else in the library is written against these types.
+ *
+ * The single most important idea here is the split between **proof** and
+ * **suspicion**, expressed as {@link Certainty}. It is what lets the engine offer a
+ * real no-false-positive guarantee on its blocking path without pretending that bot
+ * detection is a solved problem: probabilistic signals exist, they are useful, and
+ * they are structurally barred from reaching a terminal action.
+ */
+/** What kind of client we believe we are talking to. */
+export type BotClass = 
+/** Positive evidence of a person driving a real browser. */
+"human"
+/** A crawler whose *identity* was confirmed, not merely claimed. See `verified-crawler`. */
+ | "verified-bot"
+/** Announces itself as a bot in its User-Agent and does not pretend otherwise. */
+ | "declared-bot"
+/** A real browser engine driven by automation (Puppeteer, Playwright, Selenium). */
+ | "automation"
+/** A bare HTTP library or CLI: curl, wget, requests, axios, Go's http client. */
+ | "http-client"
+/** Security/vulnerability scanning and fuzzing tooling. */
+ | "scanner"
+/** Behaves like bulk content extraction regardless of what it claims to be. */
+ | "scraper"
+/**
+ * Claims an identity it provably does not have — a forged `Googlebot`, a
+ * `Sec-CH-UA` that contradicts its own User-Agent. The most actionable class we
+ * produce, because the contradiction is self-evident from the request.
+ */
+ | "impersonator"
+/** Nothing pointed either way with enough weight to name a class. */
+ | "unknown";
+/**
+ * How much a piece of evidence is worth — and, critically, whether it is allowed to
+ * get a request blocked.
+ *
+ * - `certain` — **deterministic**. The request is self-contradictory, self-declaring,
+ *   or its identity was verified against an authority outside the request itself.
+ *   No legitimate human client produces it. Only this tier may drive a terminal
+ *   action under the default policy, and every `certain` evidence must carry a
+ *   `deterministicBasis` explaining why it cannot be wrong.
+ * - `strong` / `moderate` / `weak` — **probabilistic**. Real signals, genuinely
+ *   useful in aggregate, but each has a population of legitimate clients that trips
+ *   it: privacy browsers, corporate proxies, accessibility tooling, someone on a
+ *   train tunnel. These accumulate into a score and can drive a challenge, a tag, or
+ *   an alert. They cannot, by default, drive a block.
+ */
+export type Certainty = "certain" | "strong" | "moderate" | "weak";
+/** Which way a piece of evidence points. Human evidence actively rebuts bot evidence. */
+export type EvidenceDirection = "bot" | "human";
+/** One observation from one detector. Detectors return these; they never return verdicts. */
+export interface Evidence {
+    /** Id of the detector that produced this. */
+    detector: string;
+    /** Human-readable, log-safe explanation of what was observed. */
+    summary: string;
+    direction: EvidenceDirection;
+    certainty: Certainty;
+    /**
+     * Contribution to the suspicion score, 0–1. Defaults to the weight implied by
+     * `certainty` ({@link CERTAINTY_WEIGHT}); override only to express that a signal is
+     * unusually weak or strong *for its tier*.
+     */
+    weight?: number | undefined;
+    /**
+     * A shared *root cause*, when this observation has one.
+     *
+     * Two pieces of evidence in the same family are not two reasons to be suspicious —
+     * they are one circumstance seen twice. A corporate proxy that strips
+     * `Sec-Fetch-*` also strips the Client Hints and the `Accept-Language`, and every
+     * detector that reasons from absence then fires at once about a single person
+     * behind a single appliance. Noisy-OR assumes independence; these are not
+     * independent, and treating them as if they were is how an ordinary employee
+     * accumulates a score of 95.
+     *
+     * {@link CERTAINTY_WEIGHT} scoring therefore takes the **strongest** observation in
+     * each family rather than compounding them. Leave it undefined when a signal really
+     * does stand on its own — every unfamilied piece of evidence is its own family, so
+     * the default is the old behaviour.
+     */
+    family?: string | undefined;
+    /** The class this evidence argues for, if it argues for one. */
+    botClass?: BotClass | undefined;
+    /** A concrete identity this evidence establishes or claims, e.g. `"googlebot"`. */
+    identity?: string | undefined;
+    /**
+     * Required on `certain` evidence: why this observation admits no benign
+     * explanation. Enforced at runtime in development (see {@link BotHandlerConfig.strictEvidence}).
+     * Writing one is a useful forcing function — if you cannot, your evidence is `strong`.
+     */
+    deterministicBasis?: string | undefined;
+    /** Structured detail for logs and dashboards. Must be JSON-serialisable. */
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * Every verdict and class, in a fixed order.
+ *
+ * Exported because three places need to enumerate them — the metrics counters, the
+ * dashboard's rule editor, and anything generating documentation — and three hand-kept
+ * copies is how a new verdict ends up missing from one of them.
+ */
+export declare const VERDICTS: readonly Verdict[];
+export declare const BOT_CLASSES: readonly BotClass[];
+/** Score contribution implied by each certainty tier. */
+export declare const CERTAINTY_WEIGHT: Record<Certainty, number>;
+/**
+ * The engine's conclusion about a request.
+ *
+ * `confirmed-bot` and `verified-bot` are *proven*: they rest on at least one
+ * `certain` evidence. `suspected-bot` is a judgement call from accumulated
+ * probabilistic signal — treat it as "worth a challenge", never as "worth a 403".
+ */
+export type Verdict = 
+/** Proven automated: self-declared, self-contradictory, or caught in a trap. */
+"confirmed-bot"
+/** Proven automated *and* proven to be who it says it is — Googlebot, Bingbot. */
+ | "verified-bot"
+/** Probabilistic. Enough signal to act gently; not enough to be sure. */
+ | "suspected-bot"
+/** Positive evidence of a person (valid attestation, real interaction, clearance token). */
+ | "human"
+/** Nothing conclusive either way. The default resting state of ordinary traffic. */
+ | "unknown";
+/** A request reduced to exactly the facts detectors are allowed to see. */
+export interface RequestFacts {
+    /** Uppercase HTTP method. */
+    method: string;
+    /** Path only, no query string. Always begins with `/`. */
+    path: string;
+    /** Decoded query parameters. Null-prototype so `?__proto__=x` is visible, not swallowed. */
+    query: Record<string, string>;
+    /** Lowercased header names to values. Multi-value headers are joined with `, `. */
+    headers: Record<string, string | undefined>;
+    /**
+     * Header names in the order the client actually sent them, lowercased. Browsers
+     * emit a stable, engine-specific order; most tooling does not. Empty when the
+     * transport does not expose ordering (HTTP/2 pseudo-headers, some proxies).
+     */
+    headerOrder: readonly string[];
+    /** Resolved client IP. See {@link ProxyConfig} for how this is derived. */
+    ip: string;
+    /** Wall-clock arrival time, ms since epoch. Injected so tests can control it. */
+    timestamp: number;
+    /** Parsed request cookies, if the adapter supplied them. */
+    cookies?: Record<string, string> | undefined;
+    /** `https` when the connection is TLS-terminated at or before this server. */
+    protocol?: "http" | "https" | undefined;
+    /** Negotiated HTTP version, e.g. `"1.1"`, `"2.0"`. Used for header-order sanity. */
+    httpVersion?: string | undefined;
+    /**
+     * TLS client fingerprint (JA3/JA4), if your edge computes one and forwards it.
+     * Never computed here — Node does not expose the ClientHello.
+     */
+    tlsFingerprint?: string | undefined;
+    /**
+     * Set when the header set is known to be **incomplete** — the source could not
+     * supply everything the client actually sent.
+     *
+     * This is a statement about the observer, not the client, and it changes what an
+     * absent header means. Several detectors treat "no `Accept-Language`" as evidence,
+     * which is sound for a live request and nonsense for a line of an access log that
+     * only ever records two headers. With this set, every detector that reasons from
+     * absence stands down; detectors that reason from what *is* present carry on.
+     *
+     * Adapters leave it unset. Set it yourself when replaying logs, reading from an
+     * analytics pipeline, or on any transport that filters headers before you see them.
+     */
+    partialHeaders?: boolean | undefined;
+    /** Opaque per-request extras an adapter or your own code attaches. */
+    extra?: Record<string, unknown> | undefined;
+}
+/** What the engine knows about the actor behind a request, accumulated over time. */
+export interface ActorSnapshot {
+    /** Stable key this actor is tracked under. See {@link BotHandlerConfig.actorKey}. */
+    key: string;
+    /** Requests seen from this actor inside the behavioural window. */
+    requests: number;
+    /** Distinct paths seen inside the window — breadth of crawl. */
+    distinctPaths: number;
+    /** First and last sighting, ms since epoch. */
+    firstSeen: number;
+    lastSeen: number;
+    /** Milliseconds since the previous request from this actor, or `undefined` if first. */
+    sinceLastMs?: number | undefined;
+    /** Assessments in the window that concluded `confirmed-bot`. */
+    priorConfirmations: number;
+    /**
+     * Challenges issued to this actor that were never solved.
+     *
+     * Outstanding rather than cumulative: solving one clears the count. See
+     * `MatchSpec.minUnsolvedChallenges` for the rule that reads it, and note that it is
+     * deliberately **not** evidence — a person who gives up on a challenge is a person,
+     * and what repeated abandonment means is a judgement about your traffic that only you
+     * can make.
+     */
+    unsolvedChallenges: number;
+    /** True when this actor holds a currently-valid human clearance token. */
+    cleared: boolean;
+}
+/** The engine's full, explainable output for one request. */
+export interface Assessment {
+    /** Random per-request id, safe to log and to echo in a response header. */
+    requestId: string;
+    verdict: Verdict;
+    botClass: BotClass;
+    /** Established identity when there is one, e.g. `"googlebot"`. */
+    identity?: string | undefined;
+    /** Suspicion, 0–100. Derived only from probabilistic evidence. */
+    score: number;
+    /** How much to trust the verdict, 0–1. Exactly 1 when `certain` is true. */
+    confidence: number;
+    /**
+     * True when at least one unrebutted `certain` evidence fired. This flag — not the
+     * score — is what gates terminal actions in the default policy.
+     */
+    certain: boolean;
+    /** Every bot-pointing observation, strongest first. */
+    evidence: Evidence[];
+    /** Every human-pointing observation. These rebut and dampen the score. */
+    humanEvidence: Evidence[];
+    actor: ActorSnapshot;
+    /**
+     * Set when detection was skipped rather than performed. `undefined` means every
+     * configured detector actually ran, which is what distinguishes "we looked and
+     * found nothing" from "we never looked" — a distinction that matters enormously
+     * when reading a dashboard.
+     */
+    bypass?: BypassReason | undefined;
+    /** Total time spent in detection, ms. */
+    durationMs: number;
+    /** Detectors that threw or timed out. Detection continues without them. */
+    failures: DetectorFailure[];
+    facts: RequestFacts;
+}
+/** Why an assessment skipped detection. */
+export type BypassReason = 
+/** The address matched the configured allowlist. */
+"allowlist"
+/** The path matched `ignorePaths`. */
+ | "ignored-path";
+export interface DetectorFailure {
+    detector: string;
+    reason: "error" | "timeout";
+    message: string;
+}
+/** JSON-serialisable value, for metadata and notification payloads. */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};