@osqd/bothandlerjs 0.3.0 → 0.5.0

package/dist/config.d.ts

@@ -3,6 +3,7 @@ import type { PresetName } from "./policy/presets.js";
 import type { Clock } from "./internal/clock.js";
 import type { DnsResolver } from "./internal/dns.js";
 import type { Detector } from "./detectors/types.js";
+import type { CrawlerVerificationOptions } from "./detectors/crawler-verification.js";
 import type { BotSignature } from "./detectors/known-bots.js";
 import type { ActionParams, FalsePositivePolicy, Rule } from "./policy/types.js";
 import type { CustomHandler } from "./actions/types.js";
@@ -60,6 +61,15 @@ export interface BotHandlerConfig {
     detectors?: readonly Detector[];
     /** Appended to the built-in set. Ignored when `detectors` is given. */
     extraDetectors?: readonly Detector[];
+    /**
+     * How claimed crawler identities are confirmed or refuted.
+     *
+     * Chiefly `verifiers`: your own answer to "is this really Googlebot", for the many
+     * identities that publish no proof this library can check on its own. Also the two
+     * strictness flags, which were documented on the detector and reachable only by
+     * rebuilding the whole detector list.
+     */
+    crawlerVerification?: CrawlerVerificationOptions;
     /** A named starting policy. Combined with `rules`, which are evaluated first. */
     preset?: PresetName;
     /** Your own rules, evaluated before any preset's. */

package/dist/core.d.ts

@@ -50,9 +50,24 @@ export interface BotHandlerEvents extends Record<string, unknown> {
         decision: Decision;
     };
     /** A challenge was issued, solved or rejected. */
+    /**
+     * A challenge was issued, solved or turned down.
+     *
+     * `level`, `score` and `reason` are present only when the interaction challenge is on,
+     * and they are the whole basis for tuning it: without the score distribution an
+     * operator moving `interactionAt` is guessing, and without the reason a rise in
+     * rejections says nothing about whether the cause is bots or a browser that cannot
+     * run a probe.
+     */
     challenge: {
         phase: "issued" | "solved" | "rejected";
         actorKey?: string | undefined;
+        /** Clearance granted, on a solve. */
+        level?: "pow" | "interaction" | "operator" | undefined;
+        /** Interaction score, 0–1, when one was computed. */
+        score?: number | undefined;
+        /** Why it was turned down. */
+        reason?: string | undefined;
     };
     /**
      * A detector threw or timed out.

package/dist/corpus/index.cjs

@@ -3462,6 +3462,26 @@ var REPUTATION_CASES = [
     requests: [browser("chromeWindows")],
     expect: { verdict: "human", certain: true, detectors: ["clearance"], action: ["allow", "log", "tag"] }
   }),
+  human({
+    id: "cleared-by-interaction",
+    title: "A person who ticked the box on the interaction challenge",
+    category: "clearance",
+    provenance: "A signed clearance cookie granted after a trusted activation on a browser that passed the capability probes",
+    notes: "`strong` human evidence rather than `certain`, and the gap is the whole point. A trusted gesture in a rendering browser is a real cost imposed and it is still not proof of a person: a browser driven through the DevTools protocol dispatches genuine input events and renders genuine CSS. It outranks a bare proof of work because it costs more, and it stops short of `operator` because that assertion comes from the application and this one comes from the client.",
+    clearance: "interaction",
+    requests: [browser("chromeWindows")],
+    expect: { detectors: ["clearance"], neverAction: ["block", "drop", "redirect"] }
+  }),
+  human({
+    id: "cleared-by-interaction-on-a-phone",
+    title: "A person who tapped the box on a phone",
+    category: "clearance",
+    provenance: "A tap emits almost no pointermove, so the report carries no path at all",
+    notes: "Kept because the absence of a pointer path used to be scored as a mark against the client, which graded every phone \u2014 and every screen reader, switch and voice-control user \u2014 down to the weaker clearance for the way they use a computer. A tap is reported as touch and graded on its capabilities.",
+    clearance: "interaction",
+    requests: [browser("safariIos")],
+    expect: { detectors: ["clearance"], neverAction: ["block", "drop", "redirect"] }
+  }),
   bot({
     id: "cleared-but-proven-bot",
     title: "A proven bot presenting a valid clearance token",