@osqd/bothandlerjs 0.3.0

package/dist/detectors/accept-signature.d.ts

@@ -0,0 +1,6 @@
+import type { Detector } from "./types.js";
+/**
+ * Reads the content-negotiation headers as a signature of the client.
+ *
+ * A browser asking for a page sends a long, specific `Accept` describing the
+ * document formats it renders. A scraper asks for `*/ export declare function acceptSignatureDetector(): Detector;

package/dist/detectors/browsing-coherence.d.ts

@@ -0,0 +1,44 @@
+import type { Detector } from "./types.js";
+/**
+ * Evidence that this request came out of a browsing session.
+ *
+ * Almost every detector in this library argues in one direction. That asymmetry is a
+ * problem the scoring model makes visible: a person reading forty pages of
+ * documentation from a university's shared address accumulates `rate-anomaly`,
+ * `cadence`, `crawl-breadth` and `ip-intelligence` and can cross the suspicion
+ * threshold without a single thing being wrong with their request. The engine
+ * discounts a bot score by whatever human evidence it has — `pBot × (1 − pHuman)` —
+ * and until now the only things that produced any were your own application's
+ * assertion, a clearance token, a TLS profile table most people do not maintain, and
+ * a page script most people do not embed. For an ordinary request from an ordinary
+ * browser, `pHuman` was zero.
+ *
+ * So this detector reads the properties that come from a client having *state and
+ * history* rather than from a client being well-formed:
+ *
+ * - **A cache to revalidate.** `If-None-Match` and `If-Modified-Since` mean this
+ *   client has been here before and kept what it was given. A stateless fetch loop
+ *   has nothing to revalidate against and asks for the resource fresh every time.
+ * - **A cookie jar.** Something set state on this client and the client sent it back.
+ * - **A user gesture.** `Sec-Fetch-User: ?1` is a forbidden header the browser sets
+ *   only when a *person* activated the navigation — a link click, a typed URL, a
+ *   bookmark. Page script cannot set it, and a driver navigating a page
+ *   programmatically does not produce it.
+ * - **A coherent modern fingerprint.** The Fetch Metadata group, the Client Hints and
+ *   the negotiation headers all present and agreeing with each other.
+ *
+ * **None of this is proof and none of it ever will be.** Every one of these
+ * properties is copyable: a scraper that keeps a cookie jar, replays an ETag and
+ * copies a header set produces all four. That is why the ceiling here is `moderate`,
+ * why the whole set shares one {@link Evidence.family} so it can never stack into a
+ * large discount, and why it can only ever *reduce* a suspicion score rather than
+ * establish a `human` verdict on its own. The only conclusive human evidence in this
+ * library comes from you — `isHuman`, or an operator clearance token — because you
+ * are the one party in the exchange whose word the client cannot forge.
+ *
+ * What it buys is the honest half of a two-sided argument: a request that shows the
+ * marks of a real session is less suspicious than an identical one that does not,
+ * and the population that benefits is precisely the one this library exists to
+ * protect.
+ */
+export declare function browsingCoherenceDetector(): Detector;

package/dist/detectors/cadence.d.ts

@@ -0,0 +1,28 @@
+import type { Detector } from "./types.js";
+export interface CadenceOptions {
+    /** Minimum gaps needed before the statistic means anything. Default 6. */
+    minSamples?: number;
+    /** Coefficient of variation at or below which the rhythm is machine-regular. Default 0.15. */
+    regularityThreshold?: number;
+    /** Ignore actors whose mean gap exceeds this, ms. Default 120000 (2 min). */
+    maxMeanIntervalMs?: number;
+}
+/**
+ * Is this actor's *rhythm* human?
+ *
+ * People generate ragged inter-arrival times. They read, scroll, get distracted, open
+ * three tabs at once, then nothing for four minutes. A loop calling `setInterval` or
+ * awaiting a fixed delay produces gaps clustered tightly around one value, and the
+ * coefficient of variation makes that visible in a single number.
+ *
+ * The check is on *regularity*, not speed, which is what makes it complementary to
+ * `rate-anomaly` — a slow, polite scraper deliberately pacing itself at one request
+ * every two seconds to stay under a rate limit is invisible to rate counting and
+ * extremely visible here.
+ *
+ * It stays `moderate` because a real page can produce regular traffic too: a polling
+ * XHR, a video player fetching segments, an SSE reconnect loop. Those are your own
+ * frontend, and the fix is to exclude their paths (see `ignorePaths` in the engine
+ * config) rather than to weaken the statistic.
+ */
+export declare function cadenceDetector(options?: CadenceOptions): Detector;

package/dist/detectors/clearance.d.ts

@@ -0,0 +1,25 @@
+import type { Detector } from "./types.js";
+import type { ChallengeService } from "../challenge/index.js";
+/**
+ * Reads a clearance token the client already holds.
+ *
+ * This is the library's only source of *human*-pointing evidence that is not a
+ * guess about headers, and it is worth being exact about what each level earns,
+ * because overstating any of them would undo the whole design.
+ *
+ * - **`operator`** is `certain`. Your application told us this is a person — an
+ *   authenticated session, a completed purchase, whatever your own bar is. We are
+ *   believing you, not deducing anything, which is the same reasoning that makes a
+ *   client's self-declaration `certain` in the other direction.
+ * - **`interaction`** is `strong`. A trusted input event was observed. Automation
+ *   driving a real browser can synthesise something close, so this is very good
+ *   evidence and not proof.
+ * - **`pow`** is only `moderate`, and this is the number people are most tempted to
+ *   inflate. A solved proof of work shows a JavaScript engine ran and CPU was spent.
+ *   A headless Chrome does both, happily and at scale. It raises the cost of a scrape
+ *   substantially; it says nothing whatsoever about whether a human is present.
+ *
+ * The token is bound to the actor and signed, so it cannot be lifted from one client
+ * and replayed by another under a different actor key.
+ */
+export declare function clearanceDetector(service: ChallengeService): Detector;

package/dist/detectors/client-hints.d.ts

@@ -0,0 +1,19 @@
+import type { Detector } from "./types.js";
+/**
+ * Cross-checks User-Agent Client Hints against the legacy User-Agent string.
+ *
+ * A real Chromium browser generates both from the same internal state, so they
+ * always agree. A client that rewrites one and forgets the other contradicts itself,
+ * and a contradiction is visible from a single request with no history, no state and
+ * no network call — which makes this one of the cheapest high-value checks there is.
+ *
+ * **Why none of this is `certain`, despite being a genuine contradiction.** The
+ * population that rewrites a User-Agent without touching Client Hints is not only
+ * scrapers: it is also every person running a UA-spoofing privacy extension, every
+ * enterprise browser with a rewritten UA policy, and every developer with device
+ * emulation open. Those are real people, and a `certain` tier that swept them up
+ * would make the word meaningless. So these observations score — sometimes heavily —
+ * and never block on their own. The lone exception is a hint that *self-declares*
+ * headless operation, which is a statement rather than an inference.
+ */
+export declare function clientHintsDetector(): Detector;

package/dist/detectors/client-signals.d.ts

@@ -0,0 +1,27 @@
+import type { Detector, DetectionContext } from "./types.js";
+export interface ClientSignalsOptions {
+    /**
+     * Where to find the signals on the request. Default: `facts.extra.clientSignals`.
+     *
+     * You are responsible for putting them there — typically by storing what your
+     * signal endpoint received against the session and attaching it in the adapter's
+     * `enrich` hook. The library does not invent a storage mechanism for you, because
+     * where per-session data lives is a decision only your application can make.
+     */
+    read?: (facts: DetectionContext["facts"]) => unknown;
+}
+/**
+ * Reads signals reported by the page script.
+ *
+ * The ceiling here is `moderate`, and it is a hard ceiling for a reason worth
+ * restating: every one of these values was produced by JavaScript running inside the
+ * client, which is the one place an adversary has complete control. A framework that
+ * wants `navigator.webdriver` to read `false` sets it to `false`, and everything this
+ * detector sees afterwards is whatever that framework decided to say.
+ *
+ * What it genuinely catches is automation that never bothered to hide — Selenium out
+ * of the box, a scripted Chrome someone pointed at your site this afternoon — which
+ * is a large share of real bot traffic. What it must never do is convince you that a
+ * clean report means a person.
+ */
+export declare function clientSignalsDetector(options?: ClientSignalsOptions): Detector;

package/dist/detectors/crawl-breadth.d.ts

@@ -0,0 +1,28 @@
+import type { Detector } from "./types.js";
+export interface CrawlBreadthOptions {
+    /**
+     * Distinct paths from one actor at or above which breadth is worth reporting.
+     * Default 30. Cannot exceed {@link MAX_TRACKED_PATHS}, which is where the count
+     * saturates; asking for more throws rather than never firing.
+     */
+    threshold?: number;
+    /** Fraction of requests that must be to a path not seen before. Default 0.85. */
+    noveltyRatio?: number;
+    /** Minimum requests before the ratio is meaningful. Default 20. */
+    minRequests?: number;
+}
+/**
+ * Is this actor *reading* the site or *enumerating* it?
+ *
+ * A person revisits. They land on an article, go back to the index, follow a related
+ * link, return to the article. Their ratio of distinct paths to total requests
+ * settles well below one. A crawler walking a sitemap almost never revisits, so its
+ * ratio sits near one and its distinct-path count climbs steadily.
+ *
+ * Worth being clear about what this cannot distinguish: a *welcome* crawler produces
+ * exactly this shape, and so does a person on a first visit to a documentation site
+ * clicking through the sidebar. It is a shape, not a motive — which is why it stays
+ * `weak` and why the interesting use is combining it with an actor that has already
+ * failed a header check.
+ */
+export declare function crawlBreadthDetector(options?: CrawlBreadthOptions): Detector;

package/dist/detectors/crawler-verification.d.ts

@@ -0,0 +1,39 @@
+import type { Detector } from "./types.js";
+export interface CrawlerVerificationOptions {
+    /**
+     * Treat an address with no PTR record as a forged claim. Default true.
+     *
+     * Every operator whose crawler this applies to publishes PTR records precisely so
+     * that servers can check them; a claimed Googlebot with no reverse DNS at all is
+     * not a configuration accident, it is the cheapest possible forgery. Set false if
+     * you have a resolver that cannot be trusted to distinguish NXDOMAIN from failure.
+     */
+    treatMissingPtrAsForgery?: boolean;
+    /**
+     * Also assert forgery for `ip-ranges` crawlers when ranges *are* configured and the
+     * client is outside them. Default true. Has no effect for a crawler whose ranges
+     * you have not supplied — an unverifiable claim stays unverified, never accused.
+     */
+    useConfiguredRanges?: boolean;
+}
+/**
+ * Confirms or refutes a claimed crawler identity against an authority outside the
+ * request.
+ *
+ * This is the only detector that can produce `verified-bot`, and the only one that
+ * can produce a `certain` `impersonator`. Both directions matter:
+ *
+ * - **Confirmed** — the operator's own DNS vouches for this address. Forging it needs
+ *   control of `googlebot.com`'s DNS, so a pass here is proof, and the default policy
+ *   uses it to *allow*: your SEO does not deserve to be collateral damage from a bot
+ *   rule.
+ * - **Refuted** — the client specifically claimed to be a named third party and the
+ *   claim is false. Note how narrow that is. A privacy extension rewriting a UA to a
+ *   generic browser string never lands here, because it never claims to be Googlebot.
+ *   Only a deliberate forgery of a *verifiable* identity does, which is why this one
+ *   is allowed to block.
+ *
+ * Anything short of a clear answer — a timeout, SERVFAIL, an unconfigured range list
+ * — yields nothing at all. Silence is never treated as an accusation.
+ */
+export declare function crawlerVerificationDetector(options?: CrawlerVerificationOptions): Detector;

package/dist/detectors/fetch-metadata.d.ts

@@ -0,0 +1,20 @@
+import type { Detector } from "./types.js";
+/**
+ * Checks the Fetch Metadata headers (`Sec-Fetch-Site`, `-Mode`, `-Dest`, `-User`).
+ *
+ * These are *forbidden* headers: page JavaScript cannot set or alter them, so in a
+ * real browser they are generated by the network stack from the actual context of
+ * the request. That makes them unusually hard to fake convincingly — a client
+ * assembling requests by hand either omits them or picks a combination the browser
+ * would never produce.
+ *
+ * Two failure modes are checked. **Absence** on an engine known to send them, over
+ * HTTPS, where they should be present. And **incoherence** — a `Sec-Fetch-Dest:
+ * document` that is not a navigation describes a request no browser makes.
+ *
+ * Neither is `certain`, for the same reason as elsewhere: a stripping proxy in front
+ * of your server produces the first, and an unusual-but-real client integration can
+ * produce the second. Together with a matching header set, though, they are among
+ * the sharpest probabilistic signals available.
+ */
+export declare function fetchMetadataDetector(): Detector;

package/dist/detectors/header-integrity.d.ts

@@ -0,0 +1,26 @@
+import type { Detector } from "./types.js";
+export interface HeaderIntegrityOptions {
+    /** Report a browser-claiming client that omits `Accept-Language`. Default true. */
+    checkAcceptLanguage?: boolean;
+}
+/**
+ * Does this request's header set match the client it claims to be?
+ *
+ * Browsers are extremely consistent about which headers they attach; HTTP libraries
+ * attach the minimum that gets a response. The gap between the two is one of the
+ * most reliable probabilistic signals available from a single request.
+ *
+ * Almost everything here is deliberately kept below `certain`, because headers pass
+ * through corporate proxies, CDNs, privacy extensions and mobile carrier
+ * transcoders, any of which will strip or rewrite them for an entirely real person.
+ *
+ * The exceptions are the three genuine protocol violations: a connection-specific
+ * header on HTTP/2 or HTTP/3, a message carrying both `Content-Length` and
+ * `Transfer-Encoding`, and a repeated `Host` or `Content-Length`. Each is a rule the
+ * specification requires a recipient to *enforce* rather than merely recommends, so a
+ * client that breaks it cannot get a response through any compliant proxy — and each
+ * is read from what the request *contains*, never from what it lacks. That second
+ * property is the one doing the work: an absence is indistinguishable from a facts
+ * source that dropped the header, and no absence in this file may reach `certain`.
+ */
+export declare function headerIntegrityDetector(options?: HeaderIntegrityOptions): Detector;

package/dist/detectors/header-order.d.ts

@@ -0,0 +1,27 @@
+import type { Detector } from "./types.js";
+export interface HeaderOrderOptions {
+    /** Include the order fingerprint in evidence metadata for cross-actor correlation. Default true. */
+    emitFingerprint?: boolean;
+}
+/**
+ * Reads the *order* in which headers arrived.
+ *
+ * Header order is a genuine fingerprint: a browser's network stack emits a fixed
+ * sequence that has nothing to do with what the page requested, and it is one of the
+ * few properties a scraper cannot fix by copying a User-Agent string. HTTP client
+ * libraries have their own, very different, and equally fixed orders.
+ *
+ * The reason this detector stays weak is structural rather than a lack of
+ * confidence: **anything between the client and this process may reorder headers.**
+ * HTTP/2 and HTTP/3 do not preserve a meaningful order at all, some CDNs normalise
+ * it, and some proxies rebuild the request wholesale. So it is checked only on
+ * HTTP/1.x, only when the transport actually exposed an order, and it contributes a
+ * nudge rather than a conclusion.
+ */
+export declare function headerOrderDetector(options?: HeaderOrderOptions): Detector;
+/**
+ * Stable fingerprint of a header order, for correlating one actor across rotating
+ * addresses. Exported because it is useful well outside this detector — an actor
+ * that changes IP every request but keeps the same order fingerprint is one actor.
+ */
+export declare function headerOrderFingerprint(order: readonly string[]): string;

package/dist/detectors/identity-rotation.d.ts

@@ -0,0 +1,34 @@
+import type { Detector } from "./types.js";
+export interface IdentityRotationOptions {
+    /**
+     * Distinct User-Agents from one actor at or above which rotation is reported.
+     * Default 3.
+     *
+     * An actor remembers at most {@link MAX_TRACKED_USER_AGENTS} of them, so a threshold
+     * above that can never be reached — an actor cycling through thirty spoofed strings
+     * still reports four. Asking for more throws rather than producing a detector that
+     * runs on every request and can never fire.
+     */
+    threshold?: number;
+    /** Minimum requests before the count is meaningful. Default 10. */
+    minRequests?: number;
+}
+/**
+ * One actor, several identities.
+ *
+ * A single client does not change its User-Agent mid-session. Something that does is
+ * cycling through a spoofing list, which is behaviour with no innocent
+ * interpretation *for a single client*.
+ *
+ * **This detector is off by default, and you should think before enabling it.** With
+ * the default IP-based actor key, "one actor" routinely means "one NAT gateway", and
+ * a corporate office, a university, a coffee shop or a mobile carrier's CGNAT pool
+ * legitimately presents hundreds of distinct browsers behind one address. Under that
+ * key this detector fires on exactly the busiest legitimate networks on the internet.
+ *
+ * It becomes genuinely valuable once your `actorKey` identifies something narrower
+ * than an address — a session cookie, an authenticated user id, or an IP combined
+ * with a TLS fingerprint. Then a rotating User-Agent really is one client lying, and
+ * it is worth a lot. Enable it there, and only there.
+ */
+export declare function identityRotationDetector(options?: IdentityRotationOptions): Detector;

package/dist/detectors/index.d.ts

@@ -0,0 +1,56 @@
+import type { Detector } from "./types.js";
+export type { DetectionContext, Detector, DetectorResult } from "./types.js";
+export { evidence, absenceIsMeaningful } from "./types.js";
+export { selfIdentifiedDetector } from "./self-identified.js";
+export type { SelfIdentifiedOptions } from "./self-identified.js";
+export { crawlerVerificationDetector } from "./crawler-verification.js";
+export type { CrawlerVerificationOptions } from "./crawler-verification.js";
+export { headerIntegrityDetector } from "./header-integrity.js";
+export type { HeaderIntegrityOptions } from "./header-integrity.js";
+export { clientHintsDetector } from "./client-hints.js";
+export { fetchMetadataDetector } from "./fetch-metadata.js";
+export { acceptSignatureDetector } from "./accept-signature.js";
+export { headerOrderDetector, headerOrderFingerprint } from "./header-order.js";
+export type { HeaderOrderOptions } from "./header-order.js";
+export { rateAnomalyDetector } from "./rate-anomaly.js";
+export type { RateAnomalyOptions } from "./rate-anomaly.js";
+export { cadenceDetector } from "./cadence.js";
+export type { CadenceOptions } from "./cadence.js";
+export { crawlBreadthDetector } from "./crawl-breadth.js";
+export type { CrawlBreadthOptions } from "./crawl-breadth.js";
+export { sessionIntegrityDetector } from "./session-integrity.js";
+export type { SessionIntegrityOptions } from "./session-integrity.js";
+export { identityRotationDetector } from "./identity-rotation.js";
+export type { IdentityRotationOptions } from "./identity-rotation.js";
+export { TRAP_FIELD_SOURCE, trapDetector, renderTrapLink, renderTrapField, trapRobotsEntries, DEFAULT_TRAP_PATHS } from "./trap.js";
+export type { TrapOptions, TrapLinkOptions } from "./trap.js";
+export { ipIntelligenceDetector } from "./ip-intelligence.js";
+export type { IpIntelligenceOptions } from "./ip-intelligence.js";
+export { tlsFingerprintDetector } from "./tls-fingerprint.js";
+export type { TlsFingerprintOptions, FingerprintProfile } from "./tls-fingerprint.js";
+export { clearanceDetector } from "./clearance.js";
+export { uaCoherenceDetector } from "./ua-coherence.js";
+export { probeSignatureDetector } from "./probe-signature.js";
+export type { ProbeSignatureOptions } from "./probe-signature.js";
+export { browsingCoherenceDetector } from "./browsing-coherence.js";
+export { clientSignalsDetector } from "./client-signals.js";
+export type { ClientSignalsOptions } from "./client-signals.js";
+export { BOT_SIGNATURES, BENIGN_CATEGORIES, compileSignatures, indexSignatures } from "./known-bots.js";
+export type { BotSignature, BotCategory, Verification } from "./known-bots.js";
+/**
+ * The detector set installed when you configure none.
+ *
+ * Two are missing on purpose, and both omissions are about false positives rather
+ * than about cost:
+ *
+ * - `identityRotationDetector` fires on any address that fronts several browsers,
+ *   which describes every corporate NAT and mobile carrier on the internet. It is
+ *   valuable, but only once your `actorKey` is narrower than an IP.
+ * - `tlsFingerprintDetector` needs a fingerprint from your edge and a profile table
+ *   you maintain. With neither it is inert; with a stale table it misfires on anyone
+ *   running a browser newer than your data.
+ *
+ * `clearanceDetector` is not here either, because it needs the challenge service —
+ * the engine adds it automatically once `challenge.secrets` is configured.
+ */
+export declare function defaultDetectors(): Detector[];

package/dist/detectors/ip-intelligence.d.ts

@@ -0,0 +1,30 @@
+import type { Detector } from "./types.js";
+export interface IpIntelligenceOptions {
+    /** Weight for a datacenter-range match. Default 0.3 (`moderate`). */
+    datacenterWeight?: number;
+}
+/**
+ * What do we know about where this request came from?
+ *
+ * Two range sets are consulted, and they are treated very differently.
+ *
+ * **`denylist`** is `certain`, and the justification is not technical. You configured
+ * it. The library is not inferring anything; it is carrying out an instruction you
+ * gave about addresses you have decided about. Certainty here means "this is a
+ * decision, not a guess" — and it means a bad entry in your denylist blocks real
+ * people, which is exactly why the range is required to be explicit rather than
+ * inherited from a feed by default.
+ *
+ * **`datacenter`** is `moderate` and always will be. Hosting-provider address space
+ * is where scrapers live, and it is *also* where every consumer VPN, every corporate
+ * egress gateway, every Tor exit, every privacy relay like iCloud Private Relay, and
+ * a growing share of mobile traffic lives. Treating "came from AWS" as proof of
+ * automation blocks a meaningful slice of ordinary users, disproportionately the
+ * privacy-conscious ones. As corroboration alongside a header failure it is
+ * genuinely useful; alone it is close to worthless.
+ *
+ * No range data ships with this library. Address-to-operator mappings go stale
+ * within weeks, and a stale mapping is a false positive with a long half-life —
+ * supply your own, from a source you refresh and can audit.
+ */
+export declare function ipIntelligenceDetector(options?: IpIntelligenceOptions): Detector;

package/dist/detectors/known-bots.d.ts

@@ -0,0 +1,94 @@
+import { MultiPatternMatcher } from "../internal/matcher.js";
+/**
+ * The known-bot signature database.
+ *
+ * Two things live here, and it is worth being precise about the difference.
+ *
+ * A **signature** matches a literal token in a User-Agent. That is a *claim* the
+ * client makes about itself, nothing more — anyone can send `Googlebot/2.1`. A claim
+ * is useful for two opposite reasons: an honest bot's claim tells us what it is, and
+ * a dishonest one gives us something to disprove.
+ *
+ * A **verification** is how that claim gets checked against an authority outside the
+ * request. Only the pairing of the two produces a `certain` verdict — either
+ * `verified-bot` (claim confirmed) or `impersonator` (claim disproved). A signature
+ * with no verification can never do better than `declared-bot`.
+ */
+export type BotCategory = "search" | "ai" | "seo" | "social" | "monitoring" | "archive" | "feed" | "security" | "advertising" | "library" | "headless"
+/** A real browser engine embedded in a desktop application, with a person driving it. */
+ | "embedded" | "other";
+/** Every category, for anything that has to enumerate them — a rule editor, a report. */
+export declare const BOT_CATEGORIES: readonly BotCategory[];
+/**
+ * How a claimed identity is checked.
+ *
+ * - `fcrdns` — forward-confirmed reverse DNS. Reverse-resolve the client IP, require
+ *   the name to sit under one of `domains`, then forward-resolve that name and
+ *   require the original IP back. Forging this requires control of the operator's
+ *   DNS, which is the property that makes it `certain` in both directions.
+ * - `ip-ranges` — the operator publishes IP ranges but sets no usable PTR records.
+ *   Verifiable only if you supply the ranges (see `crawlerRanges` in the config);
+ *   the library will not fetch them for you, because a detector that makes an
+ *   outbound HTTP request on a schedule is a dependency you should opt into
+ *   knowingly.
+ * - `none` — no published mechanism. The claim is unfalsifiable, so we neither
+ *   confirm nor accuse.
+ */
+export type Verification = {
+    kind: "fcrdns";
+    domains: readonly string[];
+} | {
+    kind: "ip-ranges";
+    publishedAt?: string;
+} | {
+    kind: "none";
+};
+export interface BotSignature {
+    /** Stable id, used in rules, logs and metrics. */
+    id: string;
+    name: string;
+    /** Lowercase literal tokens; a match on any one identifies this bot. */
+    tokens: readonly string[];
+    category: BotCategory;
+    verification: Verification;
+    /**
+     * Whether this client is generally *benign* — something most sites want to keep
+     * serving. Search and social preview crawlers are; scrapers and scanners are not.
+     * Drives the default policy's allow path, never a block.
+     */
+    benign: boolean;
+    /**
+     * Whether matching this signature is *conclusive* evidence of automation. Default
+     * true.
+     *
+     * Set it false when the token can legitimately appear on a request a person made.
+     * The motivating case is Electron: the UA is emitted by VS Code's Simple Browser,
+     * Slack, Discord and Postman, which are real Chromium instances with a human
+     * driving them. A signature match is only allowed into the `certain` tier when the
+     * claim "no honest client sends this" actually holds, and for embedded webviews it
+     * plainly does not.
+     */
+    conclusive?: boolean;
+    /** Why this signature is not conclusive. Surfaced in the evidence summary. */
+    caveat?: string;
+    /**
+     * The product token to name in a `User-agent:` line in `robots.txt`.
+     *
+     * Defaults to the first match token. Worth setting where the canonical spelling
+     * differs from the token we match on — `robots.txt` matching is case-insensitive,
+     * so this is about a file a person will read, not about correctness.
+     */
+    robotsAgent?: string;
+    docs?: string;
+}
+/** Every built-in signature, in one array. Extend it via `extraSignatures` rather than editing. */
+export declare const BOT_SIGNATURES: readonly BotSignature[];
+/**
+ * Compiles signatures into a single-pass matcher. Build this once per engine, never
+ * per request — construction is O(total pattern length) and matching is O(input).
+ */
+export declare function compileSignatures(signatures?: readonly BotSignature[]): MultiPatternMatcher<BotSignature>;
+/** Index by id, so rules can name a bot (`"googlebot"`) and get its metadata back. */
+export declare function indexSignatures(signatures?: readonly BotSignature[]): ReadonlyMap<string, BotSignature>;
+/** Categories whose members are, by default, worth serving. Used by `allowBenignBots`. */
+export declare const BENIGN_CATEGORIES: ReadonlySet<BotCategory>;

package/dist/detectors/probe-signature.d.ts

@@ -0,0 +1,50 @@
+import type { Detector } from "./types.js";
+/**
+ * What is this request *asking for*?
+ *
+ * Every other detector here reads the client. This one reads the request target, and
+ * it exists because of a gap the rest of the library cannot close: the scanner that
+ * does not announce itself. `self-identified` catches sqlmap and Nikto because they
+ * say so, and a great deal of hostile traffic does say so. The rest arrives wearing a
+ * copied Chrome User-Agent, and from the headers alone it is indistinguishable from a
+ * person — until you look at what it asked for, which is `/.env`, then
+ * `/.git/config`, then `/vendor/phpunit/phpunit/src/Util/PHP/eval-stdin.php`.
+ *
+ * Those paths are not obscure corners of a site. They are entries in a wordlist. No
+ * link points at them, no menu leads to them, and no person types them — the traffic
+ * that requests them is running a list against every address it can reach.
+ *
+ * **Why this stops at `strong` and never reaches `certain`.** The library's rule is
+ * that `certain` evidence must admit no benign explanation, and a *request target*
+ * always admits one: a URL is client-supplied text, and the client supplying it might
+ * be a security engineer testing their own site from a laptop, a researcher with a
+ * bug-bounty scope, or a monitoring check somebody wrote at three in the morning.
+ * Those are people, and the correct response to them is a challenge, not a closed
+ * door. A trap path is different — it is unreachable *by construction*, which is
+ * exactly the property a wordlist entry lacks.
+ *
+ * **What it does not do.** It reads one request at a time. A scanner walking a
+ * wordlist produces one of these observations per request rather than an escalating
+ * series, because nothing here remembers that the same actor asked for `/.env` a
+ * moment ago — the detectors that watch an actor over time are `rate-anomaly`,
+ * `cadence` and `crawl-breadth`, and enumeration shows up there. Keeping this one
+ * stateless is what lets it run unchanged over a log file in `replay`.
+ *
+ * **The one thing to configure.** The `platform` tier below is a list of admin and
+ * login paths that are probes on most sites and are the *front door* on the sites
+ * that run those platforms. If you run WordPress, `/wp-login.php` is where your
+ * authors sign in, and this detector will report each of them as a probe. Add such
+ * paths to `ignore`, or to the engine's `ignorePaths`, before turning any of this into
+ * a rule. The tier is capped at `moderate` precisely so that forgetting costs a
+ * tag rather than a door.
+ */
+export interface ProbeSignatureOptions {
+    /**
+     * Paths this site genuinely serves, exempted from the platform tier. Matched as
+     * prefixes, so `/wp-admin` covers everything beneath it.
+     */
+    ignore?: readonly string[];
+    /** Additional exact paths or prefixes to treat as exploit-tier probes. */
+    extraPaths?: readonly string[];
+}
+export declare function probeSignatureDetector(options?: ProbeSignatureOptions): Detector;

package/dist/detectors/rate-anomaly.d.ts

@@ -0,0 +1,36 @@
+import type { Detector } from "./types.js";
+export interface RateAnomalyOptions {
+    /** Window over which arrivals are counted, ms. Default 10000. */
+    windowMs?: number;
+    /** Requests in the window above which the rate is worth noting. Default 20. */
+    threshold?: number;
+    /**
+     * Requests in the window above which the rate is well beyond human. Default 30.
+     *
+     * Both defaults sit under the per-actor timestamp ring's capacity, because the
+     * count saturates there — a threshold above it could never be reached, which is a
+     * detector that silently never fires. If you raise these, raise them knowing the
+     * ceiling, and reach for the `rate-limit` action instead when you need real numbers.
+     */
+    hardThreshold?: number;
+}
+/**
+ * How fast is this actor going?
+ *
+ * Rate is the signal people reach for first and trust the most, and it deserves the
+ * least trust of anything in this library. The reason is that the *actor* behind a
+ * high rate is frequently not one client: a corporate NAT, a mobile carrier's CGNAT
+ * pool, a university, a VPN exit and a shared office all present hundreds of real
+ * people as one address. Blocking on rate blocks all of them.
+ *
+ * So this detector reports and never concludes. Its output tops out at `moderate`,
+ * which under the default policy cannot reach a terminal action no matter how
+ * extreme the number gets. What high rate is genuinely good for is *corroborating* —
+ * a client that already looks like a library and is also pulling 300 requests a
+ * minute is a different proposition from either fact alone.
+ *
+ * If you want rate to actually stop traffic, that is what rate *limiting* is for,
+ * and it belongs in the action layer where it applies to everyone equally and
+ * recovers on its own. See the `rate-limit` action.
+ */
+export declare function rateAnomalyDetector(options?: RateAnomalyOptions): Detector;

package/dist/detectors/self-identified.d.ts

@@ -0,0 +1,33 @@
+import type { Detector } from "./types.js";
+import type { BotCategory } from "./known-bots.js";
+export interface SelfIdentifiedOptions {
+    /**
+     * Categories to report. Removing one does not make its traffic invisible — the
+     * behavioural detectors still see it — it only stops this detector naming it.
+     */
+    categories?: readonly BotCategory[];
+}
+/**
+ * The client told us what it is.
+ *
+ * This detector is the backbone of the `certain` tier, and the reason is a point
+ * about responsibility rather than about technology. When a request arrives saying
+ * `python-requests/2.31.0` or `Googlebot/2.1`, we are not *inferring* anything. We
+ * are taking the client at its word. If that word is a lie, the misclassification is
+ * the client's doing, not a failure of detection — and no honest client is ever
+ * harmed by being believed.
+ *
+ * That is why a self-declaration can safely gate a terminal action while a much
+ * "smarter" behavioural inference cannot. The behavioural inference can be wrong
+ * about someone who never made any claim at all.
+ *
+ * Two shapes qualify:
+ *
+ * - A **known signature** — a token from {@link BOT_SIGNATURES}. Library and headless
+ *   tokens are conclusive on their own: no browser has ever sent `curl/8.4.0`.
+ * - An **unrecognised but self-announcing** UA — contains a word like `bot` or
+ *   `crawler` *and* publishes a contact URL or email, the long-standing convention
+ *   for well-behaved crawlers. Either half alone is only suggestive; together they
+ *   are a declaration.
+ */
+export declare function selfIdentifiedDetector(options?: SelfIdentifiedOptions): Detector;