@osqd/bothandlerjs 0.3.0

package/docs/design/decisions.md

@@ -0,0 +1,216 @@
+# Design decisions
+
+The choices that shaped the library, and what each one costs.
+
+← [Documentation](../index.md)
+
+---
+
+Everything here is a trade rather than a free win. They are recorded together so that a
+future change can weigh what it is undoing.
+
+---
+
+## Proof and suspicion are separate compartments
+
+**The decision.** Evidence is tiered. `certain` short-circuits to a verdict; everything else
+combines by noisy-OR into a 0–99 score. They never mix, and only the first can close a door.
+
+**Why.** Every signal that catches sophisticated automation is probabilistic, and every one
+has a population of real people who trip it. The usual answer — add the signals up, block
+above a threshold — is exactly the mistake: points do not compose into proof. Two unrelated
+suspicions about an unusual but entirely real browser reach 100 as readily as two
+well-founded ones, and the people who get caught are disproportionately the ones with the
+strongest reasons for their unusual setup.
+
+**The cost.** Sophisticated scrapers that trip four probabilistic signals are still not
+blocked. That is the intended behaviour, and it is why the [challenge](../challenge/index.md)
+exists as a ceiling for suspicion.
+
+See [evidence](../concepts/evidence.md).
+
+## The guard runs after rule selection, not inside a rule
+
+**The decision.** A separate pass, after the first matching rule is chosen, that replaces a
+terminal action when the verdict is not proven.
+
+**Why.** Anywhere else it can be forgotten. Inside a rule it has to be written correctly by
+every author of every rule, including at 3am during an incident. After selection it cannot
+be forgotten in a rule, worked around by a clever predicate, or bypassed by someone who has
+not read the documentation. Relaxing it is one explicit, greppable setting.
+
+**The cost.** A rule can say `block` and get `challenge`, which surprises people until they
+read `bothandler_downgrades_total`. That surprise is the feature.
+
+See [the guard](../concepts/the-guard.md).
+
+## No argument from absence may ever be `certain`
+
+**The decision.** A header missing from the facts never produces proof — including protocol
+violations that would otherwise qualify.
+
+**Why.** A header missing from a *record* is not a header missing from the *request*. A
+caller building facts from a log line, a WAF event or a partial adapter would otherwise
+manufacture proof against every request in the file. An HTTP/1.1 request with no `Host`
+violates RFC 9112 as plainly as anything on the certain list, and it is deliberately not
+proven here.
+
+**The cost.** Some genuinely conclusive observations are demoted to `strong`. Worth it: the
+failure mode it prevents is silent and enormous.
+
+## `deterministicBasis` is required in writing
+
+**The decision.** `certain` evidence must carry a written explanation of why it admits no
+benign explanation; enforced at runtime outside production, a warning inside it.
+
+**Why.** It is a forcing function. If you cannot write the sentence, your evidence is
+`strong`. Nearly every case where somebody wanted to mark something `certain` has failed at
+this step, which is the point.
+
+**The cost.** Slightly more ceremony to write a detector. The warning-not-throw behaviour in
+production means a third-party detector with a missing basis cannot take a live site down.
+
+## The engine never touches a response object
+
+**The decision.** `assess` returns an `Assessment`, `decide` returns a `Decision`, `handle`
+returns an `ActionOutcome`. Adapters apply it.
+
+**Why.** The same policy then behaves identically on Express and on a Worker; the engine is
+testable without a server; `assess()` is safe to run over a log file; and the
+[corpus](../testing/corpus.md), the [request tester](../operations/dashboard.md) and
+[`explain`](../testing/cli.md) all become possible for free.
+
+**The cost.** One more layer, and a new framework needs thirty lines of adapter.
+
+## Nothing may put an unbounded await on the request path
+
+**The decision.** `io` detectors run concurrently under a timeout, and a `cheap` detector's
+promise is timed out too. Event handlers and notification sinks are never awaited. The
+[audit](../operations/audit.md) runs on a timer, not in-band. `shareConfirmations` reads the
+store once per actor per instance, unawaited.
+
+**Why.** This code runs inline on every request to the site it protects. A slow resolver, a
+wedged webhook or a Redis failover must cost latency, not availability.
+
+**The cost.** Detection is sometimes less complete than it could be — a timed-out detector
+simply does not contribute. Correct: a bot filter that fails closed is an outage with extra
+steps.
+
+## Behavioural state is process-local; confirmations are not
+
+**The decision.** Rates, cadence, path breadth and UA history live in memory per process.
+`shareConfirmations` lets a *proven* verdict cross replicas.
+
+**Why.** A round trip per request would buy accuracy for signals that are only ever allowed
+to raise suspicion. A confirmation is not one of those: it is a fact about the client rather
+than a judgement about it. **Proof travels; suspicion stays home.**
+
+**The cost.** Behind four replicas each sees a quarter of an actor's traffic and is
+correspondingly less sure. The right trade for something that cannot close a door on its own.
+
+See [stores](../integration/stores.md).
+
+## Everything client-keyed is a bounded LRU
+
+**The decision.** 20,000 actors, 32 arrival timestamps, 64 path *hashes*, 4 User-Agents.
+Every cache has a TTL and a ceiling.
+
+**Why.** An unbounded map keyed by anything a client controls is a remote OOM.
+
+**The cost.** `requestsWithin` saturates at 32 and reports `undercounted: true` rather than a
+true rate. Deliberate — that series describes an actor cheaply, and exact counting belongs to
+[`rate-limit`](../policy/actions.md#rate-limit), which uses the store.
+
+## No IP intelligence, and no crawler ranges, ship with the library
+
+**The decision.** `datacenterRanges` and `crawlerRanges` are empty. What ships is the *URL*
+each crawler operator publishes.
+
+**Why.** A range baked into a release is wrong by the time somebody installs it, and being
+wrong here means verifying whoever has since been handed the address. A stale mapping is a
+false positive with a long half-life.
+
+**The cost.** `ip-intelligence` does nothing until you supply data, and crawler verification
+by address needs an opt-in refresher that makes outbound requests.
+
+See [verification](../detection/verification.md).
+
+## Client signals are capped at `moderate`, permanently
+
+**The decision.** Anything reported by JavaScript running in the client can never exceed
+`moderate`, whatever it says.
+
+**Why.** It is the one place an adversary has complete control. `navigator.webdriver`
+proves what the client *chose to report*.
+
+**The cost.** A genuinely conclusive-looking signal contributes modestly. That is the correct
+weight for a witness the defendant controls.
+
+See [client signals](../detection/client-signals.md).
+
+## One root cause is counted once
+
+**The decision.** Evidence may declare a `family`; within a family the strongest observation
+is taken instead of compounding.
+
+**Why.** Noisy-OR is only sound over independent signals. A corporate proxy that strips
+`Sec-Fetch-*` also strips the Client Hints and the `Accept-Language`, so three detectors fire
+about one person behind one appliance and the arithmetic reads their agreement as
+corroboration when it is an echo.
+
+**The cost.** Slightly lower scores on the traffic that should have them. A scraper that
+copied a User-Agent and nothing else scores 66 rather than 91 — still comfortably
+`suspected-bot`, still challenged.
+
+## Zero runtime dependencies
+
+**The decision.** The library imports nothing but `node:` builtins, and CI fails if that
+stops being true. `RedisStore` describes the commands it needs structurally and imports
+neither client.
+
+**Why.** Nothing here can hand your project a transitive advisory, an install script, or a
+version conflict with something you already run — for a package that sits on every request.
+
+**The cost.** More code written here: an IP parser, an Aho–Corasick matcher, an LRU, an
+emitter. All of them are exported, so at least they are useful twice.
+
+## The dashboard client is built, not a template literal
+
+**The decision.** 21 typed modules, esbuild-bundled into `client.generated.ts` at build time.
+
+**Why.** It was a 2,836-line template literal, with no type checking, no linting and no
+tests — inside a string, where a stray backtick in a CSS comment silently terminates the
+program.
+
+**The cost.** A build step, and a generated file in the tree. Worth it the first time the
+type checker catches something.
+
+## The corpus is a published entry point, not a test fixture
+
+**The decision.** `@osqd/bothandlerjs/corpus` ships `runCorpus` and all 526 cases.
+
+**Why.** The claims in this documentation are only worth anything if you can check them
+against *your* configuration. A corpus locked inside the test suite proves things about the
+library's own presets and nothing about yours.
+
+**The cost.** Package size, and a public API surface that now has to stay stable.
+
+See [the corpus](../testing/corpus.md).
+
+## The benchmark measures ratios, not microseconds
+
+**The decision.** Every budget is a multiple of a reference loop measured in the same
+process, seconds earlier.
+
+**Why.** A committed baseline in microseconds is a statement about the machine that produced
+it. CI runners are shared, throttled and re-provisioned; a suite that fails for reasons
+unrelated to the code is a suite people disable. A runner half the speed of a laptop runs
+both halves at half speed and the ratio is unchanged.
+
+**The cost.** The numbers are less immediately meaningful. Budgets are set at roughly double
+current cost — a guard, not a tripwire.
+
+## Related
+
+- [Evidence](../concepts/evidence.md) · [The guard](../concepts/the-guard.md) · [Threat model](../concepts/threat-model.md)
+- [Configuration](../reference/configuration.md) — where these show up as settings

package/docs/detection/client-signals.md

@@ -0,0 +1,96 @@
+# Browser signals
+
+An optional page script, and the hard ceiling on anything it reports.
+
+← [Documentation](../index.md) · [The detectors](detectors.md)
+
+---
+
+Everything else in this library reads what arrived over the wire. This reads what the
+browser says about itself — which is more informative and much less trustworthy, and the
+design is mostly about holding those two facts together.
+
+## What it reports
+
+```ts
+interface ClientSignals {
+  webdriver?: boolean;            // navigator.webdriver === true
+  noLanguages?: boolean;          // navigator.languages is empty
+  zeroDimensions?: boolean;       // screen.width === 0
+  inconsistentPlatform?: boolean; // userAgentData.platform disagrees with the UA string
+  interacted?: boolean;           // a trusted pointer/key event happened
+  msToInteraction?: number;
+  automationGlobals?: string[];   // _phantom, __nightmare, __selenium_unwrapped, …
+}
+```
+
+That is the whole list, and the omissions are the point. No canvas hash, no WebGL
+renderer, no font enumeration, no audio fingerprint. Those would raise accuracy and would
+make this a fingerprinting library, which is a different product with different ethics —
+see [design decisions](../design/decisions.md).
+
+## Wiring it up
+
+Three pieces: render the script, receive the report, attach it to the request.
+
+```ts
+import { renderClientScript, parseClientSignals } from "@osqd/bothandlerjs/client";
+
+// 1. On any page you want signals from. The nonce matches your CSP.
+app.get("/", (req, res) =>
+  res.send(page + renderClientScript({ endpoint: "/__signals", nonce: res.locals.nonce })),
+);
+
+// 2. An endpoint that stores what it receives against the session.
+app.post("/__signals", express.json({ limit: "2kb" }), (req, res) => {
+  const signals = parseClientSignals(req.body);
+  if (signals) req.session.botSignals = signals;
+  res.status(204).end();
+});
+
+// 3. Attach it, so the detector can read it.
+app.use(
+  botHandler(detector, {
+    enrich: (request, facts) => ({ ...facts, extra: { clientSignals: request.session?.botSignals } }),
+  }),
+);
+```
+
+**Where the report lives between step 2 and step 3 is your decision, not the library's.**
+A session store, a short-lived cache keyed by a cookie, an edge KV — the library does not
+invent a storage mechanism, because where per-session data lives is a question only your
+application can answer.
+
+The script reports on `sendBeacon` (falling back to `fetch` with `keepalive`), so a short
+visit still reports as the page goes away, and it reports again after the first trusted
+interaction if one happens within `interactionWindowMs`.
+
+## Why it is capped at `moderate`
+
+Permanently, and no option changes it.
+
+Every value here 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 the detector sees afterwards is whatever
+that framework decided to say.
+
+What this genuinely catches is **automation that never bothered to hide** — Selenium out
+of the box, a scripted Chrome somebody pointed at your site this afternoon — which is a
+large share of real bot traffic and worth catching. What it must never do is convince you
+that a clean report means a person.
+
+`isTrusted` on the interaction event is the most informative bit on the page, and it is
+still forgeable by a framework driving a real browser. Treat it as evidence that somebody
+*probably* touched the page, not as proof that anybody did.
+
+## What the absence of a report means
+
+Nothing. A visitor with JavaScript disabled, a request that never reached an HTML page, a
+beacon that was blocked — all produce no signals, and the detector stays silent rather
+than treating silence as suspicion. A great many real people browse this way.
+
+## Related
+
+- [The detectors](detectors.md#client-signals)
+- [Design decisions](../design/decisions.md) — why there is no fingerprinting here
+- [The challenge](../challenge/index.md) — the other thing that runs in a browser

package/docs/detection/detectors.md

@@ -0,0 +1,376 @@
+# The detectors
+
+All twenty, each with what it reads, why it exists, what it can conclude, and what it
+costs.
+
+← [Documentation](../index.md) · [How detection works](index.md)
+
+---
+
+Every detector returns **evidence**, never a verdict. What each one is allowed to
+conclude is as important as what it looks at, so every entry below names its ceiling.
+
+- **cost** — `cheap` is synchronous and in-memory; `io` may make a network call.
+- **stage** — `always` runs on every request; `confirming` runs only when a signature
+  matched, because there is nothing to confirm otherwise.
+- **ceiling** — the highest certainty this detector can produce. Only `certain` can cost
+  somebody their access; see [the guard](../concepts/the-guard.md).
+
+```ts
+import { defaultDetectors } from "@osqd/bothandlerjs";
+
+new BotHandler({ detectors: defaultDetectors() });        // the default set
+new BotHandler({ extraDetectors: [myDetector()] });       // add to it
+```
+
+`bothandlerjs detectors --preset protect-content` lists what a configuration actually
+installs, which is the reliable answer for your setup.
+
+---
+
+## Single-request detectors
+
+These need nothing but the request in front of them. They work on a replayed log line as
+well as on live traffic.
+
+### `self-identified`
+
+**cheap · always · ceiling `certain`**
+
+The client told us what it is. This is the backbone of the proven tier.
+
+When a request arrives saying `python-requests/2.31.0` or `Googlebot/2.1`, nothing is
+being *inferred*. We are taking the client at its word — and if that word is a lie, the
+misclassification belongs to whoever lied, not to a heuristic that guessed wrong about a
+person. That is a point about responsibility rather than about technology, and it is why
+this tier can do what the others may not.
+
+What it recognises: the [signature database](signatures.md) (search crawlers, AI
+crawlers, monitors, scanners, social unfurlers), bare library tokens (`curl/`, `okhttp`,
+`Go-http-client`), and User-Agents that announce automation outright.
+
+```ts
+// curl/8.4.0
+{ certainty: "certain", summary: "User-Agent identifies curl",
+  deterministicBasis: 'The product token "curl/" is emitted by an HTTP library or an ' +
+    "automation runtime and by no browser. Nothing a person does in a browser produces it." }
+```
+
+A bare token with no browser preamble is `strong` rather than `certain` when it could
+plausibly be a person's own script; the database's own entries are `certain`.
+
+### `ua-coherence`
+
+**cheap · always · ceiling `strong`**
+
+Does this User-Agent contradict *itself*?
+
+Every other single-request check 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 thing when a
+replay is the main way people evaluate a policy.
+
+It reads engines, platforms and versions against each other: a Safari token on Windows, a
+Chrome version that does not exist, a mobile token with a desktop platform.
+
+### `header-integrity`
+
+**cheap · always · ceiling `certain`**
+
+Compares the header set against what the client it claims to be would actually send.
+
+The `certain` cases here are **protocol violations** rather than absences: two `Host`
+headers, a second `Content-Length`, a connection-specific header on HTTP/2. RFC 9112
+requires a recipient to reject those; no compliant client emits them.
+
+Everything else — a browser claim with no `Accept`, no `Accept-Language`, no
+`Accept-Encoding` — is `moderate` or `strong` and shares a **family**, because a client
+missing three browser headers has one property reported three times. See
+[families](../concepts/evidence.md#families).
+
+```ts
+headerIntegrityDetector({ requireAcceptLanguage: false })   // for an API-only origin
+```
+
+### `header-order`
+
+**cheap · always · ceiling `moderate`**
+
+The order headers arrived in, against orderings every mainstream browser respects.
+
+Header order is a fingerprint that a scraper copying your browser's headers usually gets
+wrong, because it sets them from a dictionary. The rules are stated as invariants — "`X`
+must not appear after `Y`" — verified against Chrome, Firefox, Safari and Edge, and kept
+deliberately few. The value is in rules that no browser breaks; modelling any browser's
+exact sequence would turn this into a source of false positives on next month's release.
+
+Needs `rawHeaders`; see [adapters](../integration/adapters.md).
+
+### `client-hints`
+
+**cheap · always · ceiling `certain`**
+
+Cross-checks `Sec-CH-UA` against the legacy User-Agent string.
+
+A real Chromium generates both from the same internal state, so they always agree. A
+client that rewrites one and forgets the other contradicts itself — visible from a single
+request, with no history, no state and no network call, which makes it one of the cheapest
+high-value checks there is.
+
+Most of it is `strong` rather than `certain`, because the population that rewrites a
+User-Agent without touching Client Hints includes privacy extensions and corporate
+middleboxes as well as scrapers.
+
+### `fetch-metadata`
+
+**cheap · always · ceiling `strong`**
+
+`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 forge from inside a page — and their *absence* on an
+engine known to send them is informative.
+
+It knows which engine versions ship them (Blink 76+, Gecko 90+), so an old browser is not
+accused of missing something it never sent.
+
+### `accept-signature`
+
+**cheap · always · ceiling `strong`**
+
+`Accept` and `Accept-Language` as a fingerprint of what the client will do with the
+response.
+
+A browser asking for a page sends a long, specific `Accept` describing the document
+formats it renders. A scraper sends `*/*` because it will take anything and parse it
+itself. Malformed language lists — values that are not RFC 9110 language ranges — are a
+separate and stronger signal, because a browser cannot produce one.
+
+### `probe-signature`
+
+**cheap · always · ceiling `strong`**
+
+What is this request *asking for*?
+
+Every other detector reads the client; this one reads the target, and it exists to close a
+gap the rest cannot: 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 an ordinary browser User-Agent and asks for `/.env`,
+`/wp-admin/setup-config.php`, `/../../etc/passwd` or a path with a SQL payload in the
+query string.
+
+```ts
+probeSignatureDetector({ extraPaths: ["/internal/admin"] })
+```
+
+### `tls-fingerprint`
+
+**cheap · always · ceiling `strong`**
+
+Compares an edge-supplied JA3/JA4 handshake fingerprint against the client the User-Agent
+claims to be.
+
+This is the signal that survives a scraper copying every header perfectly: the TLS
+handshake is produced by the client's TLS stack rather than by its HTTP code, so a Go or
+Python program wearing Chrome's headers still shakes hands like Go or Python.
+
+The library does not compute fingerprints — it cannot see the handshake — so it reads one
+your edge computed:
+
+```ts
+createFetchAdapter(handler, { tlsFingerprintHeader: "cf-ja3-hash" });
+
+tlsFingerprintDetector({ profiles: { "<ja3 hash>": { name: "Chrome 122", engine: "blink" } } })
+```
+
+Without profiles it stays quiet rather than guessing.
+
+### `ip-intelligence`
+
+**cheap · always · ceiling `certain`**
+
+What is known about where this came from. Two range sets, 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 decided about.
+
+**`datacenterRanges` is `moderate`** — a server address is a fact about hosting, not about
+intent. VPNs, corporate egress and privacy relays all live there, and so do plenty of
+people.
+
+```ts
+new BotHandler({
+  denylist: ["203.0.113.0/24"],
+  datacenterRanges: ["198.51.100.0/16"],
+});
+```
+
+The library ships **no address data** and refuses to guess any; see
+[design decisions](../design/decisions.md).
+
+### `trap`
+
+**cheap · always · ceiling `certain`**
+
+A path no link points at, a form field no rendered browser shows, a header only a script
+would echo. Reaching one requires reading the page as data rather than as a page.
+
+```ts
+import { renderTrapLink, trapRobotsEntries, DEFAULT_TRAP_PATHS } from "@osqd/bothandlerjs";
+
+app.get("/", (_req, res) => res.send(page + renderTrapLink()));
+```
+
+The trap paths belong in your `robots.txt` as `Disallow`, which is what makes the evidence
+fair: a crawler that obeys robots never sees them, so touching one is a decision.
+
+---
+
+## Behavioural detectors
+
+These read [the actor's history](../concepts/actors.md). They are the reason the library
+keeps state at all, and none of them can reach `certain` — behaviour is a judgement.
+
+### `cadence`
+
+**cheap · always · ceiling `moderate`**
+
+Is this actor's *rhythm* human?
+
+People generate ragged inter-arrival times: they read, scroll, get distracted, open three
+tabs, then nothing for four minutes. A loop calling `setInterval` 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 pacing itself at one request every five seconds is
+invisible to a rate check and obvious to this one.
+
+### `rate-anomaly`
+
+**cheap · always · ceiling `moderate`**
+
+How fast is this actor going?
+
+Rate is the signal people reach for first and trust most, and it deserves the least trust
+of anything here. The *actor* behind a high rate is frequently not one client: a corporate
+NAT, a CGNAT pool, a university, a VPN exit and a shared office all present hundreds of
+real people under one key.
+
+So it is deliberately conservative, and it is the detector most improved by a better
+[`actorKey`](../concepts/actors.md#the-actor-key).
+
+### `crawl-breadth`
+
+**cheap · always · ceiling `weak`**
+
+Reading the site, or enumerating it?
+
+A person revisits: they land on an article, go back to the index, follow a related link,
+return. 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.
+
+`weak`, because a *welcome* crawler produces exactly this shape and so does a person on a
+first visit to a documentation site.
+
+### `identity-rotation`
+
+**cheap · always · ceiling `moderate` · off by default**
+
+One actor, several User-Agents. A single client does not change its User-Agent
+mid-session; something that does is cycling through a spoofing list.
+
+**Off by default, and think before enabling it.** With the default address-based actor
+key, a corporate NAT presents a hundred people's browsers as one actor with a hundred
+User-Agents — which is this detector's exact signature and is entirely innocent. Enable it
+when your `actorKey` identifies a session rather than a network.
+
+### `session-integrity`
+
+**cheap · always · ceiling `moderate`**
+
+Does this client hold a session?
+
+A browser accumulates state: once your server has set anything — a session cookie, a
+consent flag, an A/B bucket — a real browser sends it back on every subsequent request. A
+stateless HTTP client sends nothing back however many times it visits.
+
+It only speaks about clients that *claim* to be browsers, and only after your origin has
+had a chance to set something.
+
+### `browsing-coherence`
+
+**cheap · always · ceiling `moderate` (human)**
+
+The one that argues the other way.
+
+It reports the marks of a real browsing session — a cache validator (`If-None-Match`), a
+cookie jar, a same-site navigation, a plausible `Referer` chain — as **human** evidence,
+which the scoring model subtracts from the bot score.
+
+Without it the model has an asymmetry that shows up as false positives on exactly the
+people least able to afford them: a researcher on a shared university address reading forty
+pages accumulates four suspicions and nothing at all in their defence.
+
+### `clearance`
+
+**cheap · always · ceiling `certain` (human)**
+
+Reads a signed clearance token the client already holds. The library's only source of
+human-pointing evidence that is not a guess about headers, and the levels are exact
+because overstating any of them would undo the design:
+
+| Level | Certainty | |
+| ----- | --------- | --- |
+| `operator` | `certain` | Your application said this is a person. We believe you. |
+| `pow` | `moderate` | A proof of work was solved. A headless browser solves it too. |
+
+See [the challenge](../challenge/index.md).
+
+### `client-signals`
+
+**cheap · always · ceiling `moderate`**
+
+Reads what the optional [browser script](client-signals.md) reported: `navigator.webdriver`,
+an empty language list, zero screen dimensions, a platform that disagrees with the
+User-Agent, whether a trusted interaction happened.
+
+**Capped at `moderate`, hard.** Every value here 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`. What this genuinely catches
+is automation that never bothered to hide — which is a large share of real bot traffic —
+and what it must never do is convince you that a clean report means a person.
+
+---
+
+## Confirming detectors
+
+### `crawler-verification`
+
+**io · confirming · ceiling `certain`**
+
+Confirms or refutes a claimed crawler identity. Runs only when a signature matched, because
+with no claim there is nothing to confirm and no lookup to make.
+
+Two mechanisms, depending on what the operator publishes:
+
+- **Forward-confirmed reverse DNS.** `PTR` the address, check the name is under the
+  crawler's domain, then resolve that name forward and check it comes back to the same
+  address. A confirmation is `verified-bot`; a **refutation** is `certain` evidence of an
+  impersonator, and the strongest thing this library ever concludes about a forgery.
+- **Published address ranges.** A lookup rather than a round trip. See
+  [verifying a crawler](verification.md).
+
+A resolver that is merely *unhappy* must reach a different verdict from one that
+*disproves* the claim, and it does: a timeout produces no evidence at all.
+
+---
+
+## Related
+
+- [How detection works](index.md) — the pipeline these run in
+- [Writing a detector](writing-a-detector.md) — the contract, and the rules on certainty
+- [Evidence and certainty](../concepts/evidence.md) — what the tiers mean