@osqd/bothandlerjs 0.3.0

package/dist/config.d.ts

@@ -0,0 +1,316 @@
+import { IpRangeSet } from "./internal/ip.js";
+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 { BotSignature } from "./detectors/known-bots.js";
+import type { ActionParams, FalsePositivePolicy, Rule } from "./policy/types.js";
+import type { CustomHandler } from "./actions/types.js";
+import type { BotHandlerStore } from "./stores/types.js";
+import type { AuditOptions, TrafficAnomaly } from "./audit.js";
+import type { Decision } from "./policy/types.js";
+import type { MetricsOptions } from "./metrics.js";
+import type { NotificationOptions } from "./notify/hub.js";
+import type { ChallengeOptions } from "./challenge/index.js";
+import type { Assessment, RequestFacts } from "./types.js";
+/**
+ * How the client address is recovered from behind a proxy.
+ *
+ * This is the highest-consequence configuration in the library and the easiest to get
+ * wrong, so it has no convenient default: `trustProxy` is off, and with it off the
+ * socket address is used and `X-Forwarded-For` is ignored entirely.
+ *
+ * The reason is that `X-Forwarded-For` is a *client-supplied header*. If you trust it
+ * without knowing how many proxies actually sit in front of you, anyone can prepend a
+ * fake hop and choose the address you rate-limit, allowlist and block on. The
+ * failure is silent, and it turns every per-actor mechanism here into an attacker
+ * input. Configure `trustedProxies` if you can — it is the only variant that does not
+ * depend on getting a number right.
+ */
+export interface ProxyConfig {
+    /** Read the forwarded header at all. Default false. */
+    trustProxy?: boolean;
+    /**
+     * CIDRs of proxies you operate. The header is walked from the right, discarding
+     * addresses inside these ranges, and the first address outside them is the client.
+     * Robust against an extra hop appearing, and the recommended setting.
+     *
+     * The connecting peer counts as the first hop and is checked the same way. A
+     * request that arrives from outside these ranges did not come through your proxies,
+     * so its forwarded header is not evidence of anything and the socket address is
+     * used instead — which is what makes this variant safe on a server that is
+     * reachable both through the load balancer and directly.
+     */
+    trustedProxies?: readonly string[];
+    /**
+     * How many proxies sit in front of this process, when you cannot enumerate them.
+     * The Nth address from the right is taken. Default 1.
+     *
+     * If the chain turns out to be shorter than this, the socket address is used
+     * instead: a short chain means the request did not come through the expected
+     * topology, and every entry in it is then client-controlled. Prefer
+     * `trustedProxies`, which does not depend on getting a count right.
+     */
+    hops?: number;
+    /** Header carrying the chain. Default `"x-forwarded-for"`. */
+    header?: string;
+}
+export interface BotHandlerConfig {
+    /** Replaces the built-in detector set entirely. */
+    detectors?: readonly Detector[];
+    /** Appended to the built-in set. Ignored when `detectors` is given. */
+    extraDetectors?: readonly Detector[];
+    /** A named starting policy. Combined with `rules`, which are evaluated first. */
+    preset?: PresetName;
+    /** Your own rules, evaluated before any preset's. */
+    rules?: readonly Rule[];
+    /** Action when nothing matches. Default `allow`. */
+    defaultAction?: import("./policy/types.js").ActionName;
+    defaultActionParams?: ActionParams;
+    /** How strictly terminal actions are gated. Default `strict`. See {@link FalsePositivePolicy}. */
+    falsePositivePolicy?: FalsePositivePolicy;
+    /** Substituted when the guard blocks a terminal action. Default `challenge`. */
+    fallbackAction?: import("./policy/types.js").ActionName;
+    /** Score needed for a terminal action under `balanced`. Default 85. */
+    terminalScoreThreshold?: number;
+    /** Score at or above which an unproven request is `suspected-bot`. Default 60. */
+    suspectThreshold?: number;
+    /**
+     * Reject `certain` evidence that carries no `deterministicBasis`. Defaults to true
+     * unless `NODE_ENV` is `production`, where it downgrades to a warning so a
+     * third-party detector cannot take a live site down.
+     */
+    strictEvidence?: boolean;
+    /** Addresses and CIDRs exempt from detection entirely. Your monitors, your office, your CI. */
+    allowlist?: readonly string[];
+    /** Addresses and CIDRs treated as proven automation. An explicit local decision. */
+    denylist?: readonly string[];
+    /** Hosting-provider ranges. Supply your own; none ships with the library. */
+    datacenterRanges?: readonly string[];
+    /** Published crawler ranges, keyed by signature id, e.g. `{ gptbot: ["1.2.3.0/24"] }`. */
+    crawlerRanges?: Readonly<Record<string, readonly string[]>>;
+    proxy?: ProxyConfig;
+    /**
+     * Derives the key an actor is tracked under. Defaults to the client address.
+     *
+     * Worth replacing. An address is a poor identity — shared by a whole office,
+     * changed by a phone every few minutes — and every behavioural detector is only as
+     * good as this function. A session id, an authenticated user id, or an address
+     * combined with a TLS fingerprint all make the same detectors much sharper.
+     */
+    actorKey?: (facts: RequestFacts) => string;
+    /** Paths detection skips entirely: health checks, your own polling endpoints, static assets. */
+    ignorePaths?: readonly (string | RegExp)[];
+    /**
+     * Lets your application declare a request human — an authenticated session, a
+     * completed payment, whatever bar you set. Produces `certain` human evidence, the
+     * only conclusive human signal available, because it comes from you and not from
+     * the client.
+     */
+    isHuman?: (facts: RequestFacts) => boolean;
+    /** Enables the challenge action. Without it, rules asking for one degrade to `tag`. */
+    challenge?: Omit<ChallengeOptions, "store" | "clock">;
+    store?: BotHandlerStore;
+    /**
+     * Share `priorConfirmations` between replicas through the store. Default false.
+     *
+     * Behavioural state is process-local by design — see `state.ts` — because a round
+     * trip per request would buy accuracy for signals that are only ever allowed to raise
+     * suspicion. A **confirmation is not one of those.** `confirmed-bot` is a proven
+     * verdict: something declared itself, forged an identity, or walked into a trap. That
+     * is a fact about the client rather than a judgement about it, and behind eight
+     * replicas a fact established on one of them is unknown to the other seven — so a
+     * rule reading `minPriorConfirmations: 1` fires roughly an eighth as often as it
+     * reads.
+     *
+     * So proof travels and suspicion stays home. The cost is one store read the **first
+     * time each instance sees an actor** — not one per request — and it is never awaited:
+     * the request that triggered it is judged with whatever arrived before the detectors
+     * finished, and every request after it has the number. A store outage means the count
+     * falls back to what this process saw itself, which is where it was before.
+     *
+     * Needs a shared `store`. With the default in-memory one there is nothing to share
+     * with, and setting this does nothing at all.
+     */
+    shareConfirmations?: boolean;
+    notifications?: NotificationOptions;
+    handlers?: readonly CustomHandler[];
+    /** Replaces the built-in signature database. */
+    signatures?: readonly BotSignature[];
+    /** Appended to the built-in database. */
+    extraSignatures?: readonly BotSignature[];
+    /** Budget for each `io` detector, ms. Default 300. Exceeding it drops that detector, not the request. */
+    detectorTimeoutMs?: number;
+    /** How long an idle actor is remembered, ms. Default 900000. */
+    actorWindowMs?: number;
+    /**
+     * Maximum actors tracked concurrently. Default 20000.
+     *
+     * This is a memory budget: see the cap arithmetic in `state.ts`. Past the limit the
+     * least recently seen actor is evicted, never one still sending traffic.
+     */
+    maxActors?: number;
+    /**
+     * Put verdict headers on the *response*. Default false.
+     *
+     * Leave it off in production. An `X-Bot-Score` in the response is a live feedback
+     * signal for anyone tuning a scraper against you — they change one header, watch
+     * the number fall, and iterate. Request-side tagging gives your application the
+     * same information and tells the client nothing.
+     */
+    exposeVerdictHeaders?: boolean;
+    /**
+     * Collect counters. Default true — see {@link BotHandler.metrics}. Switching it off
+     * saves a few integer increments per request and costs you the ability to see what
+     * your policy is doing.
+     */
+    metrics?: boolean | MetricsOptions;
+    /**
+     * Watches the *shape* of your traffic and raises {@link BotHandlerConfig.onAnomaly}
+     * when it changes. `false` switches it off; the default is on with the shipped
+     * checks. See {@link AuditOptions}.
+     */
+    audit?: AuditOptions | false;
+    resolver?: DnsResolver;
+    clock?: Clock;
+    /** Every assessment, including the ones that concluded nothing. The firehose. */
+    onAssessment?: (assessment: Assessment) => void;
+    /** Every decision, paired with the assessment behind it. */
+    onDecision?: (event: {
+        assessment: Assessment;
+        decision: Decision;
+    }) => void;
+    /** A request that was actually denied: `block`, `drop` or `redirect`. */
+    onDenial?: (event: {
+        assessment: Assessment;
+        decision: Decision;
+    }) => void;
+    /**
+     * The safety guard replaced a terminal action with something recoverable.
+     *
+     * The most useful hook here, and the one worth paging on a rise in: it means your
+     * rules are asking to deny requests the evidence does not prove.
+     */
+    onDowngrade?: (event: {
+        assessment: Assessment;
+        decision: Decision;
+    }) => void;
+    /** A challenge was issued, solved or rejected. */
+    onChallenge?: (event: {
+        phase: "issued" | "solved" | "rejected";
+        actorKey?: string | undefined;
+    }) => void;
+    /**
+     * A detector threw or timed out. Operational: usually a resolver or a store, and a
+     * rising rate means detection is degraded rather than that traffic changed.
+     */
+    onDetectorFailure?: (event: {
+        detector: string;
+        reason: string;
+        message: string;
+        requestId: string;
+    }) => void;
+    /** The rule set was replaced at runtime. Your audit trail for {@link BotHandler.updatePolicy}. */
+    onPolicyChange?: (event: {
+        rules: readonly string[];
+        warnings: readonly string[];
+        by?: string | undefined;
+    }) => void;
+    /**
+     * The guard settings changed at runtime — `falsePositivePolicy`, `fallbackAction`,
+     * `defaultAction`, `terminalScoreThreshold` or `suspectThreshold`.
+     *
+     * Worth its own hook rather than folding into `onPolicyChange`: this is the change
+     * that decides whether an unproven verdict can deny anybody, and it is the one an
+     * audit trail wants named. Both the before and the after travel with it.
+     */
+    onGuardChange?: (event: {
+        before: import("./policy/policy.js").GuardSettings & {
+            suspectThreshold: number;
+        };
+        after: import("./policy/policy.js").GuardSettings & {
+            suspectThreshold: number;
+        };
+        by?: string | undefined;
+    }) => void;
+    /**
+     * A range set was replaced at runtime.
+     *
+     * The allowlist is the one worth watching: an address on it is not judged leniently,
+     * it is not judged at all, so a change to it changes what your bot handling can see.
+     */
+    onRangeChange?: (event: {
+        name: string;
+        size: number;
+        entries: readonly string[];
+        by?: string | undefined;
+    }) => void;
+    /** An actor's behavioural memory was forgotten, or the actor was cleared as human. */
+    onActorChange?: (event: {
+        key: string;
+        action: "forget" | "clear";
+        until?: number | undefined;
+        by?: string | undefined;
+    }) => void;
+    /** The audit noticed the traffic change shape. See {@link AuditOptions}. */
+    onAnomaly?: (anomaly: TrafficAnomaly) => void;
+    /** Called when a detector, sink or store fails. Wire it to your logs. */
+    onError?: (error: unknown, context: {
+        source: string;
+    }) => void;
+    /** Called on a misconfiguration noticed at runtime. Wire it to your logs. */
+    onWarning?: (message: string) => void;
+}
+export interface ResolvedConfig {
+    detectors: Detector[];
+    rules: Rule[];
+    ranges: Map<string, IpRangeSet>;
+    signatures: readonly BotSignature[];
+    proxy: Required<Omit<ProxyConfig, "trustedProxies">> & {
+        trustedProxies: IpRangeSet | undefined;
+    };
+    actorKey: (facts: RequestFacts) => string;
+    ignorePaths: readonly (string | RegExp)[];
+    suspectThreshold: number;
+    strictEvidence: boolean;
+    detectorTimeoutMs: number;
+    actorWindowMs: number;
+    maxActors: number;
+    exposeVerdictHeaders: boolean;
+    clock: Clock;
+    onError: (error: unknown, context: {
+        source: string;
+    }) => void;
+    onWarning: (message: string) => void;
+    /** Problems found while resolving. Fatal ones throw; these are advisory. */
+    warnings: string[];
+}
+/**
+ * Checks a rule list for the mistakes that are silent at runtime.
+ *
+ * Shared with {@link BotHandler.updatePolicy}, because rules can now be replaced while
+ * the process runs and a list swapped in from a dashboard deserves the same reading
+ * as one written in a config file. Structural problems throw; problems that merely
+ * make a rule useless are returned as warnings, since a policy that refuses to load
+ * over a dead rule is worse than one that says so.
+ */
+export declare function validateRules(rules: readonly Rule[]): string[];
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}
+/**
+ * Validates and normalises configuration.
+ *
+ * Invalid input throws here, at construction, rather than degrading quietly at
+ * request time. A mistyped CIDR that silently matches nothing is a security control
+ * that looks configured and is not — the worst possible state to be in, because
+ * everything appears to be working.
+ */
+export declare function resolveConfig(config?: BotHandlerConfig): ResolvedConfig;
+/**
+ * Recovers the client address from the socket address and the request headers.
+ *
+ * Exported because getting this right matters more than almost anything else here,
+ * and you may want to call it directly or test it in isolation.
+ */
+export declare function resolveClientIp(socketAddress: string | undefined, headers: Record<string, string | undefined>, proxy: ResolvedConfig["proxy"]): string;