@osqd/bothandlerjs 0.3.0

package/docs/policy/presets.md

@@ -0,0 +1,191 @@
+# Presets
+
+Eight rule sets to read, adapt and own.
+
+← [Documentation](../index.md) · [Policy](index.md)
+
+---
+
+A preset is not a black box. It is an array of [rules](rules.md) — the same ones you would
+write — exported from `src/policy/presets.ts`, each carrying an `id` and a `reason`. Print
+one, change one line, keep the rest:
+
+```ts
+import { BotHandler, protectContent } from "@osqd/bothandlerjs";
+
+new BotHandler({
+  rules: protectContent().filter((rule) => rule.id !== "http-client-challenge"),
+});
+```
+
+Or name it and be done:
+
+```ts
+new BotHandler({ preset: "protect-content" });
+```
+
+Every preset assumes the default `strict` [guard](../concepts/the-guard.md), which is why
+even the harshest of them is safe to try: a rule asking to block cannot deny an unproven
+request. **Choose a preset for the shape of the policy; the guard decides how far it is
+allowed to go.**
+
+| Preset | For | Terminal on |
+| ------ | --- | ----------- |
+| [`monitor-only`](#monitor-only) | week one, always | nothing |
+| [`allow-crawlers`](#allow-crawlers) | publishers who want to be found | impersonators, scanners, traps |
+| [`protect-content`](#protect-content) | a public content site | impersonators, scanners, traps |
+| [`decline-ai-training`](#decline-ai-training) | keeping search, declining trainers | + declared AI crawlers |
+| [`protect-data`](#protect-data) | pricing, listings, inventory | + declared AI and SEO crawlers |
+| [`protect-api`](#protect-api) | a JSON API | impersonators, scanners, traps |
+| [`protect-auth`](#protect-auth) | login, signup, checkout — **those routes only** | all proven automation |
+| [`under-attack`](#under-attack) | during an incident, then off again | all proven automation |
+
+---
+
+## `monitor-only`
+
+Three rules, no action heavier than `log`. Nothing is ever withheld from anybody.
+
+```ts
+new BotHandler({ preset: "monitor-only" });
+```
+
+**Run this first, for at least a week, on real traffic.** Every bot policy that has caused
+an outage was deployed straight to enforcement by someone who was sure they knew what
+their traffic looked like. Watch the [dashboard](../operations/dashboard.md), find the
+integration you forgot about, and then choose a real preset.
+
+## `allow-crawlers`
+
+Allows more than it stops, by name. Verified crawlers first; declared benign automation —
+link unfurlers, feed readers, uptime monitors — allowed rather than merely tolerated; and
+the last rule tags everything else, so nothing is withheld at all.
+
+Reach for it when a bot policy has already cost you traffic, or when the site's whole
+purpose is to be indexed, quoted and shared. The cost is honest: bulk extraction is
+rate-limited rather than challenged, so a determined scraper gets your content. On a site
+that wants to be read that was always true; what this refuses to do is trade away your
+search traffic to make it slightly less true.
+
+## `protect-content`
+
+The sensible default for a public site. Keeps the crawlers that bring traffic, slows the
+ones that only take it, challenges what is probably automated, blocks what has proven
+itself.
+
+Two rules are worth knowing before you copy it. `http-client-challenge` challenges bare
+HTTP clients rather than blocking them — plenty of those are your own integrations.
+`suspected-challenge` fires at `minScore: 70`, which is the number to move first if you
+are seeing too much or too little.
+
+## `decline-ai-training`
+
+Keep the search engines. Decline the model trainers.
+
+The split it draws is the one the AI crawlers publish themselves. A crawler collecting a
+training corpus and a crawler fetching one page because a person asked about it are
+different jobs, often from the same operator under different product tokens.
+`ChatGPT-User`, `PerplexityBot`, `OAI-SearchBot`, `ClaudeBot`, `Mistral-AI` and
+`DuckDuckBot` are served and tagged; the rest of the `ai` category is blocked with a body
+that says so.
+
+**`robots.txt` is the primary mechanism, not this.** The crawlers named here honour it, and
+a rule that blocks a crawler nobody told is load with no compliance. Generate the file from
+the policy and publish it — see [robots.txt](robots.md):
+
+```ts
+import { declineAiTraining, robotsFromRules } from "@osqd/bothandlerjs";
+const { robotsTxt } = robotsFromRules(declineAiTraining(), { sitemap: "https://example.com/sitemap.xml" });
+```
+
+## `protect-data`
+
+For an application whose value is in its data. Like `protect-content`, plus: AI and SEO
+crawlers are blocked on declaration, all proven automation is challenged, and
+`/api/` and `/search` carry a 120/minute ceiling that applies to everyone equally.
+
+The `any-proven-automation-challenge` rule matches on **verdicts** rather than bare
+`{ certain: true }` — which would also match a proven human, and challenging a customer you
+just vouched for is worse than useless. That subtlety is worth carrying into your own
+rules.
+
+## `protect-api`
+
+One difference drives the whole shape: **a challenge is useless here.** A proof-of-work
+interstitial is solved by a browser running JavaScript, and an API client is not one.
+Challenging your customers' integrations does not slow an attacker down; it breaks the
+integrations and leaves the attacker to solve it once in a headless browser. So the
+escalation ladder is rate limiting.
+
+The second difference is about what detection is *for* on an API. Your authentication is
+the control that matters and already knows who the caller is. This preset tags everything
+so your handlers can combine a verdict with a key, a plan and a quota; it does not try to
+be the access control. A bare HTTP client is the normal case here, so the rule that
+challenges one on a content site is deliberately absent.
+
+## `protect-auth`
+
+**Mount this on those routes only.**
+
+```ts
+app.use("/login", botHandler(authDetector));
+app.use("/checkout", botHandler(authDetector));
+```
+
+Applied site-wide it blocks your payment webhooks, your own server-side renderer and every
+honest crawler you have — all proven automation, which is exactly what this refuses. That
+is correct on a login form and an outage anywhere else. The [corpus](../testing/corpus.md)
+catches it; the symptom otherwise is a support ticket about missing orders three days
+later.
+
+The unusual choice is `delay` on merely-suspected traffic: 250 ms is imperceptible to a
+person filling in a form and ruinous to a credential stuffer working through a list — and,
+unlike a challenge, it excludes nobody.
+
+## `under-attack`
+
+A deliberately impatient posture for an incident. Everything proven is refused, suspicion
+is challenged at `minScore: 40`, and *everyone* — people included — is held to 30 requests
+a minute, because a uniform ceiling is the one mitigation that cannot single anybody out.
+
+Three things to be clear about first.
+
+**It is temporary.** The low threshold will interrupt real people on unusual browsers.
+Put it behind a switch you can flip without a deploy — `updatePolicy()` and the
+[dashboard's editor](../operations/runtime-changes.md) exist for this.
+
+**It still cannot deny anyone on a guess.** The guard applies here as everywhere. An
+incident is precisely when people reach for `falsePositivePolicy: "aggressive"`, and
+precisely when the population getting caught is at its most unusual.
+
+**It is not DDoS protection.** This runs in your process, after the connection is
+accepted. Volume that hurts at the network layer needs handling at the network layer;
+what this reduces is the *usefulness* of the traffic to whoever is sending it.
+
+And the practical warning the corpus makes concrete: like `protect-auth`, this refuses
+proven automation, so your own webhooks, health probes and renderer are refused too —
+thirteen of the corpus's infrastructure cases are. Allowlist their addresses *before* you
+switch it on, not during the incident when you notice.
+
+## Choosing between them
+
+By name, for config-driven setups:
+
+```ts
+import { PRESETS, type PresetName } from "@osqd/bothandlerjs";
+const rules = PRESETS[process.env.BOT_PRESET as PresetName]();
+```
+
+Whichever you pick, run it against the corpus before it reaches production — the run tells
+you which of your own traffic the policy refuses:
+
+```bash
+npx @osqd/bothandlerjs check --preset protect-auth
+```
+
+## Related
+
+- [Rules](rules.md) — the grammar these are written in
+- [Actions](actions.md) — what each rule can ask for
+- [Choosing a policy](../start/choosing-a-policy.md) — the decision, start to finish
+- [The corpus](../testing/corpus.md) — 526 cases, including the ones these presets get wrong

package/docs/policy/robots.md

@@ -0,0 +1,128 @@
+# robots.txt
+
+Saying out loud what your policy already does.
+
+← [Documentation](../index.md) · [Policy](index.md)
+
+---
+
+## Why this is here
+
+Declining a crawler and not saying so is the worst of both worlds: it keeps coming, wastes
+your bandwidth rediscovering that it is unwelcome on every request, and you get no credit
+for having a policy. `robots.txt` is where you say it — and for the well-behaved crawlers,
+saying it is the *only* thing you need to do, because they will simply stop.
+
+Two things this will not pretend. `robots.txt` is a request, not enforcement; everything
+that ignores it is exactly the population this library exists for. And a generated file can
+only reflect rules it can **read**.
+
+References: [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309.html) is the standard;
+[robotstxt.org](https://www.robotstxt.org/) is the older convention it formalises.
+
+---
+
+## From your policy
+
+The useful entry point. It reads your rules and writes the file that matches them:
+
+```ts
+import { declineAiTraining, robotsFromRules } from "@osqd/bothandlerjs";
+
+const { robotsTxt, declined, served, unreadable } = robotsFromRules(declineAiTraining(), {
+  disallowPaths: ["/internal/", "/admin-console"],   // your trap paths belong here
+  sitemap: "https://example.com/sitemap.xml",
+});
+
+app.get("/robots.txt", (_req, res) => res.type("text/plain").send(robotsTxt));
+```
+
+It reads every rule whose action [denies service](actions.md) and whose `match` names an
+`identity` or a `category`, and declines exactly those crawlers.
+
+### The three fields you must look at
+
+**`declined`** — the signature ids in the file, with categories expanded to the crawlers
+they cover. Reporting only the explicitly-named ids would say "0 declined" for a policy
+that turns away an entire category.
+
+**`served`** — crawlers a later rule would have declined, but an earlier rule serves.
+Policies are first-match-wins, so these are correctly *absent* from the file.
+`decline-ai-training` is the case that found this: it serves `ChatGPT-User` and blocks the
+rest of the `ai` category, and the generated file was telling `ChatGPT-User` to go away.
+"Why is GPTBot in my robots.txt but ChatGPT-User is not" has an answer, and it is your own
+rule order.
+
+**`unreadable`** — rules that could not be read, with the reason. Two kinds:
+
+- *the match is a predicate function* — it can be run, but not asked which crawlers it is
+  about.
+- *the match is scoped to a path* — the rule denies service **there**, but a named group in
+  `robots.txt` gets `Disallow: /`, the whole site. Reported rather than passed over,
+  because the error runs in the expensive direction: a crawler told to stay away entirely
+  stops fetching the pages you wanted indexed, and that surfaces weeks later as a ranking
+  drop with nothing in the logs pointing at this file.
+
+Check `unreadable` before publishing and add anything it names by hand. A `robots.txt` that
+silently omits something you block is worse than no generated file at all — it tells
+crawlers they are welcome where they are not.
+
+---
+
+## By hand
+
+When you want a file that is not derived from a policy:
+
+```ts
+import { generateRobotsTxt } from "@osqd/bothandlerjs";
+
+generateRobotsTxt({
+  header: ["# Automated collection is declined. Contact abuse@example.com."],
+  disallowCategories: ["ai"],
+  disallowBots: ["semrushbot", "ahrefsbot"],
+  disallowPaths: ["/internal/", "/cart"],
+  allowPaths: ["/blog/"],
+  crawlDelay: 5,
+  sitemap: ["https://example.com/sitemap.xml"],
+});
+```
+
+| Option | Effect |
+| ------ | ------ |
+| `disallowBots` | signature ids to decline entirely |
+| `disallowCategories` | whole [categories](../detection/signatures.md) — `ai`, `seo`, … |
+| `disallowPaths` | disallowed for every crawler; put your [trap](../detection/detectors.md) paths here |
+| `allowPaths` | rendered ahead of the disallows |
+| `sitemap` | absolute URLs, per the specification |
+| `crawlDelay` | seconds, wildcard group only; not honoured by every crawler |
+| `header` | verbatim lines at the top, already comment-prefixed |
+| `signatures` | the signature database to resolve ids against |
+
+### The grouping rule this gets right for you
+
+Under RFC 9309 a crawler obeys the most specific group that names it and **ignores every
+other group**. So a named `User-agent: GPTBot` group replaces the wildcard group outright
+for GPTBot — including your `Disallow: /internal/` lines.
+
+The renderer repeats global path rules inside every named group. Forgetting that is the
+classic way a `robots.txt` accidentally *un*-blocks a trap path for exactly the crawlers
+you were most careful about.
+
+The wildcard group is emitted first purely as a courtesy to the person reading the file;
+crawlers pick their group by specificity, not by position.
+
+---
+
+## From the command line
+
+```bash
+npx @osqd/bothandlerjs robots --preset decline-ai-training --sitemap https://example.com/sitemap.xml
+```
+
+See [the CLI](../testing/cli.md).
+
+## Related
+
+- [Presets](presets.md) — `decline-ai-training`, which this pairs with
+- [Signatures](../detection/signatures.md) — the ids and categories being named
+- [Detectors](../detection/detectors.md) — the trap paths worth disallowing here

package/docs/policy/rules.md

@@ -0,0 +1,134 @@
+# Matching requests
+
+Every field a rule can match on, and what each one is good for.
+
+← [Documentation](../index.md) · [Policy](index.md)
+
+---
+
+```ts
+interface Rule {
+  id: string;                    // stable; names every decision and log line it produces
+  match: MatchSpec | ((assessment: Assessment) => boolean);
+  action: ActionName;
+  params?: ActionParams;
+  reason?: string;
+}
+```
+
+Every field in a `MatchSpec` must match — it is an `AND`. Fields accepting a list match if
+*any* entry matches. An empty `match: {}` matches everything, which is occasionally what
+you want at the bottom of a list.
+
+## What this request is
+
+| Field | Type | |
+| ----- | ---- | --- |
+| `verdict` | one or more [`Verdict`](../concepts/verdicts.md) | `"suspected-bot"`, `["confirmed-bot", "verified-bot"]` |
+| `botClass` | one or more `BotClass` | The field most policies want — it carries intent. |
+| `certain` | `boolean` | `true` matches only proven verdicts, including a proven human. |
+| `minScore` / `maxScore` | `number` | Inclusive. Only meaningful for probabilistic verdicts. |
+
+```ts
+// Proven automation of any kind
+{ match: { certain: true, verdict: ["confirmed-bot", "verified-bot"] } }
+
+// A judgement, but a confident one
+{ match: { verdict: "suspected-bot", minScore: 70 } }
+```
+
+## Who this claims to be
+
+| Field | Type | |
+| ----- | ---- | --- |
+| `identity` | one or more `string` | A [signature](../detection/signatures.md) id: `"googlebot"`, `"gptbot"`. |
+| `category` | one or more `BotCategory` | `"ai"`, `"search"`, `"seo"`, `"scanner"`, … |
+
+```ts
+{ id: "no-training", match: { category: "ai" }, action: "block" }
+```
+
+**An identity match alone matches forgeries too**, because the identity is what the client
+*claimed*. Pair it with `verdict: "verified-bot"` when trust is the point:
+
+```ts
+{ id: "trust-google", match: { identity: ["googlebot"], verdict: "verified-bot" }, action: "allow" }
+```
+
+## What it asked for
+
+| Field | Type | |
+| ----- | ---- | --- |
+| `path` | `string \| RegExp` or a list | A string matches as a **prefix**; a regex is tested as written. |
+| `method` | one or more `string` | Upper-case. |
+
+```ts
+{ id: "protect-export", match: { path: ["/api/export", "/reports/"], verdict: "suspected-bot" },
+  action: "challenge" }
+```
+
+## What fired
+
+| Field | Type | |
+| ----- | ---- | --- |
+| `detector` | one or more `string` | Matches if **any** evidence came from one of these. |
+
+```ts
+// Traps are proof. Nothing else needs to be true.
+{ id: "trapped", match: { detector: ["trap"], certain: true }, action: "block" }
+```
+
+## What this actor has done before
+
+| Field | Type | |
+| ----- | ---- | --- |
+| `minPriorConfirmations` | `number` | Times this actor was **proven** a bot before now. |
+| `minUnsolvedChallenges` | `number` | Challenges issued that no solution came back for. |
+
+```ts
+{ id: "repeat-offender", match: { minPriorConfirmations: 3 }, action: "block",
+  reason: "Proven automation three times from this actor." }
+
+{ id: "persistent-refusers", match: { minUnsolvedChallenges: 3 }, action: "rate-limit" }
+```
+
+`minUnsolvedChallenges` is **outstanding rather than cumulative**: solving one clears the
+count, so it never accumulates against somebody who came back and proved it. It is a rule
+rather than evidence on purpose — one abandoned challenge is a person having a moment, and
+what repetition means depends on traffic the library cannot see. See
+[actors](../concepts/actors.md).
+
+## A predicate, for anything else
+
+```ts
+{
+  id: "checkout-under-attack",
+  match: (assessment) =>
+    assessment.facts.path.startsWith("/checkout") &&
+    assessment.score > 50 &&
+    assessment.actor.requests > 20,
+  action: "challenge",
+}
+```
+
+Two things to know. A predicate that **throws** is skipped rather than matched — "unknown"
+cannot safely mean "yes". And a predicate cannot be serialised, so a rule using one is
+shown read-only in the dashboard's editor and spliced back at its original index on save:
+order is the whole semantics, so "wherever it ends up" is not an option.
+
+## Validation
+
+`validateRules` runs at construction and reports what is survivable rather than throwing:
+duplicate ids, a rule shadowed by a broader one above it, an action whose parameters are
+missing. Warnings go to `onWarning` and to the dashboard's notices.
+
+```ts
+import { validateRules } from "@osqd/bothandlerjs";
+validateRules(myRules);   // string[] — empty is good
+```
+
+## Related
+
+- [Actions](actions.md) — what a matched rule can ask for
+- [The safety guard](../concepts/the-guard.md) — what it is allowed to get
+- [Verdicts, classes and scores](../concepts/verdicts.md) — the vocabularies above

package/docs/reference/api.md

@@ -0,0 +1,126 @@
+# API
+
+The methods on `BotHandler`, the entry points, and where each exported name is documented.
+
+← [Documentation](../index.md)
+
+---
+
+## Entry points
+
+| Import | Contains |
+| ------ | -------- |
+| `@osqd/bothandlerjs` | the engine, detectors, presets, robots, stores, notifiers, challenge, dashboard |
+| `@osqd/bothandlerjs/adapters` | [Express, Fastify, Koa, Fetch](../integration/adapters.md) |
+| `@osqd/bothandlerjs/client` | the browser-side [client signals](../detection/client-signals.md) script |
+| `@osqd/bothandlerjs/corpus` | [`runCorpus`](../testing/corpus.md) and the cases |
+| `@osqd/bothandlerjs/cli` | the [command line](../testing/cli.md) entry point |
+
+Zero runtime dependencies, ESM and CJS, types included.
+
+---
+
+## The request path
+
+```ts
+const assessment = await detector.assess(facts, { record: false });
+const decision   = detector.decide(assessment);
+const result     = await detector.handle(facts);   // both, plus the action applied
+```
+
+| Method | |
+| ------ | - |
+| `assess(facts, options?)` | runs detection. `{ record: false }` is a [dry run](../detection/index.md) |
+| `decide(assessment)` | applies the [policy](../policy/index.md) and [the guard](../concepts/the-guard.md). Synchronous and pure |
+| `handle(facts)` | assess + decide + produce an `ActionOutcome` |
+| `createFacts(input)` | builds `RequestFacts` from method, url, headers, `rawHeaders`, ip |
+
+`assess` and `decide` are separate on purpose: *what is this client* and *what should we do
+about it* are different questions with different lifetimes. See [policy](../policy/index.md).
+
+## The challenge
+
+| Method | |
+| ------ | - |
+| `isChallengeEndpoint(facts)` | is this the verification POST? Adapters call it for you |
+| `verifyChallenge(facts, body)` | verify a solution, grant clearance |
+| `grantClearance(facts, level?)` | issue clearance directly — `"operator"` by default |
+
+`grantClearance(facts, "operator")` is how your application vouches for an authenticated
+person. See [the challenge](../challenge/index.md).
+
+## Observation
+
+| Method | |
+| ------ | - |
+| `on(event, handler)` | subscribe; returns an unsubscribe function |
+| `metrics()` | structured snapshot |
+| `prometheus(options?)` | text exposition format |
+| `runAudit()` | run the [audit](../operations/audit.md) checks now |
+| `audit` | the `TrafficAudit` object, with `summary()` |
+| `serveDashboard(options?)` | start [the dashboard](../operations/dashboard.md) on its own port |
+| `describeDetectors()` | id, description, cost and stage for each installed detector |
+
+## Runtime changes
+
+Each takes a trailing `{ by }` — see [runtime changes](../operations/runtime-changes.md).
+
+| Method | |
+| ------ | - |
+| `updatePolicy(rules, ctx?)` | validated, atomic; cannot touch the guard |
+| `updateGuard(settings, ctx?)` | its own method and its own event, deliberately |
+| `updateRanges(name, entries, ctx?)` | allowlist, denylist, datacenter |
+| `updateCrawlerRanges(id, entries, ctx?)` | one crawler's published ranges |
+| `listRanges()` / `rangeEntries(name)` | what is loaded |
+| `forgetActor(key, ctx?)` | drop one [actor's](../concepts/actors.md) memory |
+| `clearActor(key, forMs, ctx?)` | treat an actor as cleared for a while |
+
+## Inspection
+
+`resolveIp`, `actorKeyFor`, `isAllowlisted`, `isIgnoredPath`, `policy`, `warn`.
+
+`warn(message)` is public so warnings raised *outside* the engine — the fetch adapter, the
+crawler-range refresher — reach the same `warning` event as everything else, rather than
+only the `onWarning` callback.
+
+---
+
+## Where the exported names are documented
+
+| Names | Page |
+| ----- | ---- |
+| `BotHandler`, `createFacts`, `resolveConfig`, `validateRules`, `ConfigError` | [Configuration](configuration.md) |
+| `CERTAINTY_WEIGHT`, `combineEvidence`, `noisyOr`, `sortEvidence`, `weightOf` | [Evidence](../concepts/evidence.md) |
+| `VERDICTS`, `BOT_CLASSES` | [Verdicts](../concepts/verdicts.md) |
+| `defaultDetectors`, every `*Detector` factory, `Detector`, `Evidence` | [Detectors](../detection/detectors.md), [writing one](../detection/writing-a-detector.md) |
+| `BOT_SIGNATURES`, `BotSignature`, `BotCategory` | [Signatures](../detection/signatures.md) |
+| `forwardConfirmedReverseDns`, `cachingResolver`, `nodeDnsResolver`, `PUBLISHED_CRAWLER_RANGES`, `refreshCrawlerRanges`, `startCrawlerRangeRefresh` | [Verification](../detection/verification.md) |
+| `PRESETS`, every preset function, `Rule`, `MatchSpec`, `Decision` | [Rules](../policy/rules.md), [presets](../policy/presets.md) |
+| `defineHandler`, `CustomHandler`, `ActionOutcome`, `ACTION_NAMES`, `TERMINAL_ACTIONS` | [Actions](../policy/actions.md) |
+| `generateRobotsTxt`, `robotsFromRules`, `agentFor` | [robots.txt](../policy/robots.md) |
+| `ChallengeService`, `ChallengeOptions`, `ChallengeCopy`, `parseAcceptLanguage`, `pickTranslation` | [The challenge](../challenge/index.md), [localisation](../challenge/localisation.md) |
+| `MemoryStore`, `RedisStore`, `BotHandlerStore` | [Stores](../integration/stores.md) |
+| `consoleNotifier`, `webhookNotifier`, `slackNotifier`, `notifyJsNotifier`, `Notifier` | [Notifications](../operations/notifications.md) |
+| `Metrics`, `toPrometheus`, `SCORE_BUCKETS`, `DURATION_BUCKETS_MS` | [Metrics](../operations/metrics.md) |
+| `TrafficAudit`, `DEFAULT_CHECKS`, `AuditCheck`, `TrafficAnomaly` | [The audit](../operations/audit.md) |
+| `startDashboard`, `createDashboardHandler`, `renderDashboardPage`, `Dashboard*` | [The dashboard](../operations/dashboard.md) |
+| `ActorRegistry`, `ActorState`, `ActorSummary` | [Actors](../concepts/actors.md) |
+| `renderTrapField`, `TRAP_FIELD_SOURCE` | [Detectors](../detection/detectors.md), [adapters](../integration/adapters.md) |
+| `ClientSignals`, the client script | [Client signals](../detection/client-signals.md) |
+
+### The utilities
+
+Exported because they are useful on their own and because a detector you write will want
+them: `IpRangeSet`, `parseIp`, `parseCidr`, `cidrContains`, `normalizeIp`, `formatIp`,
+`isSpecialUse`, `networkKey`, `SPECIAL_USE_RANGES`; `parseUserAgent`, `claimsBrowser`,
+`sendsModernHeaders`; `parseCookies`, `serializeCookie`; `MultiPatternMatcher`, `TtlLru`,
+`Emitter`, `ManualClock`, `systemClock`.
+
+`ManualClock` and a stub `DnsResolver` are what make the [corpus](../testing/corpus.md)
+deterministic, and they will do the same for your tests.
+
+## Related
+
+- [Configuration](configuration.md) — every constructor option
+- [Detection](../detection/index.md) — what `assess` actually runs
+- [Policy](../policy/index.md) — what `decide` actually applies