@osqd/bothandlerjs 0.5.0 → 0.7.0

package/docs/detection/shadow-mode.md

@@ -0,0 +1,147 @@
+# Shadow mode
+
+Run a detector on every request and let it decide nothing. Then read what it would have
+done, from your own traffic, before it does it.
+
+← [Documentation](../index.md) · [Detection](index.md)
+
+---
+
+## The problem it solves
+
+Every detector ships with thresholds somebody chose. They were chosen against a corpus of
+real traffic and they are defensible — and they were not chosen against *your* traffic,
+which is the only traffic that matters when the question is whether a threshold is about
+to start challenging your customers.
+
+The [correlation detectors](correlation.md) make this sharp, because several of them fire
+at `moderate` on real people **by design**:
+
+- a phone moving between wifi and cellular presents one marker from many networks, which
+  is what `marker-fanout` counts;
+- a crowd arriving on a link somebody posted wrong all request the same missing page,
+  which is what `path-campaign` counts;
+- tapping "Request desktop site" changes the platform a client claims, which is what
+  `identity-drift` counts.
+
+None of those is a bug. Each is a real observation with a real innocent explanation, and
+whether the threshold separating them is right *here* is not a thing this library can
+know. Shadow mode is how you find out without anybody being turned away while you do.
+
+```js
+const handler = new BotHandler({
+  preset: "protect-content",
+  site: {},
+  probe: { secrets: [process.env.MARKER_SECRET] },
+  shadowDetectors: ["path-novelty", "marker-fanout", "path-campaign"],
+});
+```
+
+Those three now run on every request exactly as they otherwise would. Their findings are
+counted, charted, and readable in the dashboard next to the evidence that did decide.
+And they decided nothing.
+
+## What "decided nothing" means, precisely
+
+A shadowed detector cannot affect:
+
+| | |
+| --- | --- |
+| the verdict | including via `certain` evidence, which does not go through scoring at all |
+| the score and the confidence | its findings are not in the arithmetic |
+| the bot class and the identity | the class is picked from evidence that counted |
+| any rule | a rule matching `detector: "path-novelty"` does not match a shadowed one |
+| anything downstream of a verdict | the guard, the action, the challenge, `recordOutcome` |
+
+This is not a weight of zero, and the difference is the whole design. A weight is
+consulted on the **probabilistic** path; `certain` evidence never reaches that path,
+because it short-circuits scoring and returns `confirmed-bot` on its own — which is what
+makes a terminal action permissible. A shadowed detector emitting `certain` would have
+blocked people with its weight sitting at zero the entire time.
+
+So the evidence is kept out of the arithmetic rather than weighted inside it. It lands in
+`assessment.shadowEvidence`, which nothing that decides anything reads:
+
+```js
+const assessment = await handler.assess(facts);
+
+assessment.evidence;        // what decided this request
+assessment.shadowEvidence;  // what the shadowed detectors said, flagged with `shadow: true`
+assessment.shadowVerdict;   // what the verdict would have been if they had counted
+```
+
+## The number that actually answers the question
+
+`shadowVerdict` is the point. "It fired 312 times" is not a thing anybody can act on; what
+you need to know is what turning it on would *do*, and the honest form of that is the
+verdict each request would have received.
+
+It is computed only when a shadowed detector found something, so a well-behaved one costs
+nothing on the requests it is silent about — and a badly-behaved one is the case you
+wanted to hear about anyway.
+
+```js
+if (assessment.shadowVerdict?.verdict !== assessment.verdict) {
+  log.info({ was: assessment.verdict, wouldBe: assessment.shadowVerdict?.verdict }, "shadow");
+}
+```
+
+## Reading it
+
+**In the dashboard.** Shadowed findings appear in the evidence list for each request,
+dimmed and labelled *"shadowed: counted, and part of no decision"*, with a line beneath
+saying what the verdict would have been. The Statistics tab counts them separately from
+real firings and reports how many verdicts they would have moved, by the verdict they
+would have produced.
+
+**In Prometheus**, only when something is shadowed:
+
+```
+bothandler_shadow_firings_total{detector="path-novelty"} 312
+bothandler_shadow_verdict_changes_total{verdict="suspected-bot"} 41
+```
+
+Forty-one against a `human` count that did not move is the shape of a detector about to
+start challenging people. That is the reading this exists to make possible.
+
+**In `detectors()`**, a shadowed detector is marked, so `describeDetectors()` and the
+dashboard's detector list both say so even before it has fired once.
+
+## How to use it
+
+1. Turn a detector on in shadow, alongside the policy you are already running.
+2. Leave it a week. A week, not a day: the traffic that catches a threshold out is the
+   Monday morning, the campaign, the outage, the release.
+3. Read `shadow_verdict_changes_total`. If it would have moved requests to
+   `suspected-bot` or `confirmed-bot`, find them in the dashboard and read them — one at
+   a time, as requests, not as a number.
+4. Either adjust the threshold and go back to step 2, or take it out of
+   `shadowDetectors`.
+
+This is the same shape as [`monitor-only`](../policy/presets.md#monitor-only) and
+[`replay`](../testing/replay.md), and it answers the question those two cannot: *what
+happens when I add something new to a policy that is already running*.
+
+## The honest limits
+
+**A shadowed detector still consumes its budget.** It runs, it is timed, and if it throws
+or times out that is recorded like any other failure. Shadowing is about influence, not
+about cost.
+
+**It still writes to actor state, if it writes to actor state.** Detectors are supposed to
+report rather than record — the recording that matters happens in the pipeline around them
+— but a custom detector that mutates `ctx.state` in `inspect` will do so shadowed or not.
+The bundled ones do not.
+
+**Naming a detector that is not installed is a warning, not an error.** The usual cause is
+a typo, and a typo here is otherwise invisible: nothing was going to run, so nothing looks
+any different either way. The warning is checked after the handler has finished installing
+detectors, because the marker, site and challenge detectors arrive with the source they
+read — and those are exactly the ones worth shadowing.
+
+## Related
+
+- [The detectors](detectors.md) — what each one reads, and its ceiling
+- [Correlation](correlation.md) — the sources whose thresholds this exists to check
+- [Metrics](../operations/metrics.md) — the counters, in full
+- [Choosing a policy](../start/choosing-a-policy.md) — the same caution, one level up

package/docs/detection/signatures.md

@@ -6,7 +6,7 @@ How a client is recognised by name, and what a name is worth.
 
 ---
 
-161 signatures, 389 tokens, matched in a single Aho–Corasick pass over the lower-cased
+205 signatures, 389 tokens, matched in a single Aho–Corasick pass over the lower-cased
 User-Agent. One pass regardless of how many signatures there are, which is why adding to
 this costs nothing measurable.
 
@@ -44,8 +44,16 @@ individual name does not.
 | `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 |
+| `email-security` | Proofpoint, Mimecast, Barracuda, Cisco Secure Email | allow |
 
-The last three are separate from their nearest neighbours because the decision is. A price
+`email-security` is a mail or messaging gateway checking a link somebody was sent, before
+they are allowed to click it — and it is separate because of who pays when it is blocked. A
+social preview that fails costs a card; one of these failing tells a real person, in their
+inbox, that their mail contained a link that could not be verified, and they were never the
+one crawling. They arrive with none of a browser's marks — from a datacentre, once, no
+cookie, no referer — because the request is automation acting on a human's behalf.
+
+The other 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

package/docs/index.md

@@ -38,10 +38,11 @@ Read these once and everything else follows from them. They are short.
 | | |
 | --- | --- |
 | [How detection works](detection/index.md) | The pipeline: stages, budgets, failure, and what an assessment contains. |
-| [The detectors](detection/detectors.md) | All twenty, each with what it reads, why it exists, and what it costs. |
+| [The detectors](detection/detectors.md) | All twenty-two, each with what it reads, why it exists, and what it costs. |
 | [The signature database](detection/signatures.md) | How a client is recognised by name, and what a name is worth. |
 | [Verifying a crawler](detection/verification.md) | Reverse DNS, published address ranges, and refuting a forgery. |
 | [Browser signals](detection/client-signals.md) | The optional page script, and the ceiling on anything it reports. |
+| [Shadow mode](detection/shadow-mode.md) | Run a detector without letting it decide anything, and read what it would have done. |
 | [Writing a detector](detection/writing-a-detector.md) | The contract, and the rules about certainty you have to keep. |
 
 ## Policy
@@ -89,7 +90,7 @@ Read these once and everything else follows from them. They are short.
 | --- | --- |
 | [Testing overview](testing/index.md) | The three ways to find out what a policy does before it does it. |
 | [The command line](testing/cli.md) | `replay`, `check`, `explain`, `robots`, `detectors`. |
-| [The traffic corpus](testing/corpus.md) | 526 shapes of real traffic, and how to run your own config against them. |
+| [The traffic corpus](testing/corpus.md) | 548 shapes of real traffic, and how to run your own config against them. |
 | [Replaying your own logs](testing/replay.md) | The most useful thing you can do before deploying anything. |
 | [Try it locally](testing/try-it.md) | A demo site, a live dashboard and eighteen scripted clients. |
 

package/docs/integration/client-ip.md

@@ -56,6 +56,22 @@ holds.
 Invalid CIDRs throw at construction rather than matching silently. A range that matches
 nothing is a control you believe you have and do not.
 
+## Ports in the forwarded header
+
+Most proxies write a bare address. Azure's Application Gateway and Front Door write
+`1.2.3.4:5678`, and RFC 7239 spells IPv6 as `[2001:db8::1]:5678`. Both are read correctly:
+the port is removed before the address is parsed.
+
+This matters more than it sounds. Every entry in such a chain carries a port, so an
+implementation that cannot read one reads *none* of them — the chain empties, and every
+client behind that proxy resolves to the proxy's own address. They then share one actor,
+one history and one rate-limit bucket, so a single bot is enough to lock out every real
+visitor, and nothing about it looks like a failure.
+
+A bare IPv6 address is made of colons, so only two shapes are treated as carrying a port:
+a bracketed host, and a single colon whose left side is an IPv4 address. `2001:db8::1` and
+`::1` are addresses, not hosts with ports.
+
 ## The peer is checked too
 
 The connecting peer counts as the first hop and is checked the same way.

package/docs/operations/dashboard.md

@@ -29,6 +29,13 @@ User-Agent, the verdict, the score, the action and the rule that chose it. Filte
 proven, suspected, human, guard stops, denied, mitigated or served; or type into the
 search box.
 
+**The window.** The **From** and **To** boxes above the feed take absolute instants, and
+either may be left empty — which is what makes one control answer all three of the
+questions people actually ask: from the moment an incident started until now, everything up
+to when it stopped, or between two moments. They read and write local time, the same clock
+the rows show. The charts keep showing their own rolling window; this narrows the feed, the
+counts and the export.
+
 The feed pages, fifty requests at a time. The newest page follows the stream; stepping
 back holds the list still while you read it — a feed that renumbers itself under somebody
 paging through it cannot be read — and says **held while you read** so the stillness is
@@ -46,6 +53,9 @@ score:>70 -certain                   probabilistic traffic close to the line
 "GET /api/v2/orders"                 a phrase, spaces and all
 ```
 
+The whole language, with every field and worked examples, is in [the filter
+reference](filters.md).
+
 Fields: `path` `actor` `ua` `verdict` `action` `rule` `detector` `identity` `method`
 `class` `id` `bypass` `outcome` `certain` `score`. Every term must match — narrowing
 means `AND` — and anything that is not a field term is matched against the whole
@@ -114,14 +124,43 @@ regularity (near zero is a metronome, which no person is), prior confirmations,
 whether they hold clearance. **In feed** sends one to the live feed as an `actor:` filter,
 which makes it a shareable URL like every other view.
 
+**Tracked, or shown in the feed.** The toggle above the table chooses which population
+you are looking at. *Tracked* is the registry — the default, and the one that answers "who
+is hitting me hardest". *Shown in the feed* lists only the clients that appear in the feed
+as you have currently filtered it, so once a filter is on it answers the other question:
+who is in *this*. It is derived from rows the page already holds, so it narrows with the
+search, the chips and the window without another request.
+
+Three columns go blank in that view rather than being filled in. Per minute, cadence and
+unsolved challenges are properties of a client's whole history as the engine sees it, and
+the feed's ring holds a few hundred requests rather than that history — computing them
+from the slice would put a confident number under a heading that means something else. A
+dash says "ask the registry", which is the other half of the toggle.
+
 This screen pages too, twenty-five at a time, busiest first. The registry holds far more
 clients than the feed's ring holds requests, and paging is what reaches them: the feed
 already shows you what is loudest, and the population behind it is the reason this screen
 exists. Ranking something that is still moving means a client can shift between pages
-while you read; the order is a snapshot of a live list, not a stable index.
+while you read; the order is a snapshot of a live list, not a stable index. Paging belongs
+to the registry: the feed-scoped view is built from what is already on screen, so there is
+nothing behind it to page to.
 
 The **Actors tracked** counter above the tab strip is the way in: it is a button, so
 pressing it — or reaching it with the keyboard and pressing Enter — opens this screen.
+
+**Labels.** An address is not a memory. Whoever works out that `198.51.100.4` is a
+partner's price feed can write that down with **Label**, and it shows wherever that actor
+appears — with the key still underneath it, because the key is what you search for. Labels
+can also be set from code, which is the better place for what a deployment already knows:
+
+```ts
+handler.labelActor("198.51.100.4", "partner price feed");
+handler.labelActor("198.51.100.4", undefined);   // and back again
+```
+
+**Detection never reads a label.** That separation is deliberate: the moment a note can
+change a verdict, writing notes becomes a way to be wrong about people at scale. A label
+lives exactly as long as the actor does.
 Where the `registry` section is switched off there is no Actors screen to open, and the
 counter stays an ordinary tile rather than offering to go somewhere that does not exist.
 

package/docs/operations/filters.md

@@ -0,0 +1,143 @@
+# The feed filter
+
+The search box above the live feed takes a small query language. It is the same language
+everywhere it appears — the feed, the export, a shared link — so a filter that finds
+something can be sent to somebody else and will find the same thing.
+
+An empty query matches everything. Adjacent terms mean `AND`, because that is what
+narrowing means — and `$or`, `$not` and set membership are there for when it is not.
+
+## Terms
+
+| Form | Means |
+| --- | --- |
+| `checkout` | the text appears anywhere in the request |
+| `path:/api` | the path contains `/api` |
+| `-path:/health` | the path does **not** contain `/health` |
+| `"GET /api/v2/orders"` | the phrase, spaces and all |
+| `score:>70` | a numeric comparison |
+
+Negation is `-` or `!`, and works on any term. Quoting keeps spaces together, which is the
+only way to search for a phrase.
+
+## Operators
+
+| Form | Means |
+| --- | --- |
+| `a $and b` | both — the same as writing them next to each other |
+| `a $or b` | either |
+| `$not a` | not — the same as `-a`, spelled out |
+| `path:$in(/health, /metrics)` | the path contains any of these |
+| `action:$notin(allow, tag)` | the action contains none of these |
+| `(a $or b) $and c` | grouping |
+
+`$not` binds tightest, then `$and`, then `$or` — the conventional precedence, so
+`a $or b $and c` reads as `a $or (b $and c)`. Brackets are there for the times that is not
+what you meant.
+
+**Operators carry a `$` for a reason.** A bare `or` is a word that appears in User-Agents
+and in paths — `header-order` contains one — and a language where an ordinary search word
+silently becomes an operator is a language that lies about what it matched. Typing `or`
+searches for the text `or`.
+
+Nothing you can type is an error. The box filters as you type, so half-written input is
+the normal state rather than a mistake: an unclosed bracket, a dangling `$or`, a `$in(`
+with nothing after it yet all parse to the best available reading of what is there.
+
+An empty set matches nothing rather than everything, for the same reason — `$in()` is a
+query somebody is halfway through, and a filter that widens while you are still typing it
+is a filter that lies.
+
+A colon with an unknown name in front of it is *not* a field term — a path can contain a
+colon and so can a User-Agent — so `foo:bar` searches for the text `foo:bar`.
+
+## Fields
+
+| Field | Also | Matches against |
+| --- | --- | --- |
+| `path` | `url` | the request path |
+| `actor` | `ip` | the actor key, usually the address |
+| `ua` | `useragent`, `agent` | the User-Agent string |
+| `verdict` | | `confirmed-bot`, `verified-bot`, `suspected-bot`, `human`, `unknown` |
+| `class` | `botclass` | `scanner`, `scraper`, `impersonator`, `http-client`, `automation`, … |
+| `action` | | what was decided: `allow`, `challenge`, `block`, `tag`, … |
+| `outcome` | | the coarse version: `deny`, `mitigate`, `allow`, `pending` |
+| `rule` | | the rule id that decided it |
+| `detector` | | any detector that produced evidence on this request |
+| `identity` | | the named bot, such as `googlebot` |
+| `method` | | `GET`, `POST`, … |
+| `certain` | | `true` or `false` — whether the verdict rests on proof |
+| `bypass` | | why detection was skipped, when it was |
+| `id` | `request` | the request id |
+| `score` | | 0–100. Takes `>` and `<` as well as `=` |
+
+`score` is the only numeric field. `score:>70`, `score:<20` and `score:60` all work;
+everything else matches a substring, case-insensitively.
+
+## Worked examples
+
+```text
+actor:203.0.113.4 -path:/health      that address, except its health checks
+rule:no-scrapers action:tag          the rule that fired, and what it settled on
+score:>70 -certain                   probabilistic traffic close to the line
+detector:trap                        everything that touched a trap
+class:impersonator verdict:confirmed-bot   proven forgeries
+outcome:deny -class:scanner          denials that were not scanners
+"GET /api/v2/orders"                 a phrase
+```
+
+## The chips
+
+The row of buttons — **All**, **Proven**, **Suspected**, **Human**, **Guard stops**,
+**Denied**, **Mitigated**, **Served** — is a separate filter that combines with the query
+rather than replacing it. Picking **Denied** and typing `path:/api` gives you denials on
+`/api`.
+
+## Saved filters
+
+Anything you can type can be saved by name and recalled from the dropdown beside the box.
+Saved filters live in **your browser**, not on the server: they are yours, they do not need
+a write endpoint, and clearing site data clears them. They record the query *and* the chip,
+because a filter is usually both.
+
+## Hiding traffic
+
+There is no separate exclusion list. `$not` does the job:
+
+```text
+$not path:/health                       everything except health checks
+path:$notin(/health, /metrics)          except either of two
+$not (path:/health $or ua:kube-probe)   except anything matching either
+```
+
+This used to be a button that kept its own hidden list in your browser. One mechanism is
+better than two, and this one is in the URL like every other narrowing — so a view with
+the noise taken out is a link you can send somebody rather than a setting only you have.
+
+Hidden traffic is still assessed, still counted in the metrics, and still acted on. A
+filter hides it from *your screen*; it does not stop the engine seeing it.
+
+## Completion
+
+The box completes as you type. Field names come from the parser's own list, so anything it
+offers is something the language accepts — and fields whose values are a closed set
+(`verdict`, `class`, `action`, `outcome`, `certain`, `method`) complete their values too.
+`rule`, `identity` and `path` take anything, so nothing is offered for them: guessing there
+would be inventing options rather than completing them.
+
+A token beginning with `$` completes to an operator, and a closed-set field offers `$in(`
+and `$notin(` alongside its values — because a field with a fixed set of values is exactly
+the field somebody wants two of.
+
+Arrow keys move, Enter or Tab accepts, Escape closes.
+
+## The window
+
+**From** and **To** take absolute instants and either may be left empty, which is what lets
+one control answer "from the incident until now", "everything up to when it stopped" and
+"between these two moments". They use local time, the same clock the rows show.
+
+## Related
+
+- [The dashboard](dashboard.md) — the screens, and what each one is for
+- [Embedding it](embedding.md) — the same dashboard inside your own page

package/docs/operations/index.md

@@ -99,4 +99,5 @@ want the raw event, take it here.
 
 - [Metrics](metrics.md) · [The audit](audit.md) · [Notifications](notifications.md)
 - [The dashboard](dashboard.md) — all of the above, rendered
+- [The feed filter](filters.md) — the query language, saved filters and exclusions
 - [Configuration reference](../reference/configuration.md)

package/docs/operations/metrics.md

@@ -67,8 +67,26 @@ nineteen together.
 
 Switch metrics off entirely with `metrics: false`.
 
+## The counters that appear only when something is shadowed
+
+A detector named in [`shadowDetectors`](../detection/shadow-mode.md) runs and decides
+nothing, so its firings are counted apart from the ones that decided something. Folding
+them together would put work into a chart of decisions that made none.
+
+```
+bothandler_shadow_firings_total{detector="path-novelty"} 312
+bothandler_shadow_verdict_changes_total{verdict="suspected-bot"} 41
+```
+
+The second is the one to read. It counts the assessments the shadowed detectors *would
+have moved*, keyed by the verdict they would have produced — so forty-one would-be
+`suspected-bot`s against a `human` count that did not move is the shape of a detector
+about to start challenging people. Both are absent from the output entirely while nothing
+is shadowed, rather than sitting at zero.
+
 ## Related
 
 - [The audit](audit.md) — because a counter cannot tell you a number is *unusual*
 - [The guard](../concepts/the-guard.md) — what `bothandler_downgrades_total` is counting
+- [Shadow mode](../detection/shadow-mode.md) — running a detector without letting it decide
 - [The dashboard](dashboard.md) — these numbers, drawn

package/docs/policy/presets.md

@@ -241,4 +241,4 @@ npx @osqd/bothandlerjs check --preset protect-auth
 - [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
+- [The corpus](../testing/corpus.md) — 548 cases, including the ones these presets get wrong

package/docs/start/choosing-a-policy.md

@@ -81,7 +81,7 @@ npx @osqd/bothandlerjs check --preset protect-content --audience human
 npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
 ```
 
-The first is [526 shapes of real traffic](../testing/corpus.md); the second is *yours*. Both
+The first is [548 shapes of real traffic](../testing/corpus.md); the second is *yours*. Both
 print every request the policy would have refused, with the evidence.
 
 For your own configuration rather than a preset:

package/docs/start/first-integration.md

@@ -61,7 +61,7 @@ npx @osqd/bothandlerjs check --preset protect-content
 npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
 ```
 
-The first runs your policy against [526 shapes of real traffic](../testing/corpus.md); the
+The first runs your policy against [548 shapes of real traffic](../testing/corpus.md); the
 second runs it against yours. Read the list of would-be-denied requests. If any of them is a
 person, the policy is wrong — and you found out from a log file.
 

package/docs/start/installation.md

@@ -16,7 +16,7 @@ The library imports nothing but `node:` builtins, and CI fails if that ever stop
 true. Nothing here can hand your project a transitive advisory, an install script, or a
 version conflict with something you already run.
 
-Redis, if you use it, is your client passed in: `RedisStore` describes the five commands it
+Redis, if you use it, is your client passed in: `RedisStore` describes the four commands it
 needs structurally and imports neither `ioredis` nor `node-redis`.
 
 ```ts
@@ -31,7 +31,7 @@ new BotHandler({ store: new RedisStore(redis) });
 | `@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 all 526 cases |
+| `@osqd/bothandlerjs/corpus` | [`runCorpus`](../testing/corpus.md) and all 548 cases |
 | `@osqd/bothandlerjs/cli` | the [command line](../testing/cli.md) |
 
 ## Runtimes

package/docs/testing/cli.md

@@ -43,7 +43,7 @@ npx @osqd/bothandlerjs check --preset protect-content
 ```
 
 ```
-  protect-content against 522 shapes of real traffic
+  protect-content against 548 shapes of real traffic
 
   human            181 cases   3 tag, 175 allow, 3 challenge
   benign-bot       144 cases   6 allow, 86 tag, 48 block, 2 challenge, 2 rate-limit
@@ -112,6 +112,12 @@ Lists what a configuration actually installs, with each detector's cost and stag
 for the question "is `identity-rotation` on?", which has caused more confusion than any
 other single setting.
 
+A preset selects *rules*, so it does not change this list — the flag is there because the
+command builds a real handler, not because the answer moves. What does change it is
+`challenge`, `probe` and `site`, each of which installs the detectors that read it. The
+command says so on stderr, so redirecting the list somewhere stays clean. An unknown preset
+is refused rather than quietly answered for the default configuration.
+
 ## Related
 
 - [The corpus](corpus.md) · [Log replay](replay.md)

package/docs/testing/corpus.md

@@ -1,6 +1,6 @@
 # The traffic corpus
 
-526 cases, 739 requests, 6,002 header lines, 55 categories of real web traffic — and a
+548 cases, 1,235 requests, 12,802 header lines, 58 categories of real web traffic — and a
 harness that runs them against *your* configuration.
 
 ← [Documentation](../index.md) · [Testing](index.md)
@@ -21,12 +21,16 @@ npm run corpus -- --audience human --verbose
 ```
 
 ```
-  monitor-only     526/526 cases pass  ·  0 false positives
-  protect-content  526/526 cases pass  ·  0 false positives
-  protect-data     525/526 cases pass  ·  0 false positives
-  protect-auth     511/526 cases pass  ·  0 false positives
+  monitor-only     539/539 cases pass  ·  0 false positives
+  protect-content  539/539 cases pass  ·  0 false positives
+  protect-data     538/539 cases pass  ·  0 false positives
+  protect-auth     524/539 cases pass  ·  0 false positives
 ```
 
+539 rather than 548 because nine cases name a source this configuration does not provide —
+a marker probe or a site baseline — and a verdict about a marker from a handler that issues
+none is a verdict about nothing. Those are *skipped*, and named, rather than failed.
+
 The two strict presets do not pass everything, and **the gap is the documentation rather
 than a defect**: [`protect-auth`](../policy/presets.md#protect-auth) blocks proven
 automation, and the fifteen cases it fails are your payment webhook, your own server-side
@@ -38,11 +42,11 @@ corpus keeps the receipts.
 
 | Audience | Cases | Examples |
 | -------- | ----: | -------- |
-| **human** | 182 | 30 browser profiles across Chromium, Gecko and WebKit · desktop, mobile, tablet, console, television · 40 in-app WebViews (Instagram, TikTok, WeChat, KakaoTalk, LINE, VK, banking and airline apps) · Electron desktop apps · Tor, `resistFingerprinting`, Sec-GPC · Lynx, w3m, screen readers · IE11, Android 4.4, a car's infotainment screen · corporate proxies, carrier transcoders, CGNAT, iCloud Private Relay · an author signing in at `/wp-login.php` and a developer searching a docs site for SQL syntax |
+| **human** | 186 | 30 browser profiles across Chromium, Gecko and WebKit · desktop, mobile, tablet, console, television · 40 in-app WebViews (Instagram, TikTok, WeChat, KakaoTalk, LINE, VK, banking and airline apps) · Electron desktop apps · Tor, `resistFingerprinting`, Sec-GPC · Lynx, w3m, screen readers · IE11, Android 4.4, a car's infotainment screen · corporate proxies, carrier transcoders, CGNAT, iCloud Private Relay · an author signing in at `/wp-login.php` and a developer searching a docs site for SQL syntax |
 | **benign-bot** | 144 | Googlebot and Bingbot verified by DNS · 30 regional crawlers (Naver, Seznam, Coc Coc, Sogou, 360, Shenma, Qwant, Mojeek) · Google's and Microsoft's specialist fleets · 12 link unfurlers · monitoring · feed and podcast clients · academic and archival crawlers · ad verification · email link scanners |
 | **declared-bot** | 32 | The AI fleet split by job — training, search, fetch-for-a-user — plus an agentic browser |
-| **unwanted-bot** | 106 | SEO and market-intelligence crawlers · **50 HTTP clients in their real header orders**, across Python, Node, JVM, Go, Rust, PHP, Ruby, .NET, Perl · headless runtimes · fabricated User-Agents from a randomiser (Chrome on an iPhone, Windows and macOS at once, Firefox on WebKit) |
-| **hostile** | 29 | Forged Googlebot four ways · scanners · credential stuffing · traps · protocol abuse and request-smuggling framing · forwarding-header injection · wordlist probes for `/.env`, `/.git`, JNDI and TRACE |
+| **unwanted-bot** | 116 | SEO and market-intelligence crawlers · **50 HTTP clients in their real header orders**, across Python, Node, JVM, Go, Rust, PHP, Ruby, .NET, Perl · headless runtimes · fabricated User-Agents from a randomiser (Chrome on an iPhone, Windows and macOS at once, Firefox on WebKit) |
+| **hostile** | 37 | Forged Googlebot four ways · scanners · credential stuffing · traps · protocol abuse and request-smuggling framing · forwarding-header injection · wordlist probes for `/.env`, `/.git`, JNDI and TRACE · traversals spelled in percent-encoding and encoded twice over · open-proxy probing |
 | **infrastructure** | 33 | CDN origin pulls (Cloudflare, Fastly, Akamai, CloudFront) · API gateways and service meshes · k8s and ELB probes · webhooks · browser prefetch |
 
 Every request is built the way the client actually builds it — the Client Hints block, the

package/docs/testing/index.md

@@ -13,7 +13,7 @@ that cheap.
 | Page | Answers |
 | ---- | ------- |
 | [The CLI](cli.md) | "what is this one request?", "what does this policy do?" |
-| [The corpus](corpus.md) | "who would this configuration hurt?" — 526 shapes of real traffic |
+| [The corpus](corpus.md) | "who would this configuration hurt?" — 548 shapes of real traffic |
 | [Log replay](replay.md) | "what would this have done to yesterday?" |
 | [Try it](try-it.md) | "what does it look like running?" — the demo, the simulator, three dashboards |
 

package/docs/testing/try-it.md

@@ -77,7 +77,7 @@ detectors read. Run one scenario at a time with `npm run simulate:curl`,
 ### Replaying the whole corpus over the wire
 
 ```bash
-npm run simulate:corpus                              # all 526 cases
+npm run simulate:corpus                              # all 548 cases
 npm run simulate:corpus:human                        # only the people
 npm run simulate -- --corpus --tag known-cost        # only the awkward ones
 npm run simulate -- --corpus --case browse-chrome-windows --verbose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osqd/bothandlerjs",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -80,11 +80,14 @@
   ],
   "scripts": {
     "build": "tsup && tsc --emitDeclarationOnly && tsc -p tsconfig.element.json",
+    "check:package": "npm run build && tsx scripts/check-package.ts",
     "build:watch": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:browser": "vitest run --config vitest.browser.config.ts",
+    "test:browser:firefox": "BROWSER_ENGINE=firefox npm run test:browser",
+    "test:browser:webkit": "BROWSER_ENGINE=webkit npm run test:browser",
     "lint": "biome check .",
     "docs:check": "node scripts/check-links.mjs",
     "format": "biome check --write .",