@osqd/bothandlerjs 0.3.0

package/docs/testing/corpus.md

@@ -0,0 +1,129 @@
+# The traffic corpus
+
+526 cases, 739 requests, 6,002 header lines, 55 categories of real web traffic — and a
+harness that runs them against *your* configuration.
+
+← [Documentation](../index.md) · [Testing](index.md)
+
+---
+
+## Why it exists
+
+Every claim in this documentation about what detection catches, what a preset does, and who
+a policy hurts is measured on this corpus rather than asserted. It is also the reason the
+[guard](../concepts/the-guard.md) can be defended concretely: "no case marked as a person is
+denied service" is a test that runs, not a design intention.
+
+```bash
+npm run corpus                          # the protect-content preset
+npm run corpus -- --preset protect-data
+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
+```
+
+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
+renderer, and your orchestrator's health probes — correct on a login route, an outage
+anywhere else. That is why the preset says to mount it on those routes only, and why the
+corpus keeps the receipts.
+
+## What is in it
+
+| 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 |
+| **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 |
+| **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
+Fetch Metadata group, `Priority`, a cookie jar from somebody who has genuinely used the web
+(`_ga`, `_fbp`, `__cf_bm`, a TCF consent string), cache validators on a revisit, and the
+conditional long tail: `Sec-GPC`, `Save-Data`, `Sec-Purpose: prefetch`, `Early-Data`,
+`Sec-CH-Prefers-Color-Scheme`, the Network Information hints. 155 requests carry cookies.
+Every case records **provenance**, enforced by a test.
+
+## The guarantee, checked rather than argued
+
+Every case marked `human` carries an automatic `neverAction: ["block", "drop", "redirect"]`,
+enforced by the harness whatever the case's own expectations say, and asserted **for every
+request of a sequence** — because a person denied on request seven is still a person denied.
+
+There is exactly one documented exemption, and it is *counted rather than hidden*: a
+listener tapping a link inside a podcast app, whose software sends the same
+crawler-convention User-Agent it uses to fetch feeds. The guarantee is about guesses, and a
+client that announces itself automated is not a guess. The scorecard lists every such case
+with a written reason.
+
+## Two details that make it honest
+
+**Header order is reproduced, not invented.** Chromium emits `Host, Connection, sec-ch-ua…,
+User-Agent, Accept, Sec-Fetch-*, Accept-Encoding, Accept-Language, Priority`; Gecko leads
+with identity and closes with Fetch Metadata and `TE`; WebKit interleaves them.
+`python-requests` sending `Accept-Encoding` before `Accept` is only a signal if the corpus
+gets this right.
+
+**DNS is controlled, not mocked away.** Each case declares its answers, so *"the operator's
+DNS disproves this claim"* and *"our resolver was briefly unhappy"* can be told apart. One is
+an impersonator; the other is Googlebot during a blip. See
+[verification](../detection/verification.md).
+
+## The evasion ladder
+
+Five cases that run from crude to undetectable, and **the top rungs are expected to fail**:
+
+| | | |
+|-|-|-|
+| 1 | Copied the User-Agent only | caught, four independent signals |
+| 2 | Copied the header set, not the order | caught, weakly |
+| 3 | Copied the order and the Client Hints | **not caught** from one request |
+| 4 | …at a machine-perfect rhythm | caught by `cadence`, and only by `cadence` |
+| 5 | …paced like a person, a few pages per address | **not caught at all** |
+
+Level 5 is in the corpus so that nobody can claim otherwise. At that point the difference
+from a person has stopped being technical, and what defeats it is cost — a
+[proof of work](../challenge/index.md), or an account — not detection. See
+[the threat model](../concepts/threat-model.md).
+
+## Running it against your own configuration
+
+It is a published entry point, not a test fixture:
+
+```ts
+import { runCorpus } from "@osqd/bothandlerjs/corpus";
+
+const scorecard = await runCorpus({
+  create: ({ resolver, clock }) => new BotHandler({ ...myProductionConfig, resolver, clock }),
+  assertActions: false,   // your actions are yours; the invariants are not
+});
+
+if (scorecard.falsePositives.length > 0) throw new Error("this policy turns people away");
+```
+
+`assertActions: false` is the setting to understand. The corpus knows what each case *is*;
+it does not know what your policy should do about it. The invariants — nothing marked as a
+person is denied — hold regardless.
+
+DNS is controlled and the clock is manual, so it runs offline, deterministically, in CI.
+
+## Adding cases
+
+See [`src/corpus/README.md`](../../src/corpus/README.md). The bar is provenance: a case has
+to say where its headers came from, and a test enforces it. A corpus of invented traffic
+would make every claim in this documentation false in a way nobody could see.
+
+## Related
+
+- [The CLI](cli.md#check) — the same corpus, one command
+- [Log replay](replay.md) — the complement: traffic that is actually yours
+- [The guard](../concepts/the-guard.md) — the invariant this enforces
+- [Presets](../policy/presets.md) — the four the scorecard reports on

package/docs/testing/index.md

@@ -0,0 +1,61 @@
+# Testing
+
+Finding out what a policy does to your traffic before it does it.
+
+← [Documentation](../index.md)
+
+---
+
+This library's central claim is that a bot policy is a claim about **your** traffic, and
+that it should be checked rather than believed. Everything on these pages exists to make
+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 |
+| [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 |
+
+---
+
+## The order to use them in
+
+1. **[`explain`](cli.md#explain)** — one request. The ticket that says "why was I
+   challenged?".
+2. **[`check`](cli.md#check)** — your policy against the corpus. This is the CI step. It
+   exits non-zero if any case marked as a person is denied service.
+3. **[`replay`](replay.md)** — your policy against your own access log. The corpus knows
+   what the internet looks like; only your logs know what *your* visitors look like.
+4. **[`monitor-only`](../policy/presets.md#monitor-only) in production** — for a week,
+   watching [the dashboard](../operations/dashboard.md), before anything is enforced.
+
+Step 4 is not optional and the other three do not replace it.
+
+## Testing your own configuration, not a preset
+
+The corpus is a published entry point:
+
+```ts
+import { runCorpus } from "@osqd/bothandlerjs/corpus";
+
+const scorecard = await runCorpus({
+  create: ({ resolver, clock }) => new BotHandler({ ...myProductionConfig, resolver, clock }),
+  assertActions: false,   // your actions are yours; the invariants are not
+});
+if (scorecard.falsePositives.length > 0) throw new Error("this policy turns people away");
+```
+
+DNS is controlled rather than real and the clock is manual, so it is reproducible, offline,
+and safe to run anywhere — including in CI, which is the point.
+
+## Testing a detector you wrote
+
+[Writing a detector](../detection/writing-a-detector.md) covers the contract; the corpus is
+how you find out whether your new signal fires on 182 kinds of person as well as on the
+thing you built it for. That is usually the surprising part.
+
+## Related
+
+- [Choosing a policy](../start/choosing-a-policy.md) — where these fit in the decision
+- [The dashboard](../operations/dashboard.md) — the request tester, which is `explain` with a UI

package/docs/testing/replay.md

@@ -0,0 +1,102 @@
+# Log replay
+
+What your policy would have done to yesterday.
+
+← [Documentation](../index.md) · [Testing](index.md)
+
+---
+
+A bot policy is a claim about *your* traffic. The only honest way to check it before it
+starts turning people away is to run it over traffic you already have.
+
+```bash
+npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
+```
+
+```
+  replay — 4,000 requests, preset "protect-content", format clf
+
+  verdicts
+    unknown            2906   72.7%  ██████████████████
+    confirmed-bot      1094   27.4%  ███████
+
+  what would have happened
+    allow           2906   72.7%  ██████████████████
+    challenge        477   11.9%  ███
+    tag              387    9.7%  ██
+    block            116    2.9%  █
+
+  116 request(s) would have been DENIED, in 1 distinct kind(s). Read them.
+  ─────────────────────────────────────────────────────────────────────
+     116x  block by rule "scanner-block" — confirmed-bot, proven
+          sqlmap/1.7.2#stable (https://sqlmap.org)
+          [certain] self-identified: User-Agent identifies sqlmap
+```
+
+**That last block is the point of the exercise.** Every request the policy would have
+refused, grouped by kind, with the evidence. If any of them is a person, the policy is
+wrong — and you found out from a log file rather than from a support ticket.
+
+---
+
+## Prefer JSON Lines, and here is why
+
+It accepts Combined/Common Log Format or JSON Lines. **JSON Lines is much better**, and the
+reason is a real distinction the library models:
+
+> A header missing from a *record* is not a header missing from the *request*.
+
+An nginx access line records the User-Agent and the Referer and nothing else. Several
+[detectors](../detection/detectors.md) reason from absence — "claims to be a browser but
+sent no `Accept-Language`" — and on a CLF line that reasoning is not merely weak, it is
+meaningless.
+
+So `RequestFacts.partialHeaders` marks a header-poor source, and every absence-based
+detector stands down; the ones that reason from what *is* present carry on. Without it, a
+replay over real nginx logs reports most of a site's human traffic as suspected bots —
+worse than useless, because it is confidently wrong.
+
+A CLF replay therefore **under-reports**, and its silence is not a clean bill of health.
+
+### The JSON Lines shape
+
+One object per line:
+
+```json
+{ "ip": "203.0.113.5", "method": "GET", "url": "/products/12", "headers": { "user-agent": "...", "accept-language": "en-GB" }, "timestamp": 1757030400000 }
+```
+
+Configure your access log to emit the header set you care about — at minimum `user-agent`,
+`accept`, `accept-language`, `accept-encoding`, `referer` and the `sec-ch-ua`/`sec-fetch-*`
+groups — and the replay sees what detection would have seen.
+
+## Setting `partialHeaders` yourself
+
+Whenever you build facts from something that filters headers:
+
+```ts
+createFacts({ method, url, headers, ip, partialHeaders: true });
+```
+
+Any log pipeline, any CDN export, any sampled trace. It is the difference between a replay
+that tells you something and a replay that tells you everything is a bot.
+
+## What it cannot tell you
+
+**Behaviour it did not record.** `cadence` and `crawl-breadth` read a sequence, so they work
+only if your log preserves ordering and timestamps — which JSON Lines does and a truncated
+sample does not.
+
+**DNS as it was.** [Verification](../detection/verification.md) runs against today's DNS,
+not the DNS of the day the log was written. A crawler that has since changed hands verifies
+differently.
+
+**The effect of the mitigation.** A replay shows what the policy would have *asked for*, not
+how the traffic would have responded to being challenged or slowed. Those are the same
+number only if nobody adapts, and adapting is what the population in question does.
+
+## Related
+
+- [The CLI](cli.md) — every flag
+- [The corpus](corpus.md) — the complement: traffic you do not have yet
+- [Detection](../detection/index.md) — the pipeline being replayed

package/docs/testing/try-it.md

@@ -0,0 +1,189 @@
+# Try it
+
+A demo site with a live dashboard, eighteen scripted clients, and three dashboards
+showing three different amounts of the same traffic.
+
+← [Documentation](../index.md) · [Testing](index.md)
+
+---
+
+## The demo and the simulator
+
+Two commands, two terminals:
+
+```bash
+npm run demo        # a protected site on :9673 + a live dashboard on :9674
+npm run simulate    # points eighteen kinds of client at it
+```
+
+Open **http://localhost:9674/** and watch. Every request lands in the feed with its
+verdict, its score, the action taken, and — click a row — the individual pieces of
+evidence with their certainty tiers and, for proven ones, the written basis. The
+second tab is the statistics panel: traffic over time, the latency histogram, and the
+distributions behind the tiles.
+
+That dashboard is not demo scaffolding. It is the one the library ships, started with
+one call — `detector.serveDashboard({ port: 9674 })` — and you can put the same thing
+in your own application. See [The dashboard](../operations/dashboard.md#the-dashboard).
+
+The demo policy is deliberately overreaching: it asks to **block every suspected
+bot**. Strict mode refuses every time. Those amber rows are the whole library in one
+screen — requests scoring 93 and 98 that still do not get blocked, because a score is
+not proof.
+
+`npm run simulate` runs these, each from its own source address so they are distinct
+actors, and prints what happened:
+
+```
+  human                 7x 200               2ms      unknown x7
+  curl                  2x 429               1ms      confirmed-bot x2
+  python                2x 429               1ms      confirmed-bot x2
+  go                    1x 429               1ms      confirmed-bot
+  scanner               3x 403               1ms      confirmed-bot x3
+  headless              1x 429               1ms      confirmed-bot
+  spoofed-browser       3x 429               1ms      suspected-bot x3
+  platform-mismatch     1x 200               1ms      unknown
+  fake-googlebot        1x 403               39ms     confirmed-bot
+  verified-crawler      4x 200               2ms      verified-bot x4
+  declared-crawler      30x 200, 6x 429      1ms      confirmed-bot x36
+  trap                  1x 200, 1x 403       1ms      unknown, confirmed-bot
+  trap-field            1x 403               2ms      confirmed-bot
+  scraper               34x 429              1ms      suspected-bot x34
+  metronome             14x 200              2ms      unknown x14
+  burst                 30x 200              1ms      unknown x30
+  credential-stuffing   8x 401               252ms    unknown x8
+  no-user-agent         1x 200               1ms      unknown
+```
+
+Four rows are worth reading twice:
+
+- **`human`** — seven ordinary page views, all served, verdict `unknown`. This is the
+  row that matters. Every other row is only interesting if this one stays clean.
+- **`verified-crawler`** — GPTBot arriving from the operator's published range is
+  *allowed*, ahead of every other rule. Bot detection that costs you your search
+  traffic has not helped.
+- **`burst`** — thirty requests as fast as a socket allows, and all thirty are
+  served. Rate is capped at `moderate` and cannot block on its own, because behind a
+  corporate NAT that burst is a floor of people, not a bot — and the client's request
+  carries the marks of a real browsing session, which discounts it further.
+- **`credential-stuffing`** — served, `401`, and **253 ms each**. No challenge, no
+  block, nothing excluded; the attack simply stops being economic.
+
+The simulator speaks raw HTTP over a socket rather than using `fetch`, because
+`fetch` normalises the header set and fixes the order — the exact properties several
+detectors read. Run one scenario at a time with `npm run simulate:curl`,
+`npm run simulate:trap`, and so on; `npm run simulate:list` prints them all.
+
+### Replaying the whole corpus over the wire
+
+```bash
+npm run simulate:corpus                              # all 526 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
+```
+
+```
+  by audience
+    human           178/178 pass   served 173, challenge 5
+    benign-bot      137/137 pass   served 89, block 46, challenge 2
+    unwanted-bot    104/104 pass   challenge 78, served 23, block 3
+    declared-bot     29/ 29 pass   served 27, block 2
+    infrastructure   33/ 33 pass   served 19, challenge 14
+    hostile          19/ 19 pass   block 10, challenge 5, served 4
+
+  500/500 replayed cases pass  ·  0 false positives
+```
+
+This is the stronger of the two tests. The in-process corpus runner calls `assess()`
+directly; replaying the same cases down a socket exercises the **whole stack** — the
+adapter, Node's header parsing, whether wire order survives into `rawHeaders`, cookie
+parsing, and client-address resolution through the forwarding headers. A case that
+passes in-process and fails on the wire has found an adapter bug, and one already did:
+`exposeVerdictHeaders` turned out to be honoured on every response *except* the
+challenge interstitial.
+
+It also tells you where a check *cannot* apply on this runtime. A request carrying
+both `Content-Length` and `Transfer-Encoding` is proven automation by RFC 9112 — and
+Node's own parser answers it 400 before any handler runs, so that case reaches the
+engine only when the facts were built somewhere Node's parser is not in the path: an
+edge worker, a WAF event, a log line. The replay found that, and the case now says so
+in its skip line rather than passing by accident.
+
+Cases with no wire equivalent are skipped and counted rather than quietly passing —
+HTTP/2 fixtures, cases that declare their own DNS answers, cases needing a clearance
+token only the server can mint, cases the runtime refuses before detection, and cases
+needing ranges the demo does not load.
+
+---
+
+**Start in monitor mode.** Run `preset: "monitor-only"` against real traffic for a
+week before you enforce anything. It withholds nothing from anybody and shows you
+exactly what your traffic looks like. Every bot policy that has caused an outage was
+deployed straight to enforcement by someone confident they already knew.
+
+---
+
+## Role-gated dashboards
+
+A second demo, for the question the first one does not answer: who is allowed to look?
+
+```bash
+npm run demo:roles
+```
+
+Four listeners this time — a protected site with an operator console on **:9683**, and
+three dashboards over the same handler: an **analyst** view on **:9684**, an
+**operator** view on **:9685** with the policy editor and the reset button, and an
+**admin** view on **:9686** that can also change the guard.
+
+Start at **http://localhost:9683/operator** and pick a role. There is no password, on
+purpose: this demonstrates *authorisation* — what a proven identity may reach — and
+the proving belongs to your identity provider. Signing in sets an HMAC-signed cookie
+carrying the role, and `auth: { authorize }` reads it.
+
+Then try the three dashboards as each role:
+
+| | analyst `:9684` | operator `:9685` | admin `:9686` |
+| --- | --- | --- | --- |
+| anonymous | `401` | `401` | `401` |
+| analyst | `200` | `401` | `401` |
+| operator | `200` | `200` | `401` |
+| admin | `200` | `200` | `200` |
+
+As an analyst the other two answer `401` on *every* path — authentication runs before
+routing, so a caller without the role cannot even map the endpoints. And on the analyst
+dashboard the editor endpoint answers `403` even for an admin, because `controls`
+belongs to the listener rather than to the visitor: a dashboard started without it has
+no editor to reach, whoever is asking.
+
+Each rung adds exactly one thing, and the last is the one to look at hardest. An
+operator can write a rule that asks for more than the evidence supports, and the guard
+stops it. The admin listener is the only one that can change *whether anything stops
+it* — `controls.editGuard`, off by default and separate from `editPolicy` on purpose —
+and the only one that can act on a single client: allowlist an address, forget an
+actor's history, clear one as human (`controls.editRanges`).
+
+Change any of it and watch the terminal. Every change prints with the name of whoever
+made it, because this demo's `authorize` returns the signed-in email instead of `true`
+— which is all the dashboard needs to attribute a change in the handler's warnings, in
+the `guard-change`, `range-change` and `actor-change` events, and on the marker it
+leaves on the traffic timeline.
+
+The analyst listener also runs with `sections: { evidence: false, policy: false }` and
+`redact: { maskIp: true }`. It has two tabs rather than three, its rows show what
+happened without naming which detector fired, and the feed shows `203.0.113.0/24` where
+the others show the address. Open devtools on it: the evidence is not hidden from the
+page, it never reaches it. The dashboard people watch all day need not be the one that
+names individuals, or the one that explains your detection to whoever is scraping you.
+
+Read [the dashboard's Roles section](../operations/dashboard.md#roles) for what to change before
+this goes anywhere real.
+
+---
+
+## Related
+
+- [Testing](index.md) — the rest: the CLI, the corpus, log replay
+- [The dashboard](../operations/dashboard.md) — every option the demo is showing you
+- [The corpus](corpus.md) — the traffic the simulator is a live version of

package/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "@osqd/bothandlerjs",
+  "version": "0.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Bot traffic detection and handling for TypeScript — evidence-tiered detection that separates proof from suspicion, so blocking never rests on a guess.",
+  "keywords": [
+    "bot-detection",
+    "bot-management",
+    "crawler",
+    "scraper",
+    "anti-bot",
+    "user-agent",
+    "rate-limit",
+    "security",
+    "middleware",
+    "typescript"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OSQD-ts/BothandlerJS.git"
+  },
+  "homepage": "https://github.com/OSQD-ts/BothandlerJS#readme",
+  "bugs": {
+    "url": "https://github.com/OSQD-ts/BothandlerJS/issues"
+  },
+  "author": "Michał Płatosz <platosz.michal@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js",
+      "require": "./dist/adapters/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "require": "./dist/client/index.cjs"
+    },
+    "./package.json": "./package.json",
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.cjs"
+    },
+    "./corpus": {
+      "types": "./dist/corpus/index.d.ts",
+      "import": "./dist/corpus/index.js",
+      "require": "./dist/corpus/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "bothandlerjs": "bin/bothandlerjs.mjs"
+  },
+  "directories": {
+    "example": "examples",
+    "test": "tests"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "build:watch": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "lint": "biome check .",
+    "docs:check": "node scripts/check-links.mjs",
+    "format": "biome check --write .",
+    "demo": "tsx demo/server.ts",
+    "demo:roles": "tsx demo/roles.ts",
+    "simulate": "tsx scripts/simulate.ts",
+    "simulate:corpus": "tsx scripts/simulate.ts --corpus",
+    "simulate:corpus:human": "tsx scripts/simulate.ts --corpus --audience human",
+    "simulate:list": "tsx scripts/simulate.ts --list",
+    "simulate:human": "tsx scripts/simulate.ts human",
+    "simulate:curl": "tsx scripts/simulate.ts curl",
+    "simulate:python": "tsx scripts/simulate.ts python",
+    "simulate:go": "tsx scripts/simulate.ts go",
+    "simulate:scanner": "tsx scripts/simulate.ts scanner",
+    "simulate:headless": "tsx scripts/simulate.ts headless",
+    "simulate:spoofed-browser": "tsx scripts/simulate.ts spoofed-browser",
+    "simulate:platform-mismatch": "tsx scripts/simulate.ts platform-mismatch",
+    "simulate:fake-googlebot": "tsx scripts/simulate.ts fake-googlebot",
+    "simulate:verified-crawler": "tsx scripts/simulate.ts verified-crawler",
+    "simulate:declared-crawler": "tsx scripts/simulate.ts declared-crawler",
+    "simulate:trap": "tsx scripts/simulate.ts trap",
+    "simulate:trap-field": "tsx scripts/simulate.ts trap-field",
+    "simulate:scraper": "tsx scripts/simulate.ts scraper",
+    "simulate:metronome": "tsx scripts/simulate.ts metronome",
+    "simulate:burst": "tsx scripts/simulate.ts burst",
+    "simulate:credential-stuffing": "tsx scripts/simulate.ts credential-stuffing",
+    "simulate:no-user-agent": "tsx scripts/simulate.ts no-user-agent",
+    "typecheck": "tsc -p tsconfig.typecheck.json && tsc -p tsconfig.browser.json",
+    "bench": "tsx --expose-gc scripts/bench.ts",
+    "corpus": "tsx scripts/corpus.ts",
+    "example": "tsx examples/express-basic.ts",
+    "example:fetch": "tsx examples/fetch-worker.ts",
+    "example:notify": "tsx examples/notifications.ts",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
+    "client:build": "node scripts/build-client.mjs",
+    "client:check": "node scripts/build-client.mjs --check",
+    "prebuild": "npm run client:build",
+    "pretest": "npm run client:build",
+    "pretypecheck": "npm run client:build",
+    "pretest:browser": "npm run client:build",
+    "bench:guard": "tsx scripts/bench-guard.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.3.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "axe-core": "^4.13.0",
+    "esbuild": "^0.27.7",
+    "express": "^5.2.1",
+    "playwright": "^1.62.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "module": "./dist/index.js",
+  "sideEffects": false
+}