@osqd/bothandlerjs 0.6.0 → 0.7.0

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.6.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 .",