@osqd/bothandlerjs 0.3.0

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

@@ -0,0 +1,24 @@
+import type { Detector } from "./types.js";
+export interface SessionIntegrityOptions {
+    /** Requests from one actor before a total absence of cookies is worth reporting. Default 12. */
+    minRequests?: number;
+    /** Also report navigations that carry no Referer. Default true. */
+    checkReferer?: boolean;
+}
+/**
+ * Does this client behave like something that holds a session?
+ *
+ * A browser accumulates state. Once your server has set anything at all — a session
+ * cookie, a consent flag, an A/B bucket — a real browser sends it back on every
+ * subsequent request, forever. A stateless HTTP client sends nothing back no matter
+ * how many times it visits, because it discards the response headers it does not
+ * care about.
+ *
+ * A dozen requests from one actor with not a single cookie is therefore a decent
+ * tell. It is only `moderate`, though, and the reason is worth internalising: the
+ * population that blocks all cookies is real people who have gone out of their way
+ * to protect their privacy. Escalating on this signal alone punishes precisely the
+ * users least deserving of it, which is the argument this library's whole design
+ * exists to make.
+ */
+export declare function sessionIntegrityDetector(options?: SessionIntegrityOptions): Detector;

package/dist/detectors/tls-fingerprint.d.ts

@@ -0,0 +1,34 @@
+import type { Detector } from "./types.js";
+/** What a given TLS fingerprint is known to belong to. */
+export interface FingerprintProfile {
+    /** Human-readable client name, e.g. `"Chrome 122 (macOS)"`. */
+    label: string;
+    /** Rendering engine this fingerprint belongs to, matched against the parsed UA. */
+    engine?: "blink" | "gecko" | "webkit" | undefined;
+    /** True when the fingerprint belongs to a tool rather than a browser. */
+    automated?: boolean | undefined;
+}
+export interface TlsFingerprintOptions {
+    /** Fingerprint (JA3/JA4) to profile. Supply your own; none ships with this library. */
+    profiles?: ReadonlyMap<string, FingerprintProfile>;
+}
+/**
+ * Compares the TLS handshake fingerprint against the client the User-Agent claims.
+ *
+ * This is the signal that survives a scraper copying your browser's headers
+ * perfectly, because the fingerprint is produced by the TLS library before a single
+ * HTTP byte is sent. A Go program presenting Chrome's User-Agent still has Go's
+ * ClientHello, and the mismatch is visible.
+ *
+ * Node cannot compute this — the ClientHello is consumed by the TLS layer before any
+ * JavaScript runs — so the fingerprint must come from your edge: nginx with a JA3
+ * module, HAProxy, Cloudflare's `cf-ja3-hash`, or an ALB with the right attributes
+ * forwarded. Point `tlsFingerprintHeader` at whichever header carries it.
+ *
+ * It stops at `strong` for two reasons. Fingerprints collide across clients that
+ * share a TLS library, so a match is weaker evidence than it looks. And they churn
+ * with every browser release, so a profile table is out of date the moment you stop
+ * updating it — a stale table produces mismatches for people running a browser newer
+ * than your data, which is the worst possible failure mode.
+ */
+export declare function tlsFingerprintDetector(options?: TlsFingerprintOptions): Detector;

package/dist/detectors/trap.d.ts

@@ -0,0 +1,98 @@
+import type { Detector } from "./types.js";
+export interface TrapOptions {
+    /**
+     * Paths that exist only to be found by something that reads markup rather than
+     * renders it. Matched exactly, or as a prefix when the entry ends in `/`.
+     */
+    paths?: readonly string[];
+    /**
+     * Names of form fields that are present in your HTML, hidden from people, and must
+     * therefore arrive empty. Anything that fills one filled it by parsing the form.
+     *
+     * **You have to hand the submitted values over.** The engine reads no request body,
+     * deliberately — doing so would mean consuming the stream before your own parser
+     * sees it. A hidden field in a `method="post"` form therefore arrives in the body,
+     * where nothing here can see it, so a query-string-only check would silently never
+     * fire for the forms honeypots are actually put on: sign-up, contact, comment,
+     * login. Put the parsed fields in `facts.extra.formFields` — see
+     * {@link TRAP_FIELD_SOURCE} — and this reads them alongside the query string.
+     */
+    formFields?: readonly string[];
+    /** Header a trap link may carry, if you prefer marking traps out-of-band. */
+    headerName?: string;
+}
+/**
+ * Where {@link trapDetector} looks for submitted form fields, inside `facts.extra`.
+ *
+ * ```ts
+ * botHandler(handler, {
+ *   enrich: (request, facts) => ({ ...facts, extra: { [TRAP_FIELD_SOURCE]: request.body } }),
+ * });
+ * ```
+ *
+ * Values are read as strings; anything else is ignored rather than coerced, because
+ * this feeds a `certain` verdict and `String(someObject)` is not evidence of anything.
+ */
+export declare const TRAP_FIELD_SOURCE = "formFields";
+/** Trap paths installed unless you replace them. Chosen to look like something worth fetching. */
+export declare const DEFAULT_TRAP_PATHS: readonly string[];
+/**
+ * Bait. The one detector whose evidence needs no statistics at all.
+ *
+ * A trap is a link or a form field that exists in your HTML but is unreachable by a
+ * person: hidden from layout, hidden from assistive technology, and excluded in
+ * `robots.txt`. There is no sequence of clicks, keystrokes or gestures that gets a
+ * human to it. Something that requests it read your markup and followed every href
+ * it found, which is the definition of automation.
+ *
+ * This is `certain` for a reason that no header check can match: it does not model
+ * what bots look like, it constructs a situation only a bot can be in. Detection by
+ * construction rather than by inference, and consequently the one signal whose
+ * false-positive rate does not depend on how well the internet is behaving today.
+ *
+ * Three things must all be true for that guarantee to hold, and they are your
+ * responsibility, not the library's:
+ *
+ * 1. The trap must be **invisible and unfocusable** — use {@link renderTrapLink},
+ *    which handles `aria-hidden`, `tabindex="-1"` and `rel="nofollow"` together.
+ * 2. The path must be **disallowed in robots.txt** — see {@link trapRobotsEntries} —
+ *    so a well-behaved crawler you *want* is not punished for being thorough.
+ * 3. The path must **serve nothing real**, now or ever. A trap that later becomes a
+ *    working endpoint turns into a source of false positives that will be very hard
+ *    to diagnose.
+ */
+export declare function trapDetector(options?: TrapOptions): Detector;
+export interface TrapLinkOptions {
+    /** Visible-to-nobody label. Something plausible to a parser, e.g. "Full export". */
+    label?: string;
+}
+/**
+ * Renders a trap link as HTML, with every attribute needed for the guarantee above.
+ *
+ * `aria-hidden` and `tabindex="-1"` together remove it from both the visual and the
+ * accessibility tree, so screen-reader and keyboard-only users — who are otherwise
+ * the group most at risk from clever traps — can never reach it. `rel="nofollow"`
+ * asks search engines not to follow it, and belt-and-braces with `robots.txt`.
+ *
+ * The output is static and contains no interpolated user input, so it is safe to
+ * inline. Emit it once, near the end of `<body>`.
+ */
+export declare function renderTrapLink(path: string, options?: TrapLinkOptions): string;
+/**
+ * Renders a hidden honeypot form field. Give it a name a form-filler will want to
+ * complete — `email_confirm`, `website` — and register that name in `formFields`.
+ *
+ * If the form is a POST — and the forms worth protecting are — the value arrives in
+ * the body, which this library never reads. Pass your parsed body through
+ * {@link TRAP_FIELD_SOURCE}, or the field will be rendered, filled, and ignored.
+ */
+export declare function renderTrapField(name: string): string;
+/**
+ * `robots.txt` lines that exclude your traps.
+ *
+ * Publish these. A crawler that obeys `robots.txt` is exactly the kind you want to
+ * keep, and it is unfair — and bad for your search ranking — to catch it in a net it
+ * had no way to see. The bots this detector is for ignore `robots.txt` entirely,
+ * which is the point.
+ */
+export declare function trapRobotsEntries(paths?: readonly string[]): string;

package/dist/detectors/types.d.ts

@@ -0,0 +1,70 @@
+import type { ActorSnapshot, Evidence, RequestFacts } from "../types.js";
+import type { ParsedUserAgent } from "../internal/ua.js";
+import type { MultiPatternMatcher } from "../internal/matcher.js";
+import type { BotSignature } from "./known-bots.js";
+import type { ActorState } from "../state.js";
+import type { Clock } from "../internal/clock.js";
+import type { IpRangeSet } from "../internal/ip.js";
+import type { DnsResolver } from "../internal/dns.js";
+/**
+ * Everything a detector is allowed to see.
+ *
+ * Detectors get a read-only view of the request plus the small number of services
+ * they legitimately need. They deliberately do **not** get the config object, the
+ * policy, or the response — a detector that can see the policy is a detector that
+ * will eventually be written to game it, and a detector that can touch the response
+ * has stopped being a detector.
+ */
+export interface DetectionContext {
+    readonly facts: RequestFacts;
+    /** The User-Agent, parsed once per request and shared by every detector. */
+    readonly ua: ParsedUserAgent;
+    /** Accumulated history for this actor. Read-only here; the engine owns mutation. */
+    readonly actor: ActorSnapshot;
+    /** The mutable state record behind the snapshot, for detectors that need the raw series. */
+    readonly state: ActorState;
+    readonly clock: Clock;
+    /** Compiled known-bot signatures, matched in a single pass. */
+    readonly signatures: MultiPatternMatcher<BotSignature>;
+    /** Signature matches for this request's UA, computed once and cached here. */
+    readonly signatureMatches: readonly BotSignature[];
+    /** DNS access for identity verification. Already timeout-bounded by the engine. */
+    readonly resolver: DnsResolver;
+    /** Named IP range sets from config: `allowlist`, `denylist`, `datacenter`, and per-crawler ranges. */
+    readonly ranges: ReadonlyMap<string, IpRangeSet>;
+    /** Scratch space shared between detectors within one request. Cleared afterwards. */
+    readonly shared: Map<string, unknown>;
+}
+/** Detectors return evidence, never verdicts. Combining evidence is the engine's job. */
+export type DetectorResult = Evidence | readonly Evidence[] | undefined | null;
+export interface Detector {
+    /** Stable id. Appears in evidence, rules, logs and metrics — treat it as public API. */
+    id: string;
+    /** One line, shown in `describeDetectors()` and in generated documentation. */
+    description: string;
+    /**
+     * `cheap` detectors are pure and synchronous: string and header inspection only.
+     * `io` detectors may touch DNS or a shared store, so the engine wraps them in a
+     * timeout and runs them concurrently. Mislabelling a blocking detector as `cheap`
+     * puts an unbounded await on the request path — the one thing this pipeline must
+     * never do.
+     */
+    cost?: "cheap" | "io";
+    /**
+     * `always` runs on every request. `confirming` runs only once a primary detector
+     * has produced something worth checking — used by reverse-DNS verification, which
+     * has no reason to resolve anything for a request that made no identity claim.
+     */
+    stage?: "always" | "confirming";
+    inspect(context: DetectionContext): DetectorResult | Promise<DetectorResult>;
+}
+/** Convenience for the common case of returning a single piece of evidence. */
+export declare function evidence(input: Evidence): Evidence;
+/**
+ * Whether a *missing* header may be treated as evidence.
+ *
+ * False when the source told us its header set is incomplete. Any check phrased as
+ * "the client did not send X" has to consult this first; a check phrased as "the
+ * client sent X and it contradicts Y" does not, because presence is still presence.
+ */
+export declare function absenceIsMeaningful(context: DetectionContext): boolean;

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

@@ -0,0 +1,32 @@
+import type { Detector } from "./types.js";
+/**
+ * Does this User-Agent contradict *itself*?
+ *
+ * Every other single-request detector compares the User-Agent against something else
+ * — the Client Hints, the header set, the header order. This one needs nothing but
+ * the string, which makes it the only consistency check that still works on a source
+ * with no headers at all: an nginx access line, a CDN log, a WAF event. That is not a
+ * small population, and until now every one of those requests reached the engine with
+ * exactly one usable detector.
+ *
+ * What it looks for is a string describing a client that has never existed. Two
+ * rendering engines at once. Two operating systems at once. Chrome on an iPhone,
+ * where Apple's rules mean Chrome is WebKit and says `CriOS`. A browser preamble no
+ * browser has emitted since 2009. These are not "unusual" — they are impossible, and
+ * they are what a User-Agent *randomiser* produces, because randomisers assemble a
+ * string from independent lists of browsers, versions and platforms and never check
+ * that the combination is one that ships.
+ *
+ * **Why none of it is `certain`.** The same reason `client-hints` is not: the client
+ * controls this string end to end, and the population that rewrites it badly includes
+ * privacy extensions, enterprise UA policies, developer emulation, and a long tail of
+ * embedded devices whose vendor concatenated two templates. A self-contradiction is
+ * excellent evidence that the string is fabricated; it is not evidence about who
+ * fabricated it, and a person with a UA-spoofing extension has fabricated one too.
+ *
+ * The version-versus-platform checks are deliberately the weakest thing here, because
+ * the "impossible" combination is only impossible on the vendor's own builds. Chrome
+ * ended Windows 7 support at 109, and Supermium and Thorium then shipped Chrome 120+
+ * on Windows 7 to a real, if small, population. Reported as `moderate`; never more.
+ */
+export declare function uaCoherenceDetector(): Detector;

package/dist/evidence.d.ts

@@ -0,0 +1,45 @@
+import type { BotClass, Evidence, Verdict } from "./types.js";
+export interface CombineOptions {
+    /**
+     * Score at or above which an unproven request is called `suspected-bot`. Default 60.
+     * Raising it makes the library quieter, never safer — nothing here blocks.
+     */
+    suspectThreshold: number;
+    /**
+     * Rejects `certain` evidence that carries no `deterministicBasis`. On by default
+     * outside production: it is the guard that stops the certainty tier from quietly
+     * eroding into "signals we feel strongly about", which is how a
+     * no-false-positive promise dies.
+     */
+    strictEvidence: boolean;
+    /** Called instead of throwing when `strictEvidence` finds a problem. */
+    onEvidenceViolation?: ((message: string, evidence: Evidence) => void) | undefined;
+}
+export interface CombinedEvidence {
+    verdict: Verdict;
+    botClass: BotClass;
+    identity?: string | undefined;
+    score: number;
+    confidence: number;
+    certain: boolean;
+    botEvidence: Evidence[];
+    humanEvidence: Evidence[];
+}
+/** Effective weight of a piece of evidence: its own, clamped, or its tier's default. */
+export declare function weightOf(item: Evidence): number;
+/** Strongest first: certainty tier, then weight. Stable, so detector order breaks ties. */
+export declare function sortEvidence(items: Evidence[]): Evidence[];
+/**
+ * Noisy-OR: the probability that *at least one* of these independent signals is
+ * telling the truth. Chosen over a sum because it is bounded at 1 without clamping
+ * and because it has the right shape — many weak signals genuinely do add up to
+ * something, but they approach certainty asymptotically and never reach it.
+ *
+ * The independence assumption is a simplification, and where it is most obviously
+ * wrong — several detectors reporting one stripping proxy — it is corrected before
+ * the weights get here: see {@link Evidence.family} and `independentWeights`. What
+ * remains is mild optimism about correlations nobody has named, which is tolerable
+ * precisely because this number cannot get anyone blocked.
+ */
+export declare function noisyOr(weights: readonly number[]): number;
+export declare function combineEvidence(items: readonly Evidence[], options: CombineOptions): CombinedEvidence;

package/dist/facts.d.ts

@@ -0,0 +1,46 @@
+import type { RequestFacts } from "./types.js";
+export interface FactsInput {
+    method?: string | undefined;
+    /** Request target, path plus optional query — what `req.url` gives you. */
+    url?: string | undefined;
+    /** Raw header map. Values may be arrays; names may be any case. */
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * Header names in wire order. Node exposes them via `req.rawHeaders` (alternating
+     * name/value) — pass that array directly, or a name-only list.
+     */
+    rawHeaders?: readonly string[] | undefined;
+    /** Socket address. Pass the *socket's* address; forwarding is resolved separately. */
+    ip: string;
+    timestamp?: number | undefined;
+    protocol?: "http" | "https" | undefined;
+    /**
+     * The HTTP version of the connection **this process accepted** — Node's
+     * `request.httpVersion`, not the version the client negotiated with your edge.
+     *
+     * The distinction has teeth. HTTP/2 forbids connection-specific headers, and
+     * `header-integrity` treats one as a deterministic protocol violation. If you set
+     * this from a forwarded header while the request itself arrived over HTTP/1.1 from
+     * a proxy — which adds `Connection: keep-alive` — you will manufacture that
+     * violation for every real browser behind that proxy, and it is a `certain` verdict,
+     * so it can block. Report the connection you actually have, or leave it unset.
+     */
+    httpVersion?: string | undefined;
+    tlsFingerprint?: string | undefined;
+    /** See {@link RequestFacts.partialHeaders}. Set it when the source cannot supply every header. */
+    partialHeaders?: boolean | undefined;
+    extra?: Record<string, unknown> | undefined;
+}
+/**
+ * Reduces a request to the facts detectors are allowed to see.
+ *
+ * Normalisation happens exactly once, here, and every detector reads the result. That
+ * is partly performance — lowercasing a header map per detector would be absurd — but
+ * mostly correctness: if one detector reads `req.headers['User-Agent']` and another
+ * reads `req.headers['user-agent']`, they will eventually disagree about the same
+ * request, and the bug will be invisible.
+ *
+ * Every field is bounded. Each one is attacker-controlled, and this runs on every
+ * request to your site.
+ */
+export declare function createFacts(input: FactsInput): RequestFacts;