@osqd/bothandlerjs 0.3.0

package/dist/internal/async.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runs `work` and resolves to `fallback` if it takes longer than `ms`.
+ *
+ * Detection runs inline on the request path, so an unbounded await is an
+ * availability bug: a slow reverse-DNS lookup or a stalled Redis round-trip would
+ * hold the response open. Every I/O-bound detector is wrapped in this, and a
+ * timeout degrades that one detector rather than the request.
+ *
+ * The underlying promise is not cancelled (JS has no such mechanism) but its result
+ * is discarded and its rejection swallowed, so a late failure cannot surface as an
+ * unhandled rejection.
+ */
+export declare function withTimeout<T>(work: Promise<T>, ms: number, fallback: T): Promise<T>;
+/** `Promise.allSettled` semantics without allocating a settled-result wrapper per item. */
+export declare function settleAll(work: Iterable<Promise<void>>): Promise<void>;
+export declare function isPromise(value: unknown): value is Promise<unknown>;

package/dist/internal/clock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Injectable time. Every stateful detector reads `now()` from here rather than
+ * calling `Date.now()`, which is what makes rate, cadence and expiry logic testable
+ * without sleeping and without flaky wall-clock assumptions.
+ */
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+/** Test double: time only advances when you say so. */
+export declare class ManualClock implements Clock {
+    private current;
+    constructor(current?: number);
+    now(): number;
+    advance(ms: number): void;
+    set(ms: number): void;
+}

package/dist/internal/crypto.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Signing and comparison primitives for clearance tokens.
+ *
+ * Two rules govern everything in this file. Tokens are signed, never encrypted —
+ * their contents are readable by the client and must contain nothing secret. And
+ * every comparison of a secret-derived value goes through {@link constantTimeEqual},
+ * because a token verifier is exactly the kind of oracle a timing attack likes.
+ */
+export declare function base64UrlEncode(input: Uint8Array | string): string;
+export declare function base64UrlDecode(input: string): Buffer;
+/** HMAC-SHA256, returned as base64url. */
+export declare function sign(payload: string, secret: string): string;
+/**
+ * Constant-time string comparison. Falls back to a `false` return on
+ * length mismatch — the length of a signature is not a secret, so leaking it is
+ * fine, and `timingSafeEqual` throws on unequal lengths.
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;
+/** URL-safe random id. 16 bytes is 128 bits — collision-free for request ids and nonces. */
+export declare function randomId(bytes?: number): string;
+/**
+ * SHA-256 truncated to 128 bits, base64url. Used to derive stable, non-reversible
+ * keys from values we do not want to store in the clear (IP-based actor keys when
+ * `hashActorKeys` is on, header-order fingerprints).
+ */
+export declare function shortHash(value: string, secret?: string): string;

package/dist/internal/dns.d.ts

@@ -0,0 +1,100 @@
+/**
+ * DNS access for crawler identity verification.
+ *
+ * The distinction this module exists to preserve is between *disproof* and *no
+ * answer*, and it is the load-bearing detail of the whole no-false-positive design.
+ *
+ * A reverse lookup that succeeds and returns `crawl-66-249-66-1.googlebot.com` for a
+ * client claiming to be Googlebot **confirms** the claim. One that succeeds and
+ * returns `some-vps.example.net` **disproves** it. One that times out, hits SERVFAIL,
+ * or finds no resolver at all proves nothing whatsoever — and must never be allowed
+ * to look like disproof, because "our resolver was briefly unhappy" would otherwise
+ * become "we blocked Googlebot".
+ */
+/** The subset of `node:dns/promises` this library uses. Inject your own for tests or a custom resolver. */
+export interface DnsResolver {
+    /** PTR names for an address. Rejects on NXDOMAIN. */
+    reverse(ip: string): Promise<string[]>;
+    /** A and AAAA records for a name. Rejects on NXDOMAIN. */
+    resolveAddresses(hostname: string): Promise<string[]>;
+}
+export type VerificationOutcome = 
+/** DNS confirmed the claimed identity. Deterministic. */
+{
+    status: "verified";
+    hostname: string;
+}
+/**
+ * DNS answered, and the answer contradicts the claim. Deterministic.
+ *
+ * `cause` is what callers should branch on. One of them offers an option to stop
+ * treating a missing PTR as forgery, and it used to implement that by searching
+ * `reason` for the words "no PTR record" — so rewording a human-readable sentence
+ * silently turned an operator's explicit opt-out into a no-op.
+ */
+ | {
+    status: "contradicted";
+    cause: "no-ptr" | "wrong-domain" | "no-forward-record" | "address-mismatch";
+    reason: string;
+    hostname?: string | undefined;
+}
+/** No usable answer. Proves nothing; produces no evidence in either direction. */
+ | {
+    status: "indeterminate";
+    reason: string;
+};
+/** Node-backed resolver. Imported lazily so the library stays loadable on edge runtimes. */
+export declare function nodeDnsResolver(timeoutMs?: number): DnsResolver;
+export declare class DnsTimeoutError extends Error {
+    readonly name = "DnsTimeoutError";
+    /**
+     * Carried so the timeout reads as a timeout everywhere a DNS error's code is
+     * inspected — the cache's replay, and the reason string an operator sees when a
+     * crawler could not be verified. Deliberately not one of {@link DEFINITIVE_ABSENCE}:
+     * a lookup that ran out of time has said nothing about whether the name exists.
+     */
+    readonly code = "ETIMEDOUT";
+    constructor();
+}
+/**
+ * Classifies a DNS rejection. `true` means the negative answer is authoritative and
+ * may be treated as a contradiction; `false` means we simply did not get an answer.
+ */
+export declare function isDefinitiveAbsence(error: unknown): boolean;
+/** True when `hostname` is `domain` itself or a subdomain of it. Never a substring match. */
+export declare function isUnderDomain(hostname: string, domain: string): boolean;
+/**
+ * Forward-confirmed reverse DNS.
+ *
+ * 1. PTR the client IP.
+ * 2. Require at least one name under one of `domains` — a *suffix* match on label
+ *    boundaries, so `googlebot.com.evil.net` does not pass.
+ * 3. Forward-resolve that name and require the original IP back, which is what stops
+ *    anyone who controls a PTR record for their own address from claiming to be
+ *    Googlebot.
+ */
+export declare function forwardConfirmedReverseDns(resolver: DnsResolver, ip: string, domains: readonly string[]): Promise<VerificationOutcome>;
+export interface CachingResolverOptions {
+    /** How long a successful answer is reused, ms. Default 3600000 (1h). */
+    ttlMs?: number;
+    /**
+     * How long a failure is remembered, ms. Default 60000.
+     *
+     * Much shorter than the success TTL on purpose. Caching a failure for an hour would
+     * turn a one-minute resolver blip into an hour of unverified Googlebot, and the
+     * cost of retrying is one lookup.
+     */
+    errorTtlMs?: number;
+    /** Maximum names and addresses cached. Default 10000. */
+    max?: number;
+}
+/**
+ * Memoises lookups.
+ *
+ * Verification would otherwise resolve DNS twice for *every* request from a crawler,
+ * which for a site Googlebot likes is thousands of lookups an hour for an answer that
+ * changes approximately never. Caching here rather than inside the detector keeps it
+ * at the layer where the data is genuinely cacheable, and lets you swap the whole
+ * resolver out in tests without losing it.
+ */
+export declare function cachingResolver(inner: DnsResolver, options?: CachingResolverOptions): DnsResolver;

package/dist/internal/emitter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal typed event emitter.
+ *
+ * Not `node:events`: listeners here are isolated so that one badly-written
+ * subscriber cannot take down request handling. A throwing listener is reported to
+ * `onError` and the remaining listeners still run — the same isolation guarantee the
+ * detector pipeline gives.
+ */
+export type Listener<T> = (payload: T) => void;
+export declare class Emitter<Events extends Record<string, unknown>> {
+    private readonly onError;
+    private readonly listeners;
+    constructor(onError?: (error: unknown, event: string) => void);
+    on<K extends keyof Events & string>(event: K, listener: Listener<Events[K]>): () => void;
+    off<K extends keyof Events & string>(event: K, listener: Listener<Events[K]>): void;
+    emit<K extends keyof Events & string>(event: K, payload: Events[K]): void;
+    removeAll(): void;
+}

package/dist/internal/http.d.ts

@@ -0,0 +1,22 @@
+/** Cookie parsing and serialisation, plus small header helpers. No dependencies. */
+/**
+ * Parses a `Cookie` header into a null-prototype bag.
+ *
+ * Null-prototype matters: a request carrying `__proto__=x` would otherwise hit the
+ * prototype setter on a plain object and vanish, and any later `cookies.constructor`
+ * lookup would find `Object`'s rather than `undefined`. Neither is a vulnerability by
+ * itself; both are the kind of surprise that becomes one.
+ */
+export declare function parseCookies(header: string | undefined): Record<string, string>;
+export interface CookieOptions {
+    maxAgeMs?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "Lax" | "Strict" | "None";
+}
+/** Builds a `Set-Cookie` value. Rejects names and values that would let a caller inject attributes. */
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+/** Joins multi-value headers the way the rest of the library expects to see them. */
+export declare function joinHeaderValue(value: string | string[] | undefined): string | undefined;

package/dist/internal/ip.d.ts

@@ -0,0 +1,73 @@
+/**
+ * IP parsing, normalisation and CIDR matching, with no dependencies.
+ *
+ * Everything works on raw byte arrays rather than strings, because string
+ * comparison of IPs is a classic source of bypasses: `::ffff:127.0.0.1`,
+ * `0177.0.0.1` and `127.0.0.001` are all the same host to the network stack but
+ * three different strings to a naive allowlist.
+ */
+/** An IP as bytes: 4 for IPv4, 16 for IPv6. IPv4-mapped IPv6 is folded to 4. */
+export type IpBytes = Uint8Array;
+/**
+ * Parses an IPv4 or IPv6 literal into bytes, or `null` if it is not a valid
+ * address. Deliberately strict: no octal, no hex, no shorthand octets, no zone
+ * ids. Anything ambiguous is rejected rather than guessed at.
+ */
+export declare function parseIp(value: string): IpBytes | null;
+/** Canonical string form, so the same host always produces the same actor key. */
+export declare function formatIp(bytes: IpBytes): string;
+/** Normalises any accepted spelling of an address to its canonical form. Returns `null` if unparseable. */
+export declare function normalizeIp(value: string): string | null;
+export interface Cidr {
+    readonly bytes: IpBytes;
+    readonly prefix: number;
+    readonly source: string;
+}
+/** Parses `"10.0.0.0/8"`, `"2001:db8::/32"`, or a bare address (treated as a /32 or /128). */
+export declare function parseCidr(value: string): Cidr | null;
+/** True when `ip` falls inside `cidr`. Address families never match across each other. */
+export declare function cidrContains(cidr: Cidr, ip: IpBytes): boolean;
+/**
+ * A compiled set of CIDR ranges. Building it once and reusing it keeps the hot
+ * path free of string parsing — matching is a handful of byte comparisons, and stays
+ * that way as the list grows into the thousands.
+ */
+export declare class IpRangeSet {
+    private readonly v4;
+    private readonly v6;
+    private count;
+    /**
+     * Every range that parsed, in the order it was added.
+     *
+     * Kept as plain text beside the index rather than reconstructed from it. The index
+     * is shaped for lookups — bucketed by leading byte, prefix-split — and walking it
+     * back into a list would be both slower and, for anything that wants to *show* the
+     * set, wrong: what an operator recognises is the string they wrote, not a normalised
+     * form of it. These sets are configuration-sized, so the array costs nothing.
+     */
+    private readonly sources;
+    /** Ranges that failed to parse, surfaced so a typo in config is loud rather than silent. */
+    readonly invalid: string[];
+    constructor(ranges?: Iterable<string>);
+    add(range: string): void;
+    get size(): number;
+    /** The ranges in this set, as written, oldest first. What a reader can act on. */
+    entries(): readonly string[];
+    /**
+     * Returns the matching range's original text, or `undefined`. Useful for explaining
+     * a decision. When several ranges match, the one added first wins, so the
+     * explanation does not depend on the index's internal layout.
+     */
+    match(ip: string | IpBytes): string | undefined;
+    contains(ip: string | IpBytes): boolean;
+}
+/** IANA special-purpose ranges: loopback, private, link-local, CGNAT, documentation. */
+export declare const SPECIAL_USE_RANGES: readonly ["0.0.0.0/8", "10.0.0.0/8", "100.64.0.0/10", "127.0.0.0/8", "169.254.0.0/16", "172.16.0.0/12", "192.0.0.0/24", "192.0.2.0/24", "192.168.0.0/16", "198.18.0.0/15", "198.51.100.0/24", "203.0.113.0/24", "224.0.0.0/4", "240.0.0.0/4", "::1/128", "fc00::/7", "fe80::/10", "2001:db8::/32"];
+/** True for loopback/private/link-local/documentation addresses — never public clients. */
+export declare function isSpecialUse(ip: string): boolean;
+/**
+ * Masks an address to a coarse network for rate accounting: /24 for IPv4, /64 for
+ * IPv6. IPv6 clients routinely get a whole /64 to themselves and rotate the host
+ * bits freely, so per-address counting is trivially defeated there.
+ */
+export declare function networkKey(ip: string): string;

package/dist/internal/lru.d.ts

@@ -0,0 +1,34 @@
+import type { Clock } from "./clock.js";
+/**
+ * Bounded map with per-entry TTL and least-recently-used eviction.
+ *
+ * The bound is a security property, not a nicety. Every per-actor structure in this
+ * library is keyed by something an attacker controls (an IP, a fingerprint), so an
+ * unbounded map is a remote OOM waiting to happen. Capacity is enforced on every
+ * insert; expiry is checked lazily on read plus a bounded sweep on insert, so a
+ * quiet process never keeps a timer alive.
+ */
+export declare class TtlLru<V> {
+    private readonly capacity;
+    private readonly ttlMs;
+    private readonly clock;
+    private readonly entries;
+    constructor(capacity: number, ttlMs: number, clock?: Clock);
+    get size(): number;
+    /**
+     * Every live value, most recently used last — the Map's own insertion order, which
+     * `get` and `set` maintain.
+     *
+     * Expired entries are skipped rather than deleted, because this is a read: a caller
+     * listing what is in the cache should not be the thing that evicts from it, and the
+     * next `get` or `set` on that key will clear it anyway.
+     */
+    values(): V[];
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    /** Reads, or creates via `factory` and stores. The common read-modify-write path. */
+    getOrCreate(key: string, factory: () => V): V;
+    delete(key: string): void;
+    clear(): void;
+    private evict;
+}

package/dist/internal/matcher.d.ts

@@ -0,0 +1,41 @@
+export declare class MultiPatternMatcher<T> {
+    /** Transition tables, one Map per node, indexed by character code. */
+    private readonly transitions;
+    private readonly fail;
+    /** Payloads that end at each node, plus everything reachable via fail links. */
+    private readonly outputs;
+    /** Longest pattern registered — lets callers skip inputs that cannot match. */
+    readonly maxPatternLength: number;
+    readonly patternCount: number;
+    /**
+     * Flat transition table for the root node over 7-bit ASCII.
+     *
+     * A scan of text that matches nothing — every request from a real browser — sits at
+     * the root for its entire length, so the root's transition lookup happens once per
+     * character and dominates everything else. A `Map.get` there costs a hash and a
+     * bucket probe; an array index costs neither. 512 bytes, built once.
+     *
+     * Patterns are overwhelmingly lowercase ASCII. The rare one that is not — a crawler
+     * that names itself in Cyrillic or Han — gets a root transition above 127, which the
+     * flat table cannot hold; those live in {@link rootWide}, left undefined when there
+     * are none so the common case pays one `undefined` check.
+     */
+    private readonly rootAscii;
+    private readonly rootWide;
+    constructor(patterns: Iterable<readonly [pattern: string, payload: T]>);
+    /** Root-node transition. Kept separate so the hot loop reads an array, not a Map. */
+    private fromRoot;
+    private buildFailureLinks;
+    /**
+     * Every distinct payload whose pattern occurs in `haystack`. The input must
+     * already be lowercased — casing is normalised by the caller, once, rather than
+     * per pattern.
+     *
+     * The no-match case allocates nothing and returns a shared frozen array. That is
+     * the case for every request from a person, so it is the one worth making free.
+     */
+    matchAll(haystack: string): readonly T[];
+    /** Cheap existence check that stops at the first hit. */
+    matchFirst(haystack: string): T | undefined;
+    has(haystack: string): boolean;
+}

package/dist/internal/pattern.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Path patterns supplied by an operator, made safe to reuse.
+ *
+ * `RegExp.test` is stateful when the pattern carries `g` or `y`: it resumes from
+ * `lastIndex` and resets only on a failed match, so the same pattern tested against
+ * the same string answers `true`, `false`, `true`, `false`. Nothing here matches a
+ * path more than once, so neither flag can express anything anyone wanted — but both
+ * turn a rule into a coin flip, and the symptom (a bot blocked, served, blocked,
+ * served) reads as a bug anywhere except in the flag that caused it.
+ */
+/** The pattern with `g` and `y` removed. Returns strings and stateless regexes unchanged. */
+export declare function statelessPattern<T extends string | RegExp>(pattern: T): T;
+/** True when `path` matches: strings are a prefix test, regexes are tested as written. */
+export declare function pathMatches(patterns: readonly (string | RegExp)[], path: string): boolean;

package/dist/internal/ua.d.ts

@@ -0,0 +1,92 @@
+/**
+ * User-Agent shape analysis.
+ *
+ * This is deliberately *not* a full UA-parsing library. Naming the exact browser and
+ * version is a losing game — the string is client-controlled, frozen by vendors, and
+ * lies constantly. What we extract instead is **structure**: does this string have
+ * the shape a real browser emits, and do its parts agree with each other?
+ *
+ * Structure is far harder to fake convincingly than a product token, and — more
+ * importantly — a structural contradiction is *deterministic* evidence in a way that
+ * "the string says curl" never is.
+ */
+export type UaShape = "browser-like" | "declared-bot" | "library" | "empty" | "malformed" | "other";
+export interface ParsedUserAgent {
+    raw: string;
+    lower: string;
+    shape: UaShape;
+    /** Product token we believe identifies the client, e.g. `"chrome"`, `"safari"`. */
+    browser?: string | undefined;
+    /** Major version as an integer, when one is present and plausible. */
+    majorVersion?: number | undefined;
+    /** Rendering engine token: `"blink"`, `"gecko"`, `"webkit"`. */
+    engine?: string | undefined;
+    /** Normalised OS family: `"windows"`, `"macos"`, `"linux"`, `"android"`, `"ios"`. */
+    os?: string | undefined;
+    /**
+     * Every `Product/Version` pair, in order.
+     *
+     * Computed on first access and cached. Tokenising the whole string costs more than
+     * every other part of parsing put together, and a mainstream browser User-Agent
+     * never needs it — only unrecognised and library-shaped strings do. Reading this
+     * property is cheap; reading it on a hot path for a browser is not.
+     */
+    readonly products: ReadonlyArray<UserAgentProduct>;
+    /** True when the string names a URL or an email address anywhere. */
+    declaresContact: boolean;
+    /**
+     * True when the string contains a word like `bot`, `crawler` or `spider`.
+     *
+     * Kept apart from {@link declaresContact} because the two together are a
+     * declaration and either alone is not, and conflating them let a UA reach the
+     * `certain` tier on the strength of a URL by itself.
+     */
+    declaresAutomation: boolean;
+    /**
+     * True when contact is published using the crawler convention — a `+` before the
+     * URL or address, as in `+http://www.google.com/bot.html`.
+     *
+     * A bare URL in a User-Agent means very little: plenty of applications put their
+     * own homepage or support address in one, and the people behind those are people.
+     * The `+` prefix is the long-standing convention specifically for automation
+     * announcing its operator, so it carries the intent that a bare URL does not.
+     */
+    usesContactConvention: boolean;
+    /**
+     * A Chromium fork or embedded build that does not reliably implement the modern
+     * header set, named by its product token.
+     *
+     * This distinction is not pedantry, it is a very large population. "Chromium 89 and
+     * later sends `Sec-CH-UA`" is true of Google Chrome and of the mainstream forks
+     * that track it closely — Edge, Opera, Vivaldi, Brave, Samsung Internet — and false
+     * of UC Browser, MIUI Browser, Huawei Browser, QQ Browser, Amazon Silk, television
+     * and console builds, and many in-app WebViews, all of which are pinned to an older
+     * Chromium or strip the headers. Between them those are hundreds of millions of
+     * people, concentrated in South and East Asia.
+     *
+     * Detectors reasoning from the *absence* of Client Hints or Fetch Metadata must
+     * stand down for these; detectors reading what is present carry on unchanged.
+     */
+    chromiumFork?: string | undefined;
+}
+export interface UserAgentProduct {
+    name: string;
+    version?: string | undefined;
+}
+/** Longest UA we will process. Beyond this the string is not a UA, it is a payload. */
+export declare const MAX_USER_AGENT_LENGTH = 512;
+export declare function parseUserAgent(raw: string | undefined): ParsedUserAgent;
+/**
+ * True when the string has the *shape* of a mainstream browser UA. Says nothing
+ * about whether the claim is honest — that is what the consistency detectors are
+ * for. Its job is to identify strings whose claims are worth cross-checking.
+ */
+export declare function claimsBrowser(parsed: ParsedUserAgent): boolean;
+/**
+ * True when this client can be expected to implement Client Hints and Fetch Metadata.
+ *
+ * Only mainstream Chromium and Gecko qualify. Checks that reason from those headers
+ * being *missing* must consult this first, or they report a strong signal on every
+ * regional fork, television and in-app WebView on the internet.
+ */
+export declare function sendsModernHeaders(parsed: ParsedUserAgent): boolean;

package/dist/metrics.d.ts

@@ -0,0 +1,120 @@
+import type { ActionName, Decision } from "./policy/types.js";
+import type { Assessment, BotClass, BypassReason, Verdict } from "./types.js";
+/** Upper bounds in milliseconds. The last bucket is unbounded. */
+export declare const DURATION_BUCKETS_MS: readonly number[];
+/**
+ * Upper bounds for the probabilistic score histogram.
+ *
+ * Ten buckets of ten points, which is the whole range: `combine()` caps a
+ * probabilistic score at 99 and gives every proven assessment a flat 100, so nothing
+ * ever lands past the last bound and there is no `+Inf` overflow to think about.
+ * Proven requests are counted separately in {@link MetricsSnapshot.proven} rather than
+ * piled into the top bucket — their score plays no part in any decision, and including
+ * them would put a spike at the right-hand edge that means nothing.
+ */
+export declare const SCORE_BUCKETS: readonly number[];
+export interface MetricsSnapshot {
+    /** Requests assessed, including those that bypassed detection. */
+    requests: number;
+    /** Requests that skipped detection, by reason. */
+    bypassed: Record<BypassReason, number>;
+    verdicts: Record<Verdict, number>;
+    botClasses: Record<BotClass, number>;
+    actions: Record<ActionName, number>;
+    /** Terminal actions the safety guard replaced with something recoverable. */
+    downgrades: number;
+    /** Assessments resting on at least one piece of proven evidence. */
+    proven: number;
+    /** How often each detector produced evidence. */
+    detectorFirings: Record<string, number>;
+    /** How often each detector threw or timed out. */
+    detectorFailures: Record<string, number>;
+    /**
+     * Time spent inside each detector, when `metrics.perDetectorTiming` is on.
+     *
+     * Empty otherwise, and empty is the default: timing every detector means two clock
+     * reads per detector per request, which on a twenty-detector set is forty syscalls
+     * or so on the hot path to measure work that is usually a few microseconds. Worth
+     * paying while you tune; not worth paying forever.
+     */
+    detectorTimings: Record<string, {
+        count: number;
+        totalMs: number;
+        maxMs: number;
+    }>;
+    challenges: {
+        issued: number;
+        solved: number;
+        rejected: number;
+    };
+    /**
+     * How suspicion is distributed across the traffic that was scored.
+     *
+     * The counters behind the one chart that answers "how close does ordinary traffic
+     * run to the line?" — asked of the whole run rather than of the few hundred
+     * requests a dashboard happens to still be holding. Certain assessments are
+     * excluded; see {@link SCORE_BUCKETS}.
+     */
+    scores: {
+        count: number;
+        totalScore: number;
+        /** Cumulative counts, aligned with {@link SCORE_BUCKETS}. Prometheus wants them that way. */
+        buckets: number[];
+    };
+    duration: {
+        count: number;
+        totalMs: number;
+        maxMs: number;
+        /** Cumulative counts, aligned with {@link DURATION_BUCKETS_MS} plus a final `+Inf`. */
+        buckets: number[];
+    };
+    /** Actors currently held in the registry. A gauge, not a counter. */
+    actorsTracked: number;
+}
+export interface MetricsOptions {
+    /** Record per-detector durations. Off by default; see {@link MetricsSnapshot.detectorTimings}. */
+    perDetectorTiming?: boolean;
+}
+export declare class Metrics {
+    /** Whether the engine should bother timing individual detectors. Read on the hot path. */
+    readonly perDetectorTiming: boolean;
+    private requests;
+    private readonly bypassed;
+    private readonly verdicts;
+    private readonly botClasses;
+    private readonly actions;
+    private downgrades;
+    private proven;
+    private readonly detectorFirings;
+    private readonly detectorFailures;
+    private readonly detectorTimings;
+    private challengesIssued;
+    private challengesSolved;
+    private challengesRejected;
+    private scoreCount;
+    private scoreTotal;
+    private readonly scoreBuckets;
+    private durationCount;
+    private durationTotal;
+    private durationMax;
+    private readonly durationBuckets;
+    constructor(options?: MetricsOptions);
+    recordAssessment(assessment: Assessment): void;
+    /** One detector's duration, in milliseconds. Called only when {@link perDetectorTiming} is on. */
+    recordDetectorTiming(detector: string, ms: number): void;
+    recordDecision(decision: Decision): void;
+    recordChallenge(event: "issued" | "solved" | "rejected"): void;
+    snapshot(actorsTracked: number): MetricsSnapshot;
+}
+export interface PrometheusOptions {
+    /** Metric name prefix. Default `"bothandler"`. */
+    prefix?: string;
+}
+/**
+ * Renders a snapshot in the Prometheus text exposition format.
+ *
+ * Serve it from an endpoint your scraper can reach and nobody else can — the
+ * detector-firing series describe how detection behaves, which is exactly what
+ * someone tuning a scraper against you would like to read.
+ */
+export declare function toPrometheus(snapshot: MetricsSnapshot, options?: PrometheusOptions): string;

package/dist/notify/hub.d.ts

@@ -0,0 +1,70 @@
+import type { Clock } from "../internal/clock.js";
+import type { RedactionOptions } from "./redact.js";
+import type { BotEvent, NotifyFilter, Notifier } from "./types.js";
+export interface NotificationOptions {
+    /** Where events go. Empty means notifications are off. */
+    sinks?: readonly Notifier[];
+    filter?: NotifyFilter;
+    /** Redaction applied before an event leaves the process. `false` disables it. */
+    redaction?: RedactionOptions | false;
+    /**
+     * Suppress repeats of the same actor and verdict inside this window, ms. Default
+     * 60000. A scraper generates thousands of identical events a minute; without this
+     * the first thing your bot detection breaks is your alerting.
+     */
+    dedupeWindowMs?: number;
+    /**
+     * Hard ceiling on events delivered per dedupe window across all actors. Default
+     * 200. The backstop for the case dedupe cannot help with — a distributed scrape
+     * from ten thousand addresses, where every event is genuinely distinct.
+     */
+    maxPerWindow?: number;
+    /** Called when a sink throws. Wire it to your logs. */
+    onError?: (error: unknown, sinkId: string) => void;
+    clock?: Clock;
+}
+/**
+ * Fans events out to sinks, with the two properties that decide whether a
+ * notification system is an asset or a liability under load.
+ *
+ * **It never blocks a request.** `emit` returns immediately; delivery happens on its
+ * own. A wedged Slack webhook slows down nothing.
+ *
+ * **It has a ceiling.** Bot traffic arrives in volumes that ordinary alerting was
+ * not built for, and an unbounded notifier turns a scrape into an outage of your own
+ * paging system. Repeats of the same actor and verdict collapse into one event per
+ * window, and a global cap catches distributed traffic where every event is distinct.
+ * Suppressed counts are reported when the window rolls, so a quiet channel is never
+ * mistaken for quiet traffic.
+ */
+export declare class NotificationHub {
+    private readonly sinks;
+    private readonly types;
+    private readonly minScore;
+    private readonly certainOnly;
+    private readonly redaction;
+    private readonly dedupe;
+    private readonly dedupeWindowMs;
+    private readonly maxPerWindow;
+    private readonly clock;
+    private readonly onError;
+    private windowStart;
+    private windowCount;
+    private suppressed;
+    constructor(options?: NotificationOptions);
+    get enabled(): boolean;
+    /** Queues an event. Returns immediately; never throws. */
+    emit(event: BotEvent): void;
+    /**
+     * Redacts and fans out. The only way an event reaches a sink.
+     *
+     * Made the single path because it was not one: the suppression summary built its own
+     * fan-out loop and sent `sample.assessment` straight through, so every time a window
+     * rolled under load — precisely when bot traffic is heaviest — one request's raw
+     * address, cookies and query string went to the sink in the clear, beside the
+     * properly masked events it was summarising.
+     */
+    private dispatch;
+    private shouldDeliver;
+    private deliverSummary;
+}

package/dist/notify/index.d.ts

@@ -0,0 +1,7 @@
+export { NotificationHub } from "./hub.js";
+export type { NotificationOptions } from "./hub.js";
+export { consoleNotifier, webhookNotifier, slackNotifier, notifyJsNotifier } from "./sinks.js";
+export type { ConsoleNotifierOptions, WebhookNotifierOptions, SlackNotifierOptions, NotifyJsOptions } from "./sinks.js";
+export { redactEvent, CREDENTIAL_HEADERS } from "./redact.js";
+export type { RedactionOptions } from "./redact.js";
+export type { BotEvent, BotEventType, Notifier, NotifyFilter } from "./types.js";