@osqd/bothandlerjs 0.4.0 → 0.5.0

package/dist/detectors/crawler-verification.d.ts

@@ -1,5 +1,38 @@
-import type { Detector } from "./types.js";
+import type { Detector, DetectionContext } from "./types.js";
+import type { BotSignature } from "./known-bots.js";
+/**
+ * What an operator's own check concluded about a claimed identity.
+ *
+ * Three answers, and the third is not a formality. "I could not tell" has to be
+ * expressible and has to mean *silence* — a verifier that returned false for both "this
+ * is a forgery" and "my key server timed out" would turn an outage into an accusation.
+ */
+export type VerificationOutcome = "verified" | "refuted" | "unknown";
+/**
+ * Your own answer to "is this really who it says it is".
+ *
+ * Called with the same context the built-in checks get, for one claimed signature. It
+ * may be async: the natural implementations are a lookup or a signature check.
+ */
+export type CrawlerVerifier = (ctx: DetectionContext, signature: BotSignature) => VerificationOutcome | Promise<VerificationOutcome>;
 export interface CrawlerVerificationOptions {
+    /**
+     * Verifiers of your own, by signature id — `{ googlebot: ..., gptbot: ... }`.
+     *
+     * Most of this database cannot be checked from inside a request: the operator
+     * publishes no DNS proof and no range list, and the claim is simply unfalsifiable.
+     * That is most bots, and until now it meant the library had nothing to offer an
+     * operator who *could* check — because their CDN had already verified the crawler and
+     * said so in a header, because the bot signs its requests, or because they hold the
+     * ASN data. Writing a whole detector to say so meant reimplementing the confirm and
+     * refute semantics in this file, including the part where an inconclusive answer must
+     * stay silent.
+     *
+     * A verifier here runs before the built-in check for that signature and a definite
+     * answer settles it, which also means no DNS lookup. `unknown` falls through to
+     * whatever this library can do on its own.
+     */
+    verifiers?: Readonly<Record<string, CrawlerVerifier>>;
     /**
      * Treat an address with no PTR record as a forged claim. Default true.
      *

package/dist/detectors/index.d.ts

@@ -1,3 +1,4 @@
+import type { CrawlerVerificationOptions } from "./crawler-verification.js";
 import type { Detector } from "./types.js";
 export type { DetectionContext, Detector, DetectorResult } from "./types.js";
 export { evidence, absenceIsMeaningful } from "./types.js";
@@ -53,4 +54,6 @@ export type { BotSignature, BotCategory, Verification } from "./known-bots.js";
  * `clearanceDetector` is not here either, because it needs the challenge service —
  * the engine adds it automatically once `challenge.secrets` is configured.
  */
-export declare function defaultDetectors(): Detector[];
+export declare function defaultDetectors(options?: {
+    crawlerVerification?: CrawlerVerificationOptions;
+}): Detector[];

package/dist/detectors/known-bots.d.ts

@@ -16,7 +16,35 @@ import { MultiPatternMatcher } from "../internal/matcher.js";
  */
 export type BotCategory = "search" | "ai" | "seo" | "social" | "monitoring" | "archive" | "feed" | "security" | "advertising" | "library" | "headless"
 /** A real browser engine embedded in a desktop application, with a person driving it. */
- | "embedded" | "other";
+ | "embedded"
+/**
+ * Price, stock and catalogue collection: comparison shopping, marketplace feeds,
+ * repricing tools.
+ *
+ * Its own category because it is the one kind of crawling a shop has a commercial
+ * opinion about rather than a technical one. It is not `seo` — nothing here is
+ * auditing your site for you — and it is not `scraper`, which is a *behavioural*
+ * verdict this library reaches on its own. This is a client that says what it is.
+ */
+ | "commerce"
+/**
+ * Accessibility auditing: contrast, landmarks, ARIA, WCAG conformance.
+ *
+ * Separated from `monitoring` because the answer is almost always different. A site
+ * owner who blocks uptime probes still wants the tool their accessibility team runs
+ * to reach the page, and frequently does not know it is arriving as a bot at all.
+ */
+ | "accessibility"
+/**
+ * Research and measurement: universities, internet-measurement projects, plagiarism
+ * and citation indexes.
+ *
+ * Distinct from `ai` on purpose. Both read the whole page and neither sends a person,
+ * but the decision differs: an operator refusing to feed a commercial model may be
+ * perfectly happy to appear in a citation index, and folding the two together forces
+ * one answer onto two questions.
+ */
+ | "academic" | "other";
 /** Every category, for anything that has to enumerate them — a rule editor, a report. */
 export declare const BOT_CATEGORIES: readonly BotCategory[];
 /**
@@ -40,6 +68,26 @@ export type Verification = {
 } | {
     kind: "ip-ranges";
     publishedAt?: string;
+}
+/**
+ * The operator publishes a proof this library cannot check by itself, and you can.
+ *
+ * A signed request under [Web Bot Auth](https://www.rfc-editor.org/rfc/rfc9421), a
+ * CDN that has already verified the crawler and says so in a header it adds, an ASN
+ * lookup against data you hold — all of them are conclusive, and none of them are
+ * something a detection library should be doing on its own: two need a network
+ * dependency and the third needs a key it has no business fetching.
+ *
+ * So the claim is marked verifiable-by-you, and stays *unverified* until you supply a
+ * verifier for it in `crawlerVerification.verifiers`. Marked and unsupplied behaves
+ * exactly like `none`: neither confirmed nor accused.
+ *
+ * `via` names the mechanism, for the operator reading this table to know what they
+ * would have to write.
+ */
+ | {
+    kind: "proof";
+    via: string;
 } | {
     kind: "none";
 };