@osqd/bothandlerjs 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -8,6 +8,127 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Shadow mode: run a detector and let it decide nothing.** `shadowDetectors: ["path-novelty"]`
+  runs the named detectors on every request exactly as they otherwise would and keeps their
+  findings out of the verdict, the score, the class, the identity and every rule. They land
+  in `assessment.shadowEvidence`, counted and charted next to the evidence that did decide.
+  This is deliberately not a weight of zero: a weight is consulted only on the probabilistic
+  path, and `certain` evidence never reaches that path, so a shadowed detector emitting it
+  would have blocked people with its weight sitting at zero the whole time.
+
+  `assessment.shadowVerdict` carries what the verdict *would* have been, computed only when
+  a shadowed detector actually found something. "It fired 312 times" is not a number anybody
+  can act on; "it would have moved 41 requests to `suspected-bot`" is. Prometheus gains
+  `bothandler_shadow_firings_total` and `bothandler_shadow_verdict_changes_total`, both
+  absent entirely while nothing is shadowed.
+
+  The correlation sources are why this exists: several of their detectors fire at `moderate`
+  on real people by design — a phone roaming between networks, a crowd on a broken link,
+  somebody tapping "Request desktop site" — and whether the thresholds are right *for your
+  site* is not a thing this library can know. See `docs/detection/shadow-mode.md`.
+
+- **`target-integrity`, and the raw request target it reads.** `facts.path` is normalised so
+  that a rule scoped to `/admin` holds against `/%61dmin` and `/./admin`. That normalisation
+  is also what makes an evasive target look ordinary: `/%2e%2e%2f%2e%2e%2fapp/config.yml`
+  arrives as `/app/config.yml`, which is on no wordlist and reads like a broken link.
+  `facts.rawPath` now keeps the target as it was spelled — and only when it differs from the
+  normalised form, so ordinary traffic pays nothing for it.
+
+  The detector reports encoded traversals, double encoding, encoded control characters,
+  absolute-form targets addressed to a proxy, and separators hidden inside a segment. None
+  of it is `certain` and the closest call says why: a path segment carrying a URL as *data*
+  is encoded once to sit in a path and again by whatever built the link around it, which
+  produces `%252e` honestly on a site that has done nothing wrong.
+
+- **The feed filter takes `$and`, `$or`, `$not`, `$in` and `$notin`.** Adjacent terms
+  still mean `AND` and `-term` still negates, so every existing query and saved filter
+  reads the same — but the parser produces a tree now rather than a flat list, which is
+  what `$or` needs and what the previous version communicated by silently ignoring the
+  word. `$not` binds tightest, then `$and`, then `$or`, and brackets group. Operators
+  carry a `$` because a bare `or` appears in User-Agents and paths, and a language where
+  an ordinary search word becomes an operator lies about what it matched. Nothing throws:
+  an unclosed bracket, a dangling `$or` and a half-typed `$in(` are all the normal state
+  of a live search box.
+
+- **The Actors screen lists either the registry or the actors in the feed.** A toggle
+  above the table. The registry answers "who is hitting me hardest"; once a filter is on,
+  the question is usually the other one — "who is in *this*" — and the screen could not
+  answer it. The feed-derived list leaves `Per min`, `Cadence` and `Unsolved` blank rather
+  than computing them from a few hundred requests, because those are properties of a
+  client's whole history and a confident number under the wrong heading is worse than a
+  dash.
+
+### Changed
+
+- **The browser suite runs on Chromium, Firefox and WebKit.** `BROWSER_ENGINE` picks one
+  locally (`npm run test:browser:firefox`, `:webkit`); CI runs all three as a matrix.
+  Testing a single engine is how the Safari header bug shipped, and Firefox earned its
+  place on the first run by catching the challenge page's CSP error.
+
+- **The feed's column headers stick in Safari.** The tables collapsed their borders, which
+  is a long-standing sore point for sticky table cells in WebKit — the CSSWG has an open
+  issue on collapsed borders not following a cell when it sticks, and Safari is widely
+  reported to drop the stickiness of a `th` outright. The header held in Chromium and
+  Firefox and was reported adrift in Safari, which is what a sticky element that has
+  stopped sticking looks like. They separate their
+  borders with zero spacing now, which no border in these tables relied on: the only
+  measurable difference is the accent column starting two pixels earlier, because
+  collapsing left half of that 3px border outside the cell. A browser test scrolls the
+  page and asserts the header holds, since one keyword can undo this silently.
+
+- **The feed's Exclude button is gone; `$not` replaces it.** It kept a hidden list in one
+  person's browser, which meant a view with the noise taken out could not be shared. A
+  `$not` lives in the URL like every other narrowing.
+
+- **Labelling an actor edits in place instead of calling `prompt()`.** A sandboxed iframe
+  blocks `prompt()` outright, so on an embedded dashboard the Label button did nothing at
+  all, with no error and no way to tell.
+
+- **Correlating a client's own requests, through a marker cookie.** `probe` is a new,
+  opt-in source: the engine issues a signed first-party cookie and reads it back, so two
+  requests can be attributed to one *client* rather than to one address. That closes a gap
+  the library had documented and declined to guess at — `identity-rotation` reads "one
+  actor, several User-Agents" as lying, and under an address-derived actor key that
+  describes every office and carrier on the internet, so it has always shipped switched
+  off. A marker carries an HMAC only this server can produce, which makes the same
+  observation evidence instead of speculation.
+
+  Four detectors arrive with it. `identity-drift` compares the identity claimed now with
+  the one claimed when the marker was issued, weighing a changed *browser family* at
+  `strong` and a changed platform at `moderate` — because "Request desktop site" on a
+  phone does the latter and the person doing it is a person. `marker-integrity` reports a
+  marker signed with a key we do not have. `marker-fanout` counts the networks one marker
+  has been presented from. `marker-persistence` reports a client that sends cookies but
+  never ours, deliberately narrower than `session-integrity`, which already covers a
+  client that sends none.
+
+  It is off by default and sets a cookie only when the client holds no valid one, so an
+  ordinary visitor is issued one on the first request of a session and no other. `secrets`
+  is required and has no default: a secret generated at startup would read every marker
+  minted by another replica as forged.
+
+- **Reading what a client does when it is challenged.** `challenge-reaction` reports an
+  identity that changes within seconds of a challenge, and a client challenged repeatedly
+  that has never answered. It is the only detector here whose stimulus this library chose,
+  which is what lets it reach `strong` — and it reports the same observation a tier lower
+  when only an address ties the two requests together, because that is how much less an
+  address-based join is worth. `challenge-integrity` reports solutions that were replayed,
+  or returned faster than the proof of work can be computed in a browser.
+
+- **Comparing a client with the rest of your traffic.** `site` is a second opt-in source
+  holding a bounded, warmed-up baseline of what a site normally serves. `distributed-walk`
+  finds a numeric range walked across many clients where none walks enough of it alone —
+  the one threat per-actor thresholds miss by construction. `path-novelty` is a
+  self-maintaining wordlist. `path-campaign` reports a path the site never served that
+  many unrelated clients suddenly want, requiring the miss rate so that a successful
+  launch is not reported as an attack. `miss-baseline` is `probe-volume` measured against
+  the site's own rate rather than a fixed threshold.
+
+  Nothing is reported until `warmupRequests` have been observed, because every path is
+  rare when nothing has been seen. Walk ids are held as a coarsening bitmap and marker
+  fan-out as a 128-bit sketch, so neither table grows with what a client chooses to
+  request.
+
 - **`indexers-only`, a preset for sites that want search traffic and nothing else.**
   Serves a bot only when its identity has been confirmed by DNS or a published range
   *and* it is a `search` or `social` crawler; refuses every other proven bot; challenges
@@ -106,6 +227,111 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **An embedded dashboard could point at the host application instead of at `src`.**
+  `disconnectedCallback` imports the stream module to close the stream, that module
+  imports the boot module, and the boot module read its mount path off the global once,
+  when it was first evaluated. A host page that mounted, unmounted and remounted the
+  element before the first bootstrap fetch returned — React 18's development double-mount
+  — ran that import while the global was still undefined, so the base froze at `""` for
+  the life of the page.
+
+  Nothing threw. Every request the dashboard made afterwards went to the host page's own
+  origin root rather than to `src`, so it drew no traffic while sending `/api/stream` and
+  `/api/stats` to somebody else's router, and the only outward sign was an `EventSource`
+  complaining about a MIME type on whichever engine reports that. The element now hands
+  the payload over explicitly, so being evaluated early costs nothing.
+
+- **Pressing "Load them" left the "not streamed" badge on screen.** The count of how much
+  of the gap had been closed was taken from the page's own snapshot, which is refreshed on
+  a timer and so was usually several seconds out of date; a snapshot arriving afterwards
+  with a larger count reopened a gap that had just been closed. `/api/feed` now returns
+  `skipped` alongside the backlog, so the number comes from the response that closed the
+  gap rather than from one taken before it.
+
+- **`RedisStore.increment` could leave a counter key that never expired.** `INCR` then
+  `PEXPIRE` is two commands, and a process killed between them orphaned a key nothing would
+  ever revisit — the next request falls into the next bucket, under another key. The expiry
+  is now armed by the command that *creates* the key: `SET … PX … NX` issued without waiting
+  for its reply, then `INCR`, so both are on the wire together and this stays one round trip.
+  Not a Lua script, because `eval` is the one command `ioredis` and `node-redis` spell
+  differently enough that `RedisLike` could not describe both. `pexpire` has left that
+  interface, which needs four commands now rather than five.
+
+- **The interaction challenge marked down somebody who paused mid-movement, twice over.**
+  Samples arriving more than a quarter of a second apart are dropped before anything is
+  measured, because the distance across a pause is not a distance a hand travelled — but
+  `fractionalShare` was dividing the samples it kept by the count of everything that
+  arrived, reporting *fewer* sub-pixel coordinates than the samples it was computed from
+  actually had. That reads as "these coordinates are integers", which is the signature of an
+  interpolated path. Separately, whether a path was measurable at all was decided from the
+  raw array length while the scoring judged the kept samples: four pointer samples with a
+  pause before each one were four to the array and none to the analysis, so the report was
+  called measurable and then scored at zero. Both cost the reading pattern most likely to
+  produce them — move the pointer, stop to read, move again.
+
+- **Save and Cancel on the actor label editor, which three earlier attempts could not fit.**
+  `input[type="text"] { width: 100% }` outranks a bare class selector, so the editor's
+  `width: 15ch` had never applied: the box filled its shrink-to-fit container and pushed the
+  buttons past the right edge of the panel, where they could be seen and not clicked.
+  Qualifying the selector fixed the cause; the row's other actions now stand aside while the
+  editor is open, which is also the right thing on its own — Allowlist and Forget are not
+  what somebody naming a client is reaching for.
+
+- **The Actors scope was not in the URL.** `#actors?a=feed`, pushed rather than replaced,
+  because switching between the registry and the feed is a discrete act like clicking a tab
+  and the back button should undo it. The feed-scoped list also shows a dash for
+  `Confirmations` like the three columns beside it, rather than a confident zero under a
+  heading that means "how many times has this client been proven a bot".
+
+- **`bothandlerjs detectors --preset <typo>` answered anyway.** An unknown preset fell
+  through to a handler with no preset and printed the default list at exit code 0 — a
+  confident wrong answer to the one question the command exists for, while `robots` in the
+  same file refused the same typo. It is refused now, with the same message. The command
+  also notes that a preset selects rules rather than detectors, and that `challenge`,
+  `probe` and `site` are what change the list; the note goes to stderr, so redirecting the
+  list stays clean.
+
+- **The default notification sink discarded the content of every error.** `consoleNotifier`
+  never referenced `event.error`. An error carrying no assessment fell into the branch
+  written for anomalies and printed `[bothandler] error unknown — ` at *warning* level, with
+  the failing source and the message both dropped; one that did carry an assessment printed
+  the request's evidence instead. Errors are how a failed detector, sink or store is
+  reported, and this is the sink an operator gets without configuring one — so the default
+  way to find out that a detector had been throwing showed neither which one nor why.
+
+- **Every person shown a challenge page in Firefox got a security error in their
+  console.** The page declares no icon, so the browser asks for `/favicon.ico` by itself;
+  under `default-src 'none'` that request is refused, and Firefox reports the refusal as a
+  CSP violation on a page whose entire purpose is to reassure somebody that nothing is
+  wrong. The page now declares an empty icon so the request is never made, and the policy
+  allows `img-src data:` — which permits nothing off the machine, a `data:` URI being
+  inline by definition — so that declaration is honoured. Found by running the browser
+  suite on Firefox for the first time.
+
+- **Cookies split across several header fields were misparsed, losing every cookie after
+  the first.** HTTP/2 permits a client to send its cookies as separate header fields and
+  Node's `http2` surfaces them as an array; RFC 9113 §8.2.3 says a receiver concatenates
+  them with `"; "`. They were joined with `", "` like every other header, which parses as
+  one cookie whose value is the rest of the line — so a clearance token in the second
+  field was invisible, and an HTTP/2 visitor who had solved a challenge was challenged
+  again on every request.
+
+- **`X-Forwarded-For` entries carrying a port were dropped.** Azure's Application Gateway
+  and Front Door write `1.2.3.4:5678`, and RFC 7239 spells IPv6 as `[2001:db8::1]:5678`.
+  Neither parsed, and because every entry in such a chain carries a port the whole chain
+  emptied and every client behind that proxy resolved to the proxy's own address — sharing
+  one actor, one history and one rate-limit bucket, so a single bot could lock out every
+  real visitor.
+
+- **Evidence summaries quoted client-controlled text without neutralising it.** A request
+  path containing CRLF came back inside an `id-enumeration` summary exactly as sent, which
+  forges log lines; escape sequences repainted terminals. Summaries and operator labels are
+  now cleaned centrally, so detectors written elsewhere are covered too.
+
+- **`probe-volume` was inert on three of the four adapters.** Only the Node adapter
+  reported the status the application answered, so on Fastify, Koa and every Fetch runtime
+  the detector was installed, listed, and structurally unable to fire.
+
 - **The "N not streamed" badge outlived the feed it described.** The badge adds two
   counts: the server's rate-cap `skipped`, which `FeedRing.clear()` resets, and the
   connection's lagged drops, which nothing did. After a Reset — or after the replace-sync
@@ -281,7 +507,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   looks like a challenge that worked, which is why it needed saying. `AuditWindow` gains
   `challengesSolved` and `challengeSolveRate`.
 
-- **`bothandlerjs check` — your policy against 526 shapes of real traffic.** The question
+- **`bothandlerjs check` — your policy against 545 shapes of real traffic.** The question
   the library is organised around, asked offline and before a deploy: *if I point this
   configuration at the actual internet, who gets hurt?* It exits non-zero if any case
   marked `human` is denied service, which is what makes it a CI step rather than a

package/README.md

@@ -23,7 +23,7 @@ No runtime dependencies. The library imports nothing but `node:` builtins, and C
 fails if that ever stops being true — so 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 needs structurally and imports neither `ioredis` nor
+the four commands it needs structurally and imports neither `ioredis` nor
 `node-redis`.
 
 ---
@@ -31,15 +31,15 @@ the five commands it needs structurally and imports neither `ioredis` nor
 ## Documentation
 
 The README is the argument and the shortest path to a working integration. Everything
-else lives in **[`docs/`](docs/index.md)** — thirty pages, one per question, each
-explaining why a thing exists as well as how to use it.
+else lives in **[`docs/`](docs/index.md)** — a page per question, each explaining why a
+thing exists as well as how to use it.
 
 | | |
 | --- | --- |
 | **[The course](docs/course/index.md)** | Sixteen lessons that build one integration, from a first assessment to a policy you can defend. Start here if the library is new to you. |
 | **[Start here](docs/index.md)** | [Installation](docs/start/installation.md) · [Your first integration](docs/start/first-integration.md) · [Choosing a policy](docs/start/choosing-a-policy.md) · [Upgrading](docs/start/upgrading.md) |
 | **Concepts** | [Evidence and certainty](docs/concepts/evidence.md) · [Verdicts and scores](docs/concepts/verdicts.md) · [The safety guard](docs/concepts/the-guard.md) · [Actors](docs/concepts/actors.md) · [Threat model](docs/concepts/threat-model.md) |
-| **[Detection](docs/detection/index.md)** | [The 20 detectors](docs/detection/detectors.md) · [Signatures](docs/detection/signatures.md) · [Verification](docs/detection/verification.md) · [Browser signals](docs/detection/client-signals.md) · [Writing a detector](docs/detection/writing-a-detector.md) |
+| **[Detection](docs/detection/index.md)** | [The detectors](docs/detection/detectors.md) · [Correlation](docs/detection/correlation.md) · [Signatures](docs/detection/signatures.md) · [Verification](docs/detection/verification.md) · [Browser signals](docs/detection/client-signals.md) · [Writing a detector](docs/detection/writing-a-detector.md) |
 | **[Policy](docs/policy/index.md)** | [Rules](docs/policy/rules.md) · [Actions](docs/policy/actions.md) · [Presets](docs/policy/presets.md) · [robots.txt](docs/policy/robots.md) · [The challenge](docs/challenge/index.md) |
 | **[Operations](docs/operations/index.md)** | [The dashboard](docs/operations/dashboard.md) · [Embedding it](docs/operations/embedding.md) · [Metrics](docs/operations/metrics.md) · [The audit](docs/operations/audit.md) · [Notifications](docs/operations/notifications.md) · [Runtime changes](docs/operations/runtime-changes.md) |
 | **[Integration](docs/integration/index.md)** | [Adapters](docs/integration/adapters.md) · [The client IP](docs/integration/client-ip.md) · [Stores](docs/integration/stores.md) |
@@ -233,12 +233,20 @@ all three.
   stale mapping is a false positive with a long half-life. Bring your own, from a
   source you refresh and can audit.
 - **Be right about a shared address.** Behind CGNAT, "one actor" is thousands of
-  people. That is why the behavioural signals are capped where they are.
+  people. That is why the behavioural signals are capped where they are. The optional
+  [marker cookie](docs/detection/correlation.md) narrows this — two requests carrying one
+  signed marker are one client rather than one address — but only for clients that keep
+  cookies, and the address remains what everything else is keyed on.
 - **Escalate on a wordlist walk.** `probe-signature` reads one request at a time, so a
   scanner working through five hundred paths produces five hundred separate
   observations rather than a mounting case. That is the price of a detector that runs
   unchanged over a log file; enumeration over time is what `rate-anomaly`, `cadence`
   and `crawl-breadth` are for.
+- **See an enumeration split across enough clients — unless you ask it to.** Divide a
+  range between five hundred addresses and every per-actor threshold is defeated by
+  construction, because each actor is genuinely unremarkable. `distributed-walk` finds it
+  in the union of what those addresses asked for, and needs the optional
+  [site baseline](docs/detection/correlation.md) and enough traffic to have one.
 
 ---
 
@@ -254,13 +262,13 @@ npm run build     # ESM + CJS + declarations
 npm run demo      # protected site :9673 + live dashboard :9674
 npm run demo:roles # the same dashboard behind roles: analyst :9684, operator :9685, admin :9686
 npm run simulate  # eighteen curated scenarios against the demo
-npm run simulate:corpus   # replay all 526 corpus cases over a real socket
+npm run simulate:corpus   # replay all 548 corpus cases over a real socket
 npm run bench     # hot-path benchmark, median of several rounds
-npm run corpus    # 526 shapes of real traffic against your policy
+npm run corpus    # 548 shapes of real traffic against your policy
 npm run example   # a minimal Express integration on :3000
 
 npx @osqd/bothandlerjs replay access.log     # what your policy would have done
-npx @osqd/bothandlerjs check                 # your policy against 526 shapes of real traffic
+npx @osqd/bothandlerjs check                 # your policy against 548 shapes of real traffic
 npx @osqd/bothandlerjs explain "curl/8.4.0"  # one request, and the evidence behind the verdict
 ```
 
@@ -276,7 +284,7 @@ src/
   config.ts          validation, defaults, client-IP resolution
   facts.ts           request normalisation
   state.ts           bounded per-actor behavioural memory
-  detectors/         twenty detectors + the signature database
+  detectors/         the detectors + the signature database
   policy/            rules, matcher, the safety guard, presets
   actions/           decision -> framework-neutral outcome
   challenge/         proof of work, signed tokens, the interstitial
@@ -287,7 +295,7 @@ src/
   adapters/          Express/Connect, Fastify, Koa, Fetch
   client/            browser-side signal script
   internal/          IP, crypto, UA, Aho-Corasick, LRU, DNS, HTTP
-  corpus/            526 shapes of real traffic, with provenance, and the harness
+  corpus/            548 shapes of real traffic, with provenance, and the harness
                      that runs them against your configuration
 demo/                the protected site and the live dashboard
 scripts/simulate.ts  the traffic simulator

package/dist/adapters/fastify.d.ts

@@ -15,6 +15,16 @@ export interface FastifyLikeReply {
     header(name: string, value: string): FastifyLikeReply;
     send(body: unknown): unknown;
     hijack?(): void;
+    /**
+     * The underlying response. Optional because this type describes the shape the adapter
+     * needs rather than Fastify's own, and a test double should not have to build one —
+     * but Fastify always provides it, and without it the status this request ends up
+     * answering is never reported back.
+     */
+    raw?: {
+        once(event: "finish", listener: () => void): unknown;
+        statusCode: number;
+    };
 }
 export interface FastifyAdapterOptions {
     tlsFingerprintHeader?: string;

package/dist/adapters/index.cjs

@@ -294,6 +294,7 @@ var SPECIAL_USE = new IpRangeSet(SPECIAL_USE_RANGES);
 
 // src/facts.ts
 var MAX_URL_LENGTH = 8192;
+var MAX_RAW_PATH = 512;
 var MAX_QUERY_PARAMS = 64;
 function createFacts(input) {
   const rawUrl = input.url ?? "/";
@@ -302,18 +303,21 @@ function createFacts(input) {
   const rawPath = queryStart === -1 ? url : url.slice(0, queryStart);
   const headers = /* @__PURE__ */ Object.create(null);
   for (const [name, value] of Object.entries(input.headers)) {
-    const joined = joinHeaderValue(value);
-    if (joined !== void 0) headers[name.toLowerCase()] = joined;
+    const lower = name.toLowerCase();
+    const joined = lower === "cookie" && Array.isArray(value) ? value.join("; ") : joinHeaderValue(value);
+    if (joined !== void 0) headers[lower] = joined;
   }
+  const normalized = normalizePath(rawPath);
   const facts = {
     method: (input.method ?? "GET").toUpperCase(),
-    path: normalizePath(rawPath),
+    path: normalized,
     query: parseQuery(queryStart === -1 ? "" : url.slice(queryStart + 1)),
     headers,
     headerOrder: extractOrder(input.rawHeaders, headers),
     ip: normalizeIp(input.ip) ?? input.ip,
     timestamp: input.timestamp ?? Date.now()
   };
+  if (rawPath !== normalized) facts.rawPath = rawPath.length > MAX_RAW_PATH ? rawPath.slice(0, MAX_RAW_PATH) : rawPath;
   const cookieHeader = headers["cookie"];
   if (cookieHeader !== void 0) facts.cookies = parseCookies(cookieHeader);
   if (input.protocol !== void 0) facts.protocol = input.protocol;
@@ -346,12 +350,23 @@ function parseQuery(search) {
   const query = /* @__PURE__ */ Object.create(null);
   if (search.length === 0) return query;
   let count = 0;
-  for (const [key, value] of new URLSearchParams(search)) {
+  for (const [key, value] of new URLSearchParams(boundedSearch(search))) {
     if (count++ >= MAX_QUERY_PARAMS) break;
     query[key] = value.length > 1024 ? value.slice(0, 1024) : value;
   }
   return query;
 }
+function boundedSearch(search) {
+  let seen = 0;
+  let at = search.charCodeAt(0) === 63 ? 1 : 0;
+  while (at < search.length) {
+    let end = search.indexOf("&", at);
+    if (end === -1) end = search.length;
+    if (end !== at && ++seen > MAX_QUERY_PARAMS) return search.slice(0, at - 1);
+    at = end + 1;
+  }
+  return search;
+}
 var MAX_ORDERED_HEADERS = 64;
 function extractOrder(rawHeaders, headers) {
   if (!rawHeaders || rawHeaders.length === 0) return EMPTY_ORDER;
@@ -474,6 +489,11 @@ function botHandler(handler, options = {}) {
           for (const [name, value] of Object.entries(outcome.responseHeaders)) response.setHeader(name, value);
         }
         if (outcome.delayMs !== void 0) await pause(outcome.delayMs);
+        if (typeof response.once === "function") {
+          response.once("finish", () => {
+            handler.recordOutcome(facts, response.statusCode);
+          });
+        }
         handedOff = true;
         next();
       } catch (error) {
@@ -570,6 +590,7 @@ function withBotHandler(handler, next, options = {}) {
     const decision = await evaluate3(request, context);
     if (decision.response) return decision.response;
     const response = await next(decision.request, context);
+    if (decision.result !== void 0) handler.recordOutcome(decision.result.assessment.facts, response.status);
     const extra = decision.result?.outcome.kind === "continue" ? decision.result.outcome.responseHeaders : void 0;
     if (!extra) return response;
     const merged = new Response(response.body, response);
@@ -653,6 +674,8 @@ async function evaluate(handler, options, mountChallenge, request, reply) {
     for (const [name, value] of Object.entries(outcome.responseHeaders)) reply.header(name, value);
   }
   if (outcome.delayMs !== void 0) await pause(outcome.delayMs);
+  const raw = reply.raw;
+  if (raw !== void 0) raw.once("finish", () => handler.recordOutcome(facts, raw.statusCode));
 }
 
 // src/adapters/koa.ts
@@ -660,13 +683,18 @@ function koaBotHandler(handler, options = {}) {
   const mountChallenge = options.mountChallengeEndpoint ?? true;
   return async function botHandlerMiddleware(context, next) {
     let proceed;
+    let facts;
     try {
-      proceed = await evaluate2(handler, mountChallenge, context);
+      const decision = await evaluate2(handler, mountChallenge, context);
+      proceed = decision.proceed;
+      facts = decision.facts;
     } catch (error) {
       handler.config.onError(error, { source: "adapter:koa" });
       proceed = true;
     }
-    if (proceed) await next();
+    if (!proceed) return;
+    await next();
+    if (facts !== void 0) handler.recordOutcome(facts, context.status);
   };
 }
 async function evaluate2(handler, mountChallenge, context) {
@@ -690,18 +718,18 @@ async function evaluate2(handler, mountChallenge, context) {
     context.set("cache-control", "no-store");
     if (verification.ok) context.set("set-cookie", verification.setCookie);
     context.body = verificationBody(verification);
-    return false;
+    return { proceed: false };
   }
   const { outcome } = await handler.handle(facts);
   if (outcome.kind === "drop") {
     context.req.socket.destroy();
-    return false;
+    return { proceed: false };
   }
   if (outcome.kind === "respond") {
     context.status = outcome.status;
     for (const [name, value] of Object.entries(outcome.headers)) context.set(name, value);
     context.body = outcome.body;
-    return false;
+    return { proceed: false };
   }
   for (const [name, value] of Object.entries(outcome.requestHeaders ?? {})) {
     context.req.headers[name] = value;
@@ -710,7 +738,7 @@ async function evaluate2(handler, mountChallenge, context) {
     for (const [name, value] of Object.entries(outcome.responseHeaders)) context.set(name, value);
   }
   if (outcome.delayMs !== void 0) await pause(outcome.delayMs);
-  return true;
+  return { proceed: true, facts };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {