@osqd/bothandlerjs 0.5.0 → 0.7.0

package/dist/dashboard/types.d.ts

@@ -443,6 +443,18 @@ export interface DashboardEntry {
     downgradedFrom?: ActionName | undefined;
     downgradeReason?: string | undefined;
     evidence: DashboardEvidence[];
+    /**
+     * What this request would have been had the shadowed detectors counted.
+     *
+     * Absent unless a shadowed detector found something, which is also when the `shadow`
+     * flag appears on one of the evidence entries above.
+     */
+    shadowVerdict?: {
+        verdict: Verdict;
+        botClass: BotClass;
+        score: number;
+        certain: boolean;
+    } | undefined;
     failures: Array<{
         detector: string;
         reason: string;
@@ -462,6 +474,8 @@ export interface DashboardEvidence {
     summary: string;
     certainty: Certainty;
     direction: EvidenceDirection;
+    /** From a shadowed detector: shown, counted, and part of no decision. */
+    shadow?: true | undefined;
     family?: string | undefined;
     deterministicBasis?: string | undefined;
     /**
@@ -541,6 +555,7 @@ export interface DashboardSnapshot {
         description: string;
         cost: string;
         stage: string;
+        shadow?: true | undefined;
     }>;
     rules: readonly string[];
     ranges: Array<{

package/dist/detectors/blended-identity.d.ts

@@ -0,0 +1,34 @@
+import type { Detector } from "./types.js";
+export interface BlendedIdentityOptions {
+    /** Distinct security-tool identities from one actor before it is reported. Default 2. */
+    scannerIdentities?: number;
+    /** Distinct verifiable crawler identities before it is reported. Default 2. */
+    crawlerIdentities?: number;
+}
+/**
+ * What a *series* of requests claimed, read against itself.
+ *
+ * Every identity check in this library reads one request: this User-Agent names this bot,
+ * and that claim is either confirmable or it is not. The set of claims an actor has made
+ * over time is a different object, and some sets are self-contradictory in a way no single
+ * member of them is.
+ *
+ * Unlike `identity-rotation`, these hold up under the default address-based actor key,
+ * which is the whole reason they are on by default and that one is not. A NAT gateway
+ * presents many browsers — that is what makes counting User-Agents useless there. It does
+ * not present sqlmap *and* nikto, and it does not claim to be Googlebot *and* Bingbot. The
+ * innocent explanation for a hundred browsers behind one address is an office; there is no
+ * corresponding innocent explanation for these.
+ *
+ * Three readings, and each is about a combination rather than a claim:
+ *
+ * - **Several security tools.** One address arriving as two or more named scanners is a
+ *   scan, not a coincidence. The tools announce themselves honestly, which is what makes
+ *   the *set* readable even though each member is only `declared-bot` on its own.
+ * - **Several verifiable crawlers.** At most one of Googlebot, Bingbot and Yandex can be
+ *   true of an address, because each publishes a proof tied to addresses it controls.
+ *   Claiming two is a forgery whether or not either was checked.
+ * - **A crawler that also probes.** An actor that sent a scanner payload and also claimed
+ *   to be a search crawler has told you which of the two is the lie.
+ */
+export declare function blendedIdentityDetector(options?: BlendedIdentityOptions): Detector;

package/dist/detectors/challenge-integrity.d.ts

@@ -0,0 +1,26 @@
+import type { Detector } from "./types.js";
+/**
+ * Answers to challenges that were well-formed and still wrong.
+ *
+ * The verification endpoint is deliberately not assessed — a client that has just been
+ * challenged must not be challenged again for trying to answer — so nothing else in the
+ * pipeline ever sees what happens there. Two of those outcomes say something about the
+ * client rather than about the request, and this is where they surface.
+ *
+ * **A solution submitted twice.** A challenge nonce is random, single-use and signed, so
+ * a second valid solution for one is not a coincidence: it is the same answer sent
+ * again, or one answer being shared out. The threshold is not one, because a flaky
+ * network and a retried POST produce exactly one.
+ *
+ * **A solution returned faster than the puzzle allows.** The work is measured on this
+ * server between issuing and receiving, so no client clock is involved, and the floor is
+ * set at a SHA-256 rate no browser has ever reached. Coming in under it means the answer
+ * was not computed by the script we sent.
+ */
+export interface ChallengeIntegrityOptions {
+    /** Replayed solutions before this says anything. Default 3. */
+    minReplays?: number;
+    /** Implausibly fast solutions before this says anything. Default 1. */
+    minImplausible?: number;
+}
+export declare function challengeIntegrityDetector(options?: ChallengeIntegrityOptions): Detector;

package/dist/detectors/challenge-reaction.d.ts

@@ -0,0 +1,39 @@
+import type { Detector } from "./types.js";
+/**
+ * What a client does when it is asked to prove something.
+ *
+ * Every other detector here observes traffic that would have happened anyway, and has
+ * to argue backwards from it. This one reads a reaction to a stimulus **we chose**, and
+ * that difference is what makes it worth having: we decided when the challenge went
+ * out, so a client that changes what it claims to be within seconds of receiving one is
+ * responding to it. There was no reason to look at that moment other than that we made
+ * it happen.
+ *
+ * Two reactions are worth reporting, and they mean different things.
+ *
+ * **Changing identity.** A client challenged as Chrome that returns as curl, or as
+ * Googlebot, is trying a different disguise to see whether the door opens. Software
+ * does not change what it is; an operator changes it, and the only reason to change it
+ * at that moment is the challenge.
+ *
+ * **Never answering, repeatedly.** A person who abandons one challenge is ordinary — a
+ * slow phone, a lost tab, a change of mind. A client asked five times that has never
+ * once come back is not abandoning: it is unable or unwilling, and both are facts about
+ * software rather than about a person's patience.
+ *
+ * **Why neither reaches `certain`, and why one is weaker than the other.** Both join
+ * two requests, and the join is the weak link. With a marker the join is cryptographic
+ * and the two requests provably came from one client. Without one they are tied by
+ * address alone, and a busy NAT will eventually put a different person's browser in the
+ * seconds after somebody else was challenged — so the same observation is reported a
+ * tier lower, because that is genuinely how much less it is worth. Never answering is
+ * capped lower still: a person with JavaScript disabled produces it forever, and they
+ * are a person.
+ */
+export interface ChallengeReactionOptions {
+    /** How soon after a challenge a change of identity counts as a reaction. Default 60s. */
+    windowMs?: number;
+    /** Unanswered challenges before that is worth reporting. Default 4. */
+    minUnsolved?: number;
+}
+export declare function challengeReactionDetector(options?: ChallengeReactionOptions): Detector;

package/dist/detectors/clearance.d.ts

@@ -1,25 +1,3 @@
 import type { Detector } from "./types.js";
 import type { ChallengeService } from "../challenge/index.js";
-/**
- * Reads a clearance token the client already holds.
- *
- * This is the library's only source of *human*-pointing evidence that is not a
- * guess about headers, and it is worth being exact about what each level earns,
- * because overstating any of them would undo the whole design.
- *
- * - **`operator`** is `certain`. Your application told us this is a person — an
- *   authenticated session, a completed purchase, whatever your own bar is. We are
- *   believing you, not deducing anything, which is the same reasoning that makes a
- *   client's self-declaration `certain` in the other direction.
- * - **`interaction`** is `strong`. A trusted input event was observed. Automation
- *   driving a real browser can synthesise something close, so this is very good
- *   evidence and not proof.
- * - **`pow`** is only `moderate`, and this is the number people are most tempted to
- *   inflate. A solved proof of work shows a JavaScript engine ran and CPU was spent.
- *   A headless Chrome does both, happily and at scale. It raises the cost of a scrape
- *   substantially; it says nothing whatsoever about whether a human is present.
- *
- * The token is bound to the actor and signed, so it cannot be lifted from one client
- * and replayed by another under a different actor key.
- */
-export declare function clearanceDetector(service: ChallengeService): Detector;
+export declare function clearanceDetector(service: ChallengeService, sharingThreshold?: number): Detector;

package/dist/detectors/id-enumeration.d.ts

@@ -0,0 +1,31 @@
+import type { Detector } from "./types.js";
+export interface IdEnumerationOptions {
+    /** Requests to one path shape before a walk is worth reporting. Default 30. */
+    minRequests?: number;
+    /**
+     * How completely those requests must cover the range they span. Default 0.9 — thirty
+     * requests reaching from id 1 to id 33 report; the same thirty scattered across a
+     * thousand ids do not.
+     */
+    density?: number;
+}
+/**
+ * Somebody working through the identifiers rather than following the links.
+ *
+ * `crawl-breadth` sees this as "many distinct paths", which is what it also sees when a
+ * person reads a documentation site — so it stays `weak` and nothing separates the two.
+ * Measured: `/user/1` through `/user/120` in order scored exactly the same as a hundred
+ * and twenty scattered ids, and the same again as ordinary article paths. All three
+ * `unknown`, all three 57.
+ *
+ * What separates them is not which ids were asked for but whether they *cover a range*.
+ * People arrive at ids through links, and links do not densely enumerate an integer
+ * interval; a harvester does nothing else. Thirty requests reaching from id 1 to id 33 is
+ * a walk. Thirty scattered across a hundred thousand is somebody reading.
+ *
+ * `moderate`, and the bar is set high on purpose. The awkward case is real: products in
+ * one category often carry consecutive ids, so somebody browsing a catalogue can produce a
+ * smaller version of this. Thirty requests covering ninety per cent of their own span is
+ * meant to be past what that produces, and it is still a shape rather than a motive.
+ */
+export declare function idEnumerationDetector(options?: IdEnumerationOptions): Detector;

package/dist/detectors/index.d.ts

@@ -18,7 +18,25 @@ export type { RateAnomalyOptions } from "./rate-anomaly.js";
 export { cadenceDetector } from "./cadence.js";
 export type { CadenceOptions } from "./cadence.js";
 export { crawlBreadthDetector } from "./crawl-breadth.js";
+export { parameterSweepDetector } from "./parameter-sweep.js";
+export { transportCoherenceDetector } from "./transport-coherence.js";
+export { probeVolumeDetector } from "./probe-volume.js";
+export { idEnumerationDetector } from "./id-enumeration.js";
+export { blendedIdentityDetector } from "./blended-identity.js";
+export { challengeReactionDetector } from "./challenge-reaction.js";
+export type { ChallengeReactionOptions } from "./challenge-reaction.js";
+export { challengeIntegrityDetector } from "./challenge-integrity.js";
+export { distributedWalkDetector, pathNoveltyDetector, missBaselineDetector, pathCampaignDetector } from "./site-baseline.js";
+export type { DistributedWalkOptions, PathNoveltyOptions, MissBaselineOptions, PathCampaignOptions } from "./site-baseline.js";
+export type { ChallengeIntegrityOptions } from "./challenge-integrity.js";
+export { identityDriftDetector, markerIntegrityDetector, markerPersistenceDetector, markerFanoutDetector } from "./marker.js";
+export type { IdentityDriftOptions, MarkerIntegrityOptions, MarkerPersistenceOptions, MarkerFanoutOptions } from "./marker.js";
 export type { CrawlBreadthOptions } from "./crawl-breadth.js";
+export type { ParameterSweepOptions } from "./parameter-sweep.js";
+export type { TransportCoherenceOptions } from "./transport-coherence.js";
+export type { ProbeVolumeOptions } from "./probe-volume.js";
+export type { IdEnumerationOptions } from "./id-enumeration.js";
+export type { BlendedIdentityOptions } from "./blended-identity.js";
 export { sessionIntegrityDetector } from "./session-integrity.js";
 export type { SessionIntegrityOptions } from "./session-integrity.js";
 export { identityRotationDetector } from "./identity-rotation.js";
@@ -31,6 +49,8 @@ export { tlsFingerprintDetector } from "./tls-fingerprint.js";
 export type { TlsFingerprintOptions, FingerprintProfile } from "./tls-fingerprint.js";
 export { clearanceDetector } from "./clearance.js";
 export { uaCoherenceDetector } from "./ua-coherence.js";
+export { targetIntegrityDetector } from "./target-integrity.js";
+export type { TargetIntegrityOptions } from "./target-integrity.js";
 export { probeSignatureDetector } from "./probe-signature.js";
 export type { ProbeSignatureOptions } from "./probe-signature.js";
 export { browsingCoherenceDetector } from "./browsing-coherence.js";
@@ -52,7 +72,10 @@ export type { BotSignature, BotCategory, Verification } from "./known-bots.js";
  *   running a browser newer than your data.
  *
  * `clearanceDetector` is not here either, because it needs the challenge service —
- * the engine adds it automatically once `challenge.secrets` is configured.
+ * the engine adds it automatically once `challenge.secrets` is configured. The three
+ * marker detectors work the same way: with no `probe` there is no cookie to have been
+ * issued, so they would be three permanently silent entries in every deployment that
+ * does not use one, and the engine adds them once `probe` is.
  */
 export declare function defaultDetectors(options?: {
     crawlerVerification?: CrawlerVerificationOptions;

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

@@ -35,6 +35,17 @@ export type BotCategory = "search" | "ai" | "seo" | "social" | "monitoring" | "a
  * to reach the page, and frequently does not know it is arriving as a bot at all.
  */
  | "accessibility"
+/**
+ * A mail or messaging gateway checking a link on somebody's behalf.
+ *
+ * Its own category because of who pays when it is blocked. A social preview that fails
+ * costs a card; one of these failing tells a real person, in their inbox, that the link
+ * they were sent could not be verified — and they were never the one crawling. They also
+ * arrive with none of a browser's marks: from a datacentre, once, with no cookie and no
+ * referer, moments after a message was delivered, which is a shape that reads as
+ * automation because it *is* automation, acting for a human.
+ */
+ | "email-security"
 /**
  * Research and measurement: universities, internet-measurement projects, plagiarism
  * and citation indexes.

package/dist/detectors/marker.d.ts

@@ -0,0 +1,106 @@
+import type { Detector } from "./types.js";
+/**
+ * What the marker cookie said about a client across its requests.
+ *
+ * These three read the same observation from three angles, and none of them can say
+ * anything at all unless `probe` is configured — a marker nobody issued is a marker
+ * nobody can fail to return. When the probe is off they return `undefined` on every
+ * request, which is the correct answer rather than a silent failure: absence of a
+ * marker is absence of information.
+ *
+ * See `docs/detection/correlation.md` for why a marker exists and what it costs.
+ */
+export interface IdentityDriftOptions {
+    /** Report a platform-only or language-only change. Default true, at `moderate`. */
+    reportSoftDrift?: boolean;
+}
+/**
+ * One client, two identities.
+ *
+ * This is the detector this library could not previously write. Correlating by address
+ * cannot distinguish "a client that claimed to be Chrome and then curl" from "two
+ * people behind one office connection", and guessing between them would either miss
+ * every rotation or accuse every shared network. A marker removes the ambiguity: both
+ * requests carried an HMAC only this server can produce, so they came from one client,
+ * and that client described itself two different ways.
+ *
+ * **The parts are weighed separately, because they are not equally suspicious.**
+ * A browser family that changes — Chrome to curl, Firefox to Googlebot — has no benign
+ * reading; software does not change what it is. A *platform* that changes does have
+ * one, and it is common: "Request desktop site" on a phone rewrites the User-Agent to
+ * claim a desktop, and the person doing it is a person. Language changes when someone
+ * changes their language. So the family carries the weight and the rest is reported
+ * softly, which is the difference between catching a rotation and blaming a visitor for
+ * using a browser feature.
+ */
+export declare function identityDriftDetector(options?: IdentityDriftOptions): Detector;
+export interface MarkerIntegrityOptions {
+    /** Ignored below this many forged presentations. Default 1. */
+    minForgeries?: number;
+}
+/**
+ * A marker that this server did not sign.
+ *
+ * Browsers do not edit their cookies. A marker that fails its HMAC was altered by
+ * whoever was holding it, and the only reason to alter an opaque signed value is to
+ * find out what the server does with a different one — which is what a scanner does and
+ * what a person browsing does not.
+ *
+ * **Why this stops at `strong`.** `certain` in this library means no benign explanation
+ * exists, and one does, thinly: a middlebox or a broken cookie jar can truncate or
+ * re-encode a value in transit. It is rare, it is not the client's fault, and it should
+ * cost a challenge rather than a door.
+ */
+export declare function markerIntegrityDetector(options?: MarkerIntegrityOptions): Detector;
+export interface MarkerPersistenceOptions {
+    /** Markers handed out with none returned before this says anything. Default 5. */
+    minIssued?: number;
+}
+/**
+ * A client that keeps cookies, but never ours.
+ *
+ * The obvious version of this detector reports any client that is handed a marker and
+ * never returns one — and that version is worth almost nothing, because
+ * `session-integrity` already reports a client that sends no cookie at all, and it does
+ * so with a better-calibrated weight. Two moderate signals for one observation is a
+ * double count, and the population it lands on is people who block cookies. Measured on
+ * the corpus, the overlapping version took `cookies-blocked` from 21 to 38 and put +24
+ * on five ordinary browsing sessions.
+ *
+ * So this asks the narrower question the marker can uniquely answer: the client is
+ * *demonstrably* keeping cookies — it sent some — and ours is not among them. A browser
+ * with a cookie jar puts every first-party cookie in it; a scraper replaying a captured
+ * session header sends the one cookie it was told to and stores nothing new.
+ *
+ * **Why `moderate` and never more.** A marker can go missing for reasons that are the
+ * operator's fault rather than the client's: `secure: true` on a page served over plain
+ * HTTP is never stored at all, and a `domain` that does not match the host is not sent
+ * back. Both would produce this for every visitor, which is exactly why it may never
+ * deny anybody on its own. Verified crawlers are never issued a marker, so they never
+ * appear here.
+ */
+export declare function markerPersistenceDetector(options?: MarkerPersistenceOptions): Detector;
+export interface MarkerFanoutOptions {
+    /** Distinct networks one marker may be presented from before this says anything. Default 16. */
+    minNetworks?: number;
+}
+/**
+ * One client, many networks.
+ *
+ * A marker comes back only from the client that received it, so a marker presented from
+ * sixteen different networks is one client that has moved across sixteen networks. The
+ * shape that produces is a scraper on a rotating proxy pool that keeps its cookie jar —
+ * which most of them do, because discarding it breaks the sites they are scraping.
+ *
+ * **Why this is capped at `moderate` and offered no higher.** The honest reading is that
+ * this signal cannot separate a proxy pool from a heavily mobile person. A phone on a
+ * carrier using CGNAT can be renumbered across a great many `/24`s in the twelve hours a
+ * marker lives, and so can anyone whose employer egresses through a rotating pool. Those
+ * are people. The count is real and it is worth combining with everything else, and it
+ * is never worth denying somebody on by itself.
+ *
+ * The counting is per process and bounded, so across replicas each sees only its share.
+ * That direction is deliberate: it undercounts, and undercounting says nothing where
+ * overcounting would accuse somebody.
+ */
+export declare function markerFanoutDetector(options?: MarkerFanoutOptions): Detector;

package/dist/detectors/parameter-sweep.d.ts

@@ -0,0 +1,39 @@
+import type { Detector } from "./types.js";
+export interface ParameterSweepOptions {
+    /**
+     * Distinct path-and-query combinations at or above which a sweep is worth reporting.
+     * Default 25. Cannot exceed {@link MAX_TRACKED_QUERIES}, where the count saturates;
+     * asking for more throws rather than never firing.
+     */
+    threshold?: number;
+    /**
+     * How many variants must sit on one path before this is a sweep rather than browsing.
+     * Default 8 — that is, twenty-five variants across three paths reports, and
+     * twenty-five variants across twenty paths does not.
+     */
+    variantsPerPath?: number;
+    /** Minimum requests before the shape means anything. Default 20. */
+    minRequests?: number;
+}
+/**
+ * The scraping that `crawl-breadth` cannot see.
+ *
+ * Breadth counts distinct *paths*, and a path has no query string on it. So the shape
+ * it reads as "somebody rereading one page" is also the shape of enumerating a
+ * catalogue: `/products?page=1` through `?page=200` is one path and two hundred
+ * requests. Measured, on the same two hundred requests expressed both ways — as
+ * distinct paths it scored 62 and was called `suspected-bot`; as `?page=N` it scored 55
+ * and passed as `unknown`. Paginated collection is not an exotic case, it is how
+ * catalogues, search results and APIs are actually taken.
+ *
+ * So this counts the other thing: distinct parameterisations, and how many of them
+ * stack onto a single path. Both halves are needed. A high variant count alone is
+ * ordinary — a shop's own visitors filter and sort — and it is the *concentration* that
+ * separates a person changing their mind from a machine walking an index.
+ *
+ * `weak`, and deliberately. A person paging through search results produces a smaller
+ * version of exactly this, and someone with a slow connection retrying looks similar
+ * again. It is a shape, not a motive; its value is as a second signal beside an actor
+ * that has already failed something sharper.
+ */
+export declare function parameterSweepDetector(options?: ParameterSweepOptions): Detector;

package/dist/detectors/probe-signature.d.ts

@@ -47,4 +47,31 @@ export interface ProbeSignatureOptions {
     /** Additional exact paths or prefixes to treat as exploit-tier probes. */
     extraPaths?: readonly string[];
 }
+/**
+ * Payload shapes in a query value or a path segment.
+ *
+ * Deliberately narrow, and split by how much of the observation is the payload itself.
+ * A generic "looks like SQL" pattern fires on a search box — someone looking up
+ * `union select` in the documentation of a database — and a generic "looks like HTML"
+ * pattern fires on a CMS preview and on every forum thread about cross-site
+ * scripting. Those are people, reading a site about the thing the pattern describes.
+ *
+ * So `sql` and `markup` patterns are reported at `moderate` on their own and are
+ * promoted to `strong` only when the value also carries **injection punctuation** — a
+ * quote, a comment marker, a statement separator — which is the part a person
+ * searching for the phrase does not type and the part an injection cannot work
+ * without. `always` patterns need no such qualification: nobody searches for a JNDI
+ * lookup with a live LDAP URL in it.
+ */
+type PayloadTier = "always" | "sql" | "markup";
 export declare function probeSignatureDetector(options?: ProbeSignatureOptions): Detector;
+/** Exported for the fuzz that proves the gate cannot reject something a pattern would match. */
+export declare const __payloadInternals: {
+    PAYLOADS: readonly {
+        pattern: RegExp;
+        what: string;
+        tier: PayloadTier;
+    }[];
+    PAYLOAD_GATE: RegExp;
+};
+export {};

package/dist/detectors/probe-volume.d.ts

@@ -0,0 +1,26 @@
+import type { Detector } from "./types.js";
+export interface ProbeVolumeOptions {
+    /** Reported responses before the ratio means anything. Default 20. */
+    minResponses?: number;
+    /** Share of them that must be misses. Default 0.8. */
+    missRatio?: number;
+}
+/**
+ * An actor that is looking for something rather than reading anything.
+ *
+ * The oldest tell there is for a scanner, and the one this library could not see: it
+ * decides *before* the response exists, which is what lets it shape the response and also
+ * what hides the status code from it. Fed back through `recordOutcome`, the shape is
+ * unmistakable — a person browsing a site does not generate forty misses in a row, and a
+ * wordlist does almost nothing else.
+ *
+ * Counts 404 and 410 only. A 403 is usually this library's own doing, and counting it
+ * would let a rule that challenges an actor manufacture the evidence for challenging it.
+ * A 500 is the site's problem and says nothing about the client.
+ *
+ * `moderate`, not higher. A site that has just moved its URLs produces this from perfectly
+ * ordinary readers, and so does a feed reader working through a list of removed articles.
+ * It is also entirely absent unless the application reports outcomes, which is why nothing
+ * else depends on it.
+ */
+export declare function probeVolumeDetector(options?: ProbeVolumeOptions): Detector;

package/dist/detectors/site-baseline.d.ts

@@ -0,0 +1,135 @@
+import type { Detector } from "./types.js";
+/**
+ * Three questions that can only be answered by comparing a client with everybody else.
+ *
+ * All of them read {@link SiteProfile}, all of them are silent unless `site` is
+ * configured, and all of them are silent again until it has warmed up. That last point
+ * is the one worth repeating: during warmup every path is rare because nothing has been
+ * seen, so a baseline consulted early does not merely fail, it fails *confidently*.
+ *
+ * None of them exceeds `moderate`. A baseline is a claim about what is normal for a
+ * site, and it is wrong in exactly the circumstances a site is most unusual — the day of
+ * a redesign, the hour a campaign lands, the migration that leaves half the URLs
+ * missing. That is not a reason to skip the comparison; it is a reason never to let one
+ * close a door on its own.
+ */
+export interface DistributedWalkOptions {
+    /** Distinct actors on one shape before it is worth reporting. Default 8. */
+    minActors?: number;
+    /** Distinct ids that must have been covered. Default 150. */
+    minIds?: number;
+    /** Fraction of the id range that must actually have been requested. Default 0.6. */
+    minCoverage?: number;
+    /** Highest visits-per-id that still reads as enumeration rather than reading. Default 1.3. */
+    maxRevisitRatio?: number;
+    /**
+     * Lowest visits-per-id that still reads as enumeration. Default 0.7.
+     *
+     * Guards the estimate rather than the traffic — see the note on coarsening below.
+     */
+    minRevisitRatio?: number;
+}
+/**
+ * An enumeration split across many clients so that no single one looks like one.
+ *
+ * This is the threat every per-actor threshold misses by construction. Take a wordlist,
+ * or an id range, and divide it between five hundred addresses at one request a minute
+ * each: every actor is unremarkable, `id-enumeration` never fires for anybody, and the
+ * range is still walked end to end. The only place it is visible is in the union.
+ *
+ * **What separates it from a popular site.** Many clients requesting numbered pages is
+ * ordinary — that is what a catalogue is. Two things are not. Enumeration *covers* a
+ * contiguous range rather than sampling the popular parts of it, and it visits each id
+ * about once, because there is no reason to fetch the same record twice. Real readers
+ * are the opposite on both counts: they cluster on a few popular ids and return to them.
+ * So coverage and the revisit ratio are both required, and either one alone would report
+ * an ordinary shop.
+ *
+ * **Why this is `moderate` and why it stays there.** The evidence is about the *shape*,
+ * and it is attached to a client that contributed to it — which is the closest this
+ * library comes to holding one client responsible for what others did. It is defensible
+ * only because the actor is genuinely part of the pattern being described, and only at a
+ * weight that cannot deny anybody by itself. A partner integration syncing a catalogue
+ * from a pool of workers produces this exactly, and is welcome traffic.
+ */
+export declare function distributedWalkDetector(options?: DistributedWalkOptions): Detector;
+export interface PathNoveltyOptions {
+    /** Requests before the ratio means anything. Default 30. */
+    minRequests?: number;
+    /** Share of an actor's requests that must be for paths nobody else asked for. Default 0.95. */
+    minNovelShare?: number;
+}
+/**
+ * A client asking for things this site has never been asked for.
+ *
+ * A wordlist is a list of paths that exist on *some* sites. On yours, most of them do
+ * not exist and nobody has ever requested them — which makes "nobody else has ever asked
+ * for this" a self-maintaining wordlist detector that needs no wordlist. It catches the
+ * scanner whose list is newer than `EXPLOIT_PATHS`, and it costs nothing to keep current.
+ *
+ * **The bar is deliberately close to 1.** Plenty of ordinary traffic requests novel
+ * paths: a search page with the query in the path, a CMS with per-article slugs, a
+ * long-tail catalogue where most items are viewed once a month. What none of those do is
+ * request *only* novel paths for thirty requests in a row. The share is the signal, not
+ * the count.
+ *
+ * **What it cannot see.** The profile is per process and its table evicts, so a path the
+ * site serves rarely can read as novel after it ages out. That direction produces false
+ * positives rather than misses, which is why this is capped at `moderate` and why the
+ * share is set where it is.
+ */
+export declare function pathNoveltyDetector(options?: PathNoveltyOptions): Detector;
+export interface MissBaselineOptions {
+    /** Answered requests from this actor before the comparison means anything. Default 20. */
+    minResponses?: number;
+    /** How many times the site's own miss rate this actor must exceed. Default 5. */
+    minRatio?: number;
+    /** Below this the actor's own miss rate is unremarkable whatever the site's is. Default 0.5. */
+    floor?: number;
+}
+/**
+ * A client missing far more than this site's visitors normally do.
+ *
+ * `probe-volume` asks whether an actor's requests are mostly misses, against a fixed
+ * threshold. That threshold is wrong on both kinds of site: on one mid-migration, where
+ * half of all traffic 404s, it reports everybody; on a tidy one where a miss is genuinely
+ * rare, a client missing a third of the time is remarkable and it says nothing.
+ *
+ * Comparing against the site's own rate fixes both, and is why this reports the ratio
+ * rather than the number. It needs the application to report outcomes, which every
+ * bundled adapter does.
+ */
+export declare function missBaselineDetector(options?: MissBaselineOptions): Detector;
+export interface PathCampaignOptions {
+    /** Distinct clients on a newly-appeared path before it is worth reporting. Default 12. */
+    minClients?: number;
+    /** Share of the answers to it that must be misses. Default 0.9. */
+    minMissShare?: number;
+    /** Answers needed before that share means anything. Default 10. */
+    minAnswered?: number;
+}
+/**
+ * A path this site has never served, suddenly being asked for by everybody.
+ *
+ * This is what a freshly published vulnerability looks like from inside a site: a URL
+ * nobody had ever requested is requested by hundreds of unrelated clients within an hour
+ * of the disclosure, because they are all running the same new list. It is the exact
+ * inverse of `path-novelty`, which reads one client asking for many unknown paths, and
+ * it catches the traffic that detector misses — a client running one probe and moving on
+ * looks like nothing at all on its own.
+ *
+ * **Why the miss rate is required, and not optional.** Many clients arriving at once on
+ * a brand-new URL is also precisely what a successful launch looks like: a page goes up,
+ * a newsletter goes out, and thousands of people request a path that did not exist
+ * yesterday. Counting clients alone would report every marketing campaign a site ever
+ * runs. What separates them is what the application answered — a launch returns a page,
+ * a probe returns nothing — so the miss share is what makes this a signal rather than a
+ * traffic alarm, and the detector is silent without outcomes being reported.
+ *
+ * **Why it is still `moderate`.** The client this is attached to did request the path,
+ * so it is describing something that client did; but *most* of the evidence is about
+ * everybody else's behaviour, and a client that followed a bad link from somewhere is
+ * indistinguishable here from one running the list. That is a real limit, not a
+ * conservative gesture.
+ */
+export declare function pathCampaignDetector(options?: PathCampaignOptions): Detector;

package/dist/detectors/target-integrity.d.ts

@@ -0,0 +1,16 @@
+import type { Detector } from "./types.js";
+export interface TargetIntegrityOptions {
+    /**
+     * Report a target that walks above the site root, e.g. `/../../etc/passwd`. Default
+     * true.
+     *
+     * Worth a switch because it is the one signal here a *broken* client produces as
+     * readily as a hostile one: a relative link resolved against the wrong base gives a
+     * client dots to send, and some feed readers and old link checkers duly send them.
+     * Encoding those dots is deliberate; writing them is a bug. Both are reported, the
+     * second at a lower tier, and this turns the second off for a site that has one of
+     * those clients and would rather not hear about it on every request.
+     */
+    reportPlainTraversal?: boolean;
+}
+export declare function targetIntegrityDetector(options?: TargetIntegrityOptions): Detector;