@osqd/bothandlerjs 0.3.0 → 0.5.0

package/dist/metrics.d.ts

@@ -47,6 +47,18 @@ export interface MetricsSnapshot {
         solved: number;
         rejected: number;
     };
+    /**
+     * Clearance granted, by level, and why the rest were turned down.
+     *
+     * Without these an operator running the interaction challenge is tuning blind. The
+     * split between `pow` and `interaction` says how many clients are clearing the higher
+     * bar; the rejection reasons say whether a rise is bots or a population whose browsers
+     * cannot answer a probe — and those call for opposite responses.
+     */
+    clearances: Record<string, number>;
+    challengeRejections: Record<string, number>;
+    /** Interaction scores, in ten buckets of 0.1. The distribution `interactionAt` sits in. */
+    interactionScores: number[];
     /**
      * How suspicion is distributed across the traffic that was scored.
      *
@@ -91,6 +103,9 @@ export declare class Metrics {
     private challengesIssued;
     private challengesSolved;
     private challengesRejected;
+    private readonly clearances;
+    private readonly challengeRejections;
+    private readonly interactionScores;
     private scoreCount;
     private scoreTotal;
     private readonly scoreBuckets;
@@ -104,6 +119,18 @@ export declare class Metrics {
     recordDetectorTiming(detector: string, ms: number): void;
     recordDecision(decision: Decision): void;
     recordChallenge(event: "issued" | "solved" | "rejected"): void;
+    /** Which clearance a solve earned. */
+    recordClearance(level: string): void;
+    /**
+     * Why a challenge was turned down, bucketed by cause.
+     *
+     * Bucketed rather than recorded verbatim: the reason string carries measured numbers
+     * ("answered in 120ms"), and a counter keyed on those would grow without bound on a
+     * label an attacker controls the shape of.
+     */
+    recordChallengeRejection(reason: string): void;
+    /** The interaction score a solve was graded on, into ten buckets of 0.1. */
+    recordInteractionScore(score: number): void;
     snapshot(actorsTracked: number): MetricsSnapshot;
 }
 export interface PrometheusOptions {

package/dist/policy/index.d.ts

@@ -1,7 +1,7 @@
 export { Policy } from "./policy.js";
 export type { GuardSettings } from "./policy.js";
 export { compileMatch, independentStrongSignals } from "./match.js";
-export { monitorOnly, allowCrawlers, protectContent, declineAiTraining, protectData, protectApi, protectAuth, underAttack, PRESETS } from "./presets.js";
+export { monitorOnly, allowCrawlers, protectContent, declineAiTraining, protectData, protectApi, protectAuth, indexersOnly, underAttack, PRESETS } from "./presets.js";
 export type { PresetName } from "./presets.js";
 export { ACTION_NAMES, TERMINAL_ACTIONS } from "./types.js";
 export type { ActionName, ActionParams, Decision, FalsePositivePolicy, MatchSpec, PolicyOptions, Rule } from "./types.js";

package/dist/policy/presets.d.ts

@@ -111,6 +111,52 @@ export declare function declineAiTraining(): Rule[];
  * challenges one on a content site is deliberately absent.
  */
 export declare function protectApi(): Rule[];
+/**
+ * Indexers welcome, everything else automated is not.
+ *
+ * The strictest permanent posture in this file: a crawler is served only when its
+ * identity has been *confirmed* against its operator's DNS or published ranges, and
+ * only when the job it does is bringing people to the site. Every other proven bot is
+ * refused, and suspicion escalates as far as the guard allows.
+ *
+ * Three things to be clear about before choosing it.
+ *
+ * **Most indexers cannot be verified at all.** Of the search and social signatures the
+ * library ships, twelve publish forward-confirmable DNS — Google, Bing, Yandex, Baidu,
+ * Apple, Sogou, Seznam, Naver, PetalBot, Cốc Cốc, Yahoo, Pinterest — and two more
+ * (DuckDuckBot, Facebook) are checkable only if you supply `crawlerRanges`. The other
+ * twenty-three, Twitterbot, LinkedInBot, Slackbot, Discord, Telegram, WhatsApp,
+ * Reddit, Mastodon and Bluesky among them, publish nothing to check a claim against.
+ * They can never reach `verified-bot`, so `unverifiable-indexer-block` refuses them and
+ * your pages stop getting link previews when somebody shares them. That rule is
+ * deliberately separate and deliberately named: change its action to `rate-limit` and
+ * you serve them at a ceiling instead, which is the trade every site makes differently.
+ *
+ * **A confirmed crawler outside `search` and `social` is refused too** — the AI
+ * crawlers, the SEO tools, the archivers, the uptime monitors, and **your own webhooks,
+ * health probes and server-side renderer**. That last group is how this preset breaks
+ * your own infrastructure on the first deploy; fifteen of the corpus's thirty-three
+ * infrastructure cases are refused by it. Allowlist yours first, by identity or by
+ * address, above everything else:
+ *
+ * ```ts
+ * rules: [{ id: "our-renderer", match: { identity: "our-ssr" }, action: "allow" }, ...indexersOnly()]
+ * ```
+ *
+ * **Suspicion is challenged, not blocked**, and no rule here asks otherwise. Under the
+ * default `strict` guard a `block` on a probabilistic verdict is downgraded to a
+ * challenge anyway, so writing one would express a strictness the engine does not have
+ * while reporting a guard stop on every suspicious request. If you want denial on
+ * suspicion, say so where it is visible — `falsePositivePolicy: "balanced"`, which
+ * additionally demands two independent strong signals — and add the rule that asks:
+ *
+ * ```ts
+ * { id: "high-suspicion-block", match: { verdict: "suspected-bot", minScore: 90 }, action: "block" }
+ * ```
+ *
+ * Some real people will be denied by that. Nothing in this preset does it for you.
+ */
+export declare function indexersOnly(): Rule[];
 /**
  * For while it is happening.
  *
@@ -156,6 +202,7 @@ export declare const PRESETS: {
     readonly "protect-data": typeof protectData;
     readonly "protect-api": typeof protectApi;
     readonly "protect-auth": typeof protectAuth;
+    readonly "indexers-only": typeof indexersOnly;
     readonly "under-attack": typeof underAttack;
 };
 export type PresetName = keyof typeof PRESETS;

package/dist/state.d.ts

@@ -153,7 +153,7 @@ export declare class ActorRegistry {
      * A read, and only a read: it neither records a request against an actor nor moves
      * one up the LRU, so watching the list cannot change what it lists.
      */
-    top(limit: number, now: number): ActorSummary[];
+    top(limit: number, now: number, offset?: number): ActorSummary[];
     forget(key: string): void;
     clear(): void;
     /** Marks an actor as holding valid human clearance until `until`. */

package/docs/challenge/index.md

@@ -146,6 +146,7 @@ and rules can read it:
 
 ## Related
 
+- [The interaction challenge](interaction.md) — asking for a gesture, and probing the browser
 - [Localisation](localisation.md) — showing the page in a language the visitor reads
 - [Actions](../policy/actions.md) — where `challenge` sits on the ladder
 - [The guard](../concepts/the-guard.md) — why it is the ceiling for unproven verdicts

package/docs/challenge/interaction.md

@@ -0,0 +1,325 @@
+# The interaction challenge
+
+A gesture and a browser examination, on top of the proof of work — and a precise account
+of what that is worth.
+
+← [Documentation](../index.md) · [The challenge](index.md)
+
+---
+
+## What it adds
+
+The [proof of work](index.md) demonstrates that a JavaScript engine ran. This asks for two
+more things:
+
+1. **A deliberate gesture** — a checkbox the visitor ticks.
+2. **Evidence that a browser rendered the page** — six probes that read back things only a
+   real rendering engine can produce.
+
+Turn it on with one option:
+
+```ts
+new BotHandler({
+  challenge: {
+    secrets: [process.env.CHALLENGE_SECRET!],
+    contactHtml: '<p>Locked out? Email <a href="mailto:help@example.com">help@example.com</a>.</p>',
+    interaction: true,
+  },
+});
+```
+
+**Solving the puzzle alone no longer grants clearance when this is on.** The gesture is
+required. Read [what it costs people](#what-it-costs-people) before you enable it.
+
+---
+
+## What is actually verifiable
+
+Everything the page reports is client-supplied, and the client is the one place an
+adversary has complete control. Being precise about this is the difference between a
+security control and a decoration.
+
+| Signal | Who says so | Can it be faked? |
+| ------ | ----------- | ---------------- |
+| **Elapsed time between issue and answer** | **the server**, from the signed token's `iat` | **no** |
+| `isTrusted` on the activation | the client | yes, by a browser driven through CDP |
+| Capability probes | the client | yes, by actually having a browser — which is the point |
+| Pointer path | the client | yes, with deliberate effort |
+
+Exactly one row is server-verified. The rest raise cost rather than establish fact.
+
+### The ceiling
+
+Every probe here is answered by the client, and every value a probe asks about has to reach
+the browser in order to be rendered. So anything willing to **parse the page it was served**
+can answer without rendering anything. Measured, five challenges each:
+
+| A client that… | Gets |
+| -------------- | ---- |
+| replays a report captured from a real browser | **0/5** |
+| hardcodes a formula for the layout probe | **0/5** |
+| **parses the served HTML and CSS each time** | **5/5** |
+| actually renders the page | 5/5 |
+
+Read the third row carefully. Against an adversary who writes a parser for your challenge
+page, the interaction challenge adds **nothing over the plain proof of work except the
+server-verified elapsed-time floor**. It is not a defence against somebody targeting you
+specifically, and no client-side probe can be.
+
+**What it does buy**, and this is worth having: it defeats every scraper that does not
+bother — off-the-shelf tooling, `fetch()` in a loop, a report captured once and replayed, a
+naive headless driver with a lerped mouse path. That is the overwhelming majority of
+automated traffic, and for bulk extraction it is often the difference between worth doing
+and not.
+
+Nothing here is proof of humanity, and none of it is ever `certain`. If you need a bar an
+adversary cannot step over by writing a parser, the bar is an account, not a challenge.
+
+---
+
+## The capability probes
+
+Each reads back something that only exists if a rendering engine produced it. An HTTP
+client that parsed the HTML has no answer to any of them.
+
+One of them is different for every challenge. **The layout probe** asks the page to lay out
+a block whose box count and box height are both drawn from the challenge's nonce **under the
+signing secret**, and to report the measured height. The client cannot compute that answer;
+it can only measure it.
+
+An earlier version fixed the height at 7px in the stylesheet and derived the count from the
+nonce in the page's own script, which made the answer a formula an attacker reads once and
+hardcodes for ever — a client that never rendered anything answered it correctly five times
+out of five.
+
+That closes a hole the other probes leave wide open. Every other answer in a report is the
+same from one challenge to the next, so a report captured once from a real browser could be
+replayed against fresh challenges for ever: solve the puzzle headlessly, paste the blob,
+and never run a browser again — skipping precisely the cost this feature exists to impose.
+Measured before the probe existed, one captured report was accepted for **five consecutive
+challenges**; with it, for one.
+
+It is still not proof against somebody who parses the page: both numbers have to reach the
+browser to be rendered, so a parser can find them. What it removes is the *formula* — there
+is no longer a fixed rule to implement once and reuse — and what it stops outright is
+*replay*. See [the ceiling](#the-ceiling).
+
+| Probe | Weight | What it asks |
+| ----- | -----: | ------------ |
+| `cssApplied` | 0.30 | A computed `letter-spacing` that only exists if a CSSOM parsed the stylesheet and ran the cascade |
+| `layout` | 0.20 | A laid-out element has a non-zero box |
+| `fontMetrics` | 0.15 | The same string in two families measures differently — there is a font engine |
+| `animationFrame` | 0.15 | Two frames arrive, a plausible interval apart |
+| `mediaQuery` | 0.10 | A media query evaluates against a real viewport |
+| `hiddenIsHidden` | 0.10 | `display: none` is honoured, not merely parsed |
+
+`cssApplied` carries the most weight because it is the one that separates *the population
+this challenge is aimed at* — HTTP-client scrapers — from browsers. A real browser passes
+every probe, including a headless one; that is expected and is the cost being imposed.
+
+---
+
+## Reading the pointer
+
+When the checkbox is ticked with a pointer, the page sends a bounded, quantised record of
+the movement leading up to it — a rolling window of the **most recent** 128 samples of
+`[dx, dy, dt]`, rounded to two decimal places. Most recent matters: a fixed buffer that
+stopped accepting samples once full kept a reader's idle wandering and discarded the
+approach to the control, which is the one movement the analysis exists to recognise. **The analysis runs on the server.** A page that scored itself would simply
+be asked to report a good score.
+
+Five properties are measured, and they are weighted by *what they cost an attacker who is
+trying*:
+
+| Property | Weight | Naive path | A hand |
+| -------- | -----: | ---------- | ------ |
+| Distance per sample | 0.30 | 0.00 | ~0.60 |
+| Straightness | 0.25 | 1.00 | ~0.85 |
+| Speed variation | 0.15 | 0.00 | ~0.98 |
+| Timing jitter | 0.10 | 0.00 | ~0.50 |
+| Acceleration changes | 0.10 | 0 | many |
+| Sub-pixel coordinates | 0.10 | none | most samples |
+
+**Distance per sample carries the most, and speed carries less than it looks like it
+should.** Speed is distance over time, so jittering the event timing alone manufactures
+speed variation for free — 0.33 on a perfectly straight constant-step path, measured — and
+ragged dispatch timing is exactly what an awaited automation loop produces without trying.
+Distance per sample reads only where the pointer went, so a constant-step path scores zero
+however uneven its timing.
+
+The last two terms are worth little on purpose: bolting random noise onto a straight line
+maxes both out immediately and is nearly free.
+
+A **discontinuity is excluded rather than measured**. A sample arriving more than 250 ms
+after the last one is the pointer reappearing — entering the window, coming back from
+another application, or simply resting — and the distance across that gap is not a distance
+a hand travelled. This matters more than it sounds: a perfectly even synthetic path
+measured through a real browser scored 0.76 on distance variation, indistinguishable from a
+person, because of exactly one sample — the pointer's first appearance, a 60×60 jump
+recorded 1.25 s after load. One outlier in twenty-six.
+
+### How much this actually separates
+
+Fed paths directly, the analysis discriminates sharply:
+
+| Path | Movement score |
+| ---- | -------------: |
+| Constant-velocity interpolation | **0.00** |
+| The same line with random jitter | **0.38** |
+| A short, quick human move | **0.69** |
+| A full human move | **0.93** |
+
+Driven through a **real browser**, it discriminates much less:
+
+| Through Chromium | Movement | Composite |
+| ---------------- | -------: | --------: |
+| A person-like move | 0.75 | 0.90 |
+| Evenly-stepped automation | 0.56 | 0.83 |
+
+That gap is not wide enough to sit a threshold in, and raising `interactionAt` to catch the
+second row would start refusing the first. **So be clear about what the movement analysis
+is for:** it raises the bar for a client that *fabricates* a report without a browser —
+where a lazy path scores 0.00 — and it is only a weak tiebreaker between two clients that
+both really are browsers. The signals doing the load-bearing work against a real browser are
+the server-verified elapsed time and the capability probes.
+
+---
+
+## How the clearance is graded
+
+```
+score = capabilities × 0.6  +  movement × 0.4
+```
+
+| Outcome | Result |
+| ------- | ------ |
+| No interaction reported | **refused** |
+| `isTrusted` false | **refused** |
+| Answered faster than `minElapsedMs` | **refused** |
+| Client claims it took longer than the challenge has existed | **refused** |
+| The path describes more movement than the challenge lasted | **refused** |
+| The layout probe is unanswered, or answers a different challenge | **refused** |
+| Score below `refuseBelow` (0.2) | **refused** |
+| Score at or above `interactionAt` (0.75) | `interaction` clearance |
+| Anything in between | `pow` clearance |
+
+`bothandler_interaction_score_bucket` counts refusals as well as successes. A distribution
+fed only from what already passed has everything below the threshold cut out of it, which
+is the part of the shape the threshold decision actually turns on.
+
+Rejections name the probes that failed rather than only counting them — `capabilities 70%
+(missing: fontMetrics, animationFrame)`. A percentage says something is wrong; the names say
+whether it is bots or a population whose browsers cannot answer one particular question, and
+those call for opposite responses.
+
+`interactionAt` is set from measurement rather than taste. Fed a fabricated
+constant-velocity path a client scores **0.60**, and a person in a browser scores **0.90**;
+the bar sits between them. It does **not** separate crude automation inside a real browser
+from a person — see the table above — and it is not set as though it does.
+
+The [`clearance` detector](../detection/detectors.md) then reads the level: `interaction`
+is `strong` human evidence at weight 0.7, `pow` is `moderate` at 0.45.
+
+### A keyboard is never penalised
+
+A pointer path is worth something, and its **absence is worth nothing either way**. Voice
+control produces no pointer movement. Switch access produces machine-regular timing. A
+screen reader activates the control from the keyboard.
+
+Scoring those down would put assistive technology on the wrong side of a check the rest of
+this library exists to keep people out of. So a keyboard or unclassified activation is
+graded on its capabilities and its timing alone.
+
+The consequence, stated plainly: **claiming keyboard activation is the cheapest way
+through, and it costs a real browser.** That is the floor this feature raises, and it is
+deliberate. The alternative — penalising the absence of mouse movement — refuses people
+for how they use a computer.
+
+A **tap is not a mouse**, and is reported as its own thing. Touch produces almost no
+`pointermove` — one sample, frequently none — so classifying a tap as a pointer would score
+it zero for movement and quietly grade every phone down to the weaker clearance. The page
+reads `click.detail`, which the platform sets to 0 for a keyboard activation and to the
+click count for a pointer, and takes the device from `pointerdown`.
+
+A path **too short to describe is no evidence, not bad evidence**. Somebody whose cursor
+already rested on the control, or who nudged it a few pixels, is graded on capabilities like
+a keyboard or a tap.
+
+Scoring that as zero was tried first, on the reasoning that a pointer activation showing no
+movement describes something that did not happen. Measured, it was wrong in both directions
+at once: it downgraded honest clients, and it caught nobody — `via` is a field the client
+fills in, so an attacker with no path to show simply writes `keyboard` and is graded on
+capabilities like everybody else. A rule that only ever costs honest people something is not
+strictness.
+
+The discrimination that does work is untouched: a path of four samples or more that looks
+interpolated scores zero, and that is a claim about movement the client *did* report.
+
+---
+
+## Tuning
+
+```ts
+challenge: {
+  secrets: [SECRET],
+  interaction: {
+    minElapsedMs: 1000,   // server-measured floor between issue and answer
+    interactionAt: 0.75,  // at or above this, grant `interaction`
+    refuseBelow: 0.2,     // below this, refuse outright
+  },
+}
+```
+
+**`challengeTtlMs` defaults to ten minutes when the gesture is on**, rather than the two
+the plain challenge uses. Two minutes is the right budget for a puzzle a machine solves in
+milliseconds; it is the wrong one for a page that stops and waits for a person to read it
+and act. Somebody using a screen reader that announces the whole page, on a slow device
+where the proof of work itself takes twenty seconds, or simply interrupted, runs out and is
+told to reload — having done nothing wrong and with no way to know why.
+
+`minElapsedMs` is the one worth raising during an incident. It is server-verified, so it is
+a hard ceiling on how fast a farm can work through challenges however many browsers it
+runs — and it costs a real visitor nothing, because a person takes longer than a second to
+read a page and tick a box anyway.
+
+---
+
+## What it costs people
+
+The gesture is a **checkbox**, and that choice is the whole accessibility argument. It is
+the one interactive control that every way of using a computer can operate: pointer, touch,
+the space bar, a screen reader, switch access, voice control. A slider, a press-and-hold or
+an image puzzle would each exclude somebody.
+
+The interstitial with the gesture is axe-audited in both themes at every release, the
+control has a real `<label>`, and the page moves focus to it when the puzzle finishes so
+that a keyboard user is put on the one remaining action rather than having to go looking.
+
+**Who still cannot get through:** anyone without JavaScript or WebCrypto, and anyone whose
+browser cannot run the probes — a text-mode browser, for instance. They could not complete
+the plain proof of work either, so this changes nothing for them, and `contactHtml` remains
+their route. Supply a real one.
+
+When the page gives up, **it withdraws the checkbox** rather than leaving it on screen. A
+live control that cannot work offers a way through that does not exist, and it is worst for
+somebody using a screen reader, who would find it, activate it, and be told nothing.
+
+## Why not an image puzzle
+
+Because they no longer work and they exclude people.
+
+Machine learning solves image grids more accurately than humans do, and solving farms
+charge about a dollar per thousand — so a visual CAPTCHA adds friction for people and a
+rounding error for attackers. It also locks out blind and low-vision users, motor
+impairments and cognitive disabilities.
+
+The [guard](../concepts/the-guard.md) permits a `challenge` on a *guess* precisely because
+the client can pass it on its own. For somebody who cannot see the puzzle, that is not a
+challenge — it is a block, delivered on a guess. This library will not ship one.
+
+## Related
+
+- [The challenge](index.md) — the proof of work this builds on
+- [Localisation](localisation.md) — the interstitial in a language the visitor reads
+- [Client signals](../detection/client-signals.md) — the same reasoning, on ordinary pages
+- [Threat model](../concepts/threat-model.md) — what none of this can do

package/docs/course/11-the-challenge.md

@@ -133,6 +133,41 @@ Passing a challenge cannot change a proven verdict, so re-issuing would loop for
 **Challenging on an API** breaks your customers' integrations and stops nobody — see
 `protect-api` in [lesson 10](10-actions-and-presets.md).
 
+## Asking for a gesture as well
+
+The proof of work shows a JavaScript engine ran. One option asks for two more things — a
+deliberate gesture, and evidence that a *browser* rendered the page:
+
+```js
+challenge: {
+  secrets: [process.env.SERIF_CHALLENGE_SECRET],
+  contactHtml: "<p>…</p>",
+  interaction: true,
+}
+```
+
+The interstitial grows a checkbox, and six probes read back things only a rendering engine
+produces — a computed style that needs the cascade to have run, a laid-out box, font
+metrics, a frame loop. **Solving the puzzle alone no longer grants clearance**: the gesture
+is required, and passing grants the stronger `interaction` clearance rather than `pow`.
+
+The control is a checkbox rather than a slider or a puzzle for one reason: it is the only
+interactive element every way of using a computer can operate — pointer, touch, the space
+bar, a screen reader, switch access, voice control.
+
+**Be clear about what it buys.** It does not prove a person. What it does is move a scraper
+from `fetch()` in a loop to running a browser engine and rendering CSS per request, which
+is three or four orders of magnitude more expensive. Exactly one signal in the exchange is
+server-verified and cannot be faked: the elapsed time between issuing the challenge and
+receiving the answer, taken from the signed token.
+
+Watch it with the counters it emits — `bothandler_clearances_total{level=…}`,
+`bothandler_challenge_rejections_total{cause=…}` and `bothandler_interaction_score_bucket`.
+Without the score distribution, moving the threshold is guessing.
+
+See [the interaction challenge](../challenge/interaction.md) for the full account,
+including where its movement analysis stops working.
+
 ## Unsolved challenges as a signal
 
 Every issued-and-never-solved challenge is counted on the [actor](07-actors.md):
@@ -221,7 +256,7 @@ browser" over an English "email us" is half a fix.
 
 ## Reference
 
-- [The challenge](../challenge/index.md) · [Localisation](../challenge/localisation.md)
+- [The challenge](../challenge/index.md) · [The interaction challenge](../challenge/interaction.md) · [Localisation](../challenge/localisation.md)
 - [Actions](../policy/actions.md) — where `challenge` sits
 
 Next: [Going live](12-going-live.md).

package/docs/course/13-operating-it.md

@@ -63,6 +63,23 @@ That combination is worth understanding. The dashboard people watch all day need
 one that names individuals, or the one that explains your detection to whoever is scraping
 you.
 
+**It does not have to be its own page.** The same dashboard is also a custom element, so it
+can live inside the admin tool your team already opens, rather than behind a second link
+they have to remember:
+
+```html
+<bot-dashboard src="/_bots"></bot-dashboard>
+<script type="module">
+  import { defineBotDashboard } from "@osqd/bothandlerjs/element";
+  defineBotDashboard();
+</script>
+```
+
+`sections` and `redact` above still apply — they are enforced on the server, and embedding
+changes nothing about that. What the element adds is which screens appear and how it looks.
+[Embedding it](../operations/embedding.md) has the whole of it, including what putting the
+dashboard inside your own page costs you.
+
 ## Metrics
 
 On by default; a handful of integer increments per request.
@@ -232,7 +249,8 @@ miss.
 
 ## Reference
 
-- [The dashboard](../operations/dashboard.md) · [Metrics](../operations/metrics.md)
-- [The audit](../operations/audit.md) · [Notifications](../operations/notifications.md)
+- [The dashboard](../operations/dashboard.md) · [Embedding it](../operations/embedding.md)
+- [Metrics](../operations/metrics.md) · [The audit](../operations/audit.md)
+- [Notifications](../operations/notifications.md)
 
 Next: [Scaling and changing it live](14-scaling.md).

package/docs/detection/signatures.md

@@ -41,6 +41,18 @@ individual name does not.
 | `library` | curl, wget, python-requests, Go-http-client, okhttp | usually challenge |
 | `headless` | HeadlessChrome, Playwright, Puppeteer, Selenium | usually challenge |
 | `embedded` | Smart TVs, set-top boxes, game consoles | allow |
+| `commerce` | idealo, Kelkoo, PriceRunner, Trivago, Skyscanner, Indeedbot | a commercial decision |
+| `academic` | Crossref, OpenAlex, university web-science crawls | usually allow |
+| `accessibility` | Siteimprove and other WCAG auditors | allow |
+
+The last three are separate from their nearest neighbours because the decision is. A price
+comparator is not an SEO auditor — nothing there is auditing your site for you, and the
+same crawler is a distribution channel to one retailer and a competitor's research tool to
+the next, which is why nothing in `commerce` is marked benign. A citation index is not a
+model being trained, and an operator refusing the second is often glad of the first. And an
+accessibility crawler is not an uptime probe: it is usually commissioned by the site's own
+owner and then forgotten about, so blocking it does not reduce load, it makes an
+accessibility report look clean by removing the evidence.
 
 ```ts
 { id: "no-ai", match: { category: "ai" }, action: "block", reason: "Not for model training." }
@@ -54,6 +66,7 @@ What, if anything, can check the claim:
 type Verification =
   | { kind: "fcrdns"; domains: readonly string[] }   // reverse DNS, forward-confirmed
   | { kind: "ip-ranges"; publishedAt?: string }      // an address list the operator publishes
+  | { kind: "proof"; via: string }                   // something only you can check
   | { kind: "none" };                                // no published mechanism
 ```
 
@@ -62,6 +75,29 @@ them, and for those the claim is **unfalsifiable**. The library neither confirms
 accuses — it records what the client said and lets the policy decide what a self-declared
 identity is worth. See [verifying a crawler](verification.md).
 
+**But you may be able to check what this library cannot.** Your CDN has often already
+verified the crawler and says so in a header it adds; some bots now sign their requests;
+you may hold ASN data. None of those belong inside a detection library — two need a
+network dependency and the third needs a key it has no business fetching — so instead you
+supply the answer:
+
+```ts
+new BotHandler({
+  crawlerVerification: {
+    verifiers: {
+      // Whatever you can prove, however you prove it.
+      gptbot: (ctx) => (ctx.facts.headers["cf-verified-bot"] === "gptbot" ? "verified" : "unknown"),
+    },
+  },
+});
+```
+
+A verifier returns `"verified"`, `"refuted"` or `"unknown"`, runs before the built-in check
+for that signature, and a definite answer settles it — which also means no DNS lookup.
+`"unknown"` falls through to whatever the library can do on its own, and so does a throw:
+an unreachable key server must never read as an accusation, or an outage becomes a wave of
+blocked crawlers.
+
 ## What a name is worth
 
 A matched signature makes `self-identified` produce `certain` evidence, and this is the

package/docs/index.md

@@ -59,6 +59,7 @@ Read these once and everything else follows from them. They are short.
 | | |
 | --- | --- |
 | [The challenge](challenge/index.md) | Proof of work, clearance, and exactly what it buys. |
+| [The interaction challenge](challenge/interaction.md) | A gesture and a browser examination, and exactly what they are worth. |
 | [Languages](challenge/localisation.md) | Writing the interstitial in a language the visitor reads. |
 
 ## Running it
@@ -67,6 +68,7 @@ Read these once and everything else follows from them. They are short.
 | --- | --- |
 | [Operations overview](operations/index.md) | What to watch, and what to do when it moves. |
 | [The dashboard](operations/dashboard.md) | What it shows, what it refuses to do, and every option it takes. |
+| [Embedding it](operations/embedding.md) | `<bot-dashboard>` in a page you already have: screens, themes, panels of your own. |
 | [Metrics](operations/metrics.md) | Counters, histograms and the Prometheus exposition. |
 | [The traffic audit](operations/audit.md) | Watching the shape of your traffic rather than any one request. |
 | [Notifications](operations/notifications.md) | Getting told, without being told a thousand times. |