@osqd/bothandlerjs 0.5.0 → 0.7.0

package/dist/corpus/schema.d.ts

@@ -61,6 +61,14 @@ export interface CaseRequest {
     tlsFingerprint?: string;
     /** Milliseconds after the case's start time. Drives the behavioural detectors. */
     atMs?: number;
+    /**
+     * What the application answered, if the case is about that.
+     *
+     * The engine decides before a response exists, so this is reported back afterwards the
+     * way an adapter reports it. Only cases about response shape need it — a scan that is
+     * almost all misses being the one that matters.
+     */
+    status?: number;
     /** The source could not supply the full header set. See `RequestFacts.partialHeaders`. */
     partialHeaders?: boolean;
 }
@@ -133,6 +141,31 @@ export interface TrafficCase {
      * from the request.
      */
     clearance?: "pow" | "interaction" | "operator";
+    /**
+     * Answers this actor has already given to challenges, established before the case runs.
+     *
+     * Declared rather than performed, for the same reason `clearance` is: the corpus
+     * replays *requests*, and these are outcomes of the challenge verification endpoint,
+     * which is deliberately not part of the request path. A case cannot submit a solution
+     * any more than it can sign its own clearance token, so it says what has already
+     * happened and the runner tells the handler.
+     */
+    /**
+     * Whether this client stores the cookies it is given. Default: inferred.
+     *
+     * The runner returns cookies the handler set to any case that sends a cookie of its
+     * own, because that is what having a jar means and modelling it otherwise made every
+     * browsing session look like a client that threw its marker away. A case sets this
+     * explicitly to say something the requests cannot: `false` models a client that sends
+     * one cookie it was configured with and stores nothing new.
+     */
+    keepsCookies?: boolean;
+    challengeHistory?: {
+        /** Solutions submitted for challenges that had already been solved. */
+        replayedSolutions?: number;
+        /** Solutions returned faster than the proof of work can be computed in a browser. */
+        implausibleSolves?: number;
+    };
     /**
      * A person whose *client software* declares itself automated, and why.
      *

package/dist/crawler-ranges.d.ts

@@ -81,6 +81,37 @@ export interface RefreshResult {
  * an error rather than a guess.
  */
 export declare function fetchCrawlerRanges(source: PublishedRangeSource, options?: RefreshOptions): Promise<string[]>;
+/** Where a reputation or hosting-provider address list is published. */
+export interface AddressListSource {
+    /** The range set to install it as. `denylist` blocks; `datacenter` corroborates. */
+    id: "denylist" | "datacenter" | "allowlist";
+    url: string;
+}
+export interface AddressListOptions extends RefreshOptions {
+    /** Entries to accept before refusing the list. Default 100,000. */
+    maxPrefixes?: number;
+}
+/**
+ * Fetches a published address list — a reputation feed, a hosting provider's own ranges.
+ *
+ * The same hardened path as {@link fetchCrawlerRanges}: HTTPS only, a size cap, comments
+ * stripped, JSON `prefixes` documents or one prefix per line, and a list that is empty,
+ * oversized or contains a block big enough to matter is refused **whole** rather than in
+ * part. It is a separate entry point because the limits differ — a reputation feed is
+ * thousands of entries where a crawler's is hundreds, and calling one a crawler's list in
+ * an error message helps nobody.
+ *
+ * It does not install anything. Hand the result to `updateRanges("denylist", …)` when you
+ * are ready, which is the same two-step the crawler path takes and for the same reason:
+ * fetching is the part that can fail, and installing is the part that changes behaviour.
+ *
+ * **A denylist entry is `certain`.** It does not corroborate anything — it decides, and it
+ * blocks people. A feed is somebody else's judgement about an address, refreshed on
+ * somebody else's schedule, and an address that was a bot last month may be a customer's
+ * home connection this month. Read what you are subscribing to, and prefer `datacenter`
+ * for anything you have not decided about yourself.
+ */
+export declare function fetchAddressList(source: AddressListSource, options?: AddressListOptions): Promise<string[]>;
 /**
  * Fetches every published list and installs it.
  *

package/dist/dashboard/client/actions.d.ts

@@ -14,4 +14,4 @@
  */
 export type AfterAction = () => void;
 export declare function isConfirming(): boolean;
-export declare function actorActions(key: string, after: AfterAction): HTMLElement[];
+export declare function actorActions(key: string, after: AfterAction, current?: string): HTMLElement[];

package/dist/dashboard/client/app.d.ts

@@ -19,8 +19,15 @@ export interface App {
         replace?: boolean;
         push?: boolean;
     }) => void;
-    /** Puts the feed's filter state into the URL, so a view can be sent to somebody. */
-    syncUrl: () => void;
+    /**
+     * Puts the feed's filter state and the Actors scope into the URL, so a view can be
+     * sent to somebody. `replace: false` for a discrete choice a click made, which the
+     * back button should undo; the default replaces, because a history entry per keystroke
+     * of the search box is not history.
+     */
+    syncUrl: (options?: {
+        replace?: boolean;
+    }) => void;
 }
 export declare const app: App;
 /**

package/dist/dashboard/client/boot.d.ts

@@ -1,5 +1,34 @@
 import type { Boot } from "./types.js";
-export declare const BOOT: Boot;
+/**
+ * Reassignable, and that is the fix for a real bug rather than a style choice.
+ *
+ * On the served page this module evaluates after the nonced script has stamped the
+ * global, so reading it once was right. Embedded, the element sets the global and *then*
+ * imports the client — correct, and not something it can actually guarantee, because any
+ * other code path that reaches a client module first evaluates this one first.
+ *
+ * One did. `disconnectedCallback` imports `stream.js` to close the stream, `stream.js`
+ * imports this, and a host page that mounts, unmounts and remounts the element before the
+ * first bootstrap fetch returns — React 18's development double-mount, exactly — ran that
+ * import while the global was still undefined. `base` then froze at `""` for the life of
+ * the page, so every request the dashboard made went to the host application's own origin
+ * root instead of to `src`: no dashboard, and a stray `/api/stream` arriving at somebody
+ * else's router.
+ *
+ * These are `let` and {@link applyBoot} replaces them, so being evaluated early costs
+ * nothing. ES module bindings are live and esbuild keeps them so — importers read the
+ * variable, not a copy of it — which is what makes this work without every consumer
+ * changing to a getter.
+ */
+export declare let BOOT: Boot;
 /** Every request the page makes is relative to the mount path. */
-export declare const API: string;
-export declare const SECTIONS: Required<import("./types.js").DashboardSections>;
+export declare let API: string;
+export declare let SECTIONS: Required<import("./types.js").DashboardSections>;
+/**
+ * Points this module at the payload the element fetched.
+ *
+ * Called before the client is imported. Ordering still matters for *drawing* — the client
+ * builds its tab strip from these — but no longer for correctness of the mount path,
+ * which is the part that was silently wrong.
+ */
+export declare function applyBoot(next: Boot): void;

package/dist/dashboard/client/query.d.ts

@@ -7,19 +7,32 @@ import type { DashboardEntry } from "./types.js";
  * question in the two cases somebody actually reaches for the box: an address that
  * also appears inside a User-Agent, and a path that is a prefix of ten others.
  *
- * So terms can name a field, and can be negated:
+ * So terms name a field, and combine:
  *
  * ```text
- * actor:203.0.113.4 -path:/health      that address, except its health checks
- * rule:no-scrapers action:tag          the rule that fired, and what it settled on
- * score:>70 -certain                   probabilistic traffic close to the line
- * "GET /api/v2/orders"                 a phrase, spaces and all
+ * actor:203.0.113.4 -path:/health          that address, except its health checks
+ * verdict:human $or verdict:unknown        either verdict
+ * $not path:/health                        the same as -path:/health, spelled out
+ * action:$in(block, drop)                  one of a set
+ * action:$notin(allow, tag)                none of a set
+ * (verdict:human $or score:<20) $and $not path:/health
+ * "GET /api/v2/orders"                     a phrase, spaces and all
  * ```
  *
- * Every term must match — this is an `AND`, because that is what narrowing means and
- * a filter box that quietly `OR`s is a filter box that lies. Anything that does not
- * parse as a field term is matched against the whole request, so a plain word still
- * behaves exactly as it did.
+ * **Adjacent terms still mean AND**, which is what narrowing means and what every
+ * existing query and saved filter relies on. `$and` is available for people who would
+ * rather write it than rely on juxtaposition; it parses to the same thing. `$or` binds
+ * more loosely than `$and`, and `$not` more tightly than either, so
+ * `a $or b $and c` reads as `a $or (b $and c)` — the conventional precedence, and the
+ * reason parentheses exist for the times it is not what you meant.
+ *
+ * Operator names are prefixed with `$` for one reason: a bare `or` is a word that
+ * appears in User-Agents and paths, and a language where an ordinary search word
+ * silently becomes an operator is a language that lies about what it matched.
+ *
+ * **Nothing here throws.** It backs a live search box, so half-typed input is the
+ * normal state rather than an error: an unclosed parenthesis, a dangling `$or`, a
+ * `$in(` with nothing after it all parse to the best reading available.
  *
  * Kept free of the DOM so it can be unit-tested, which is the point: this is the piece
  * of the page most likely to be wrong in a way nobody notices.
@@ -31,12 +44,59 @@ export interface Term {
     negated: boolean;
     /** For numeric fields: how `value` should be compared. */
     compare?: "<" | ">" | "=" | undefined;
+    /** For `$in` and `$notin`: the set. `value` holds the first, so a term always has one. */
+    values?: readonly string[] | undefined;
 }
-export declare function parseQuery(input: string): Term[];
+/**
+ * A parsed query.
+ *
+ * A tree rather than a list, because `$or` cannot be expressed in a list — which is
+ * what the flat version of this quietly told people by ignoring it.
+ */
+export type Filter = {
+    kind: "all";
+} | {
+    kind: "term";
+    term: Term;
+} | {
+    kind: "not";
+    of: Filter;
+} | {
+    kind: "and";
+    parts: readonly Filter[];
+} | {
+    kind: "or";
+    parts: readonly Filter[];
+};
+/** Every field name the language accepts, including the aliases. For suggestions. */
+export declare const FIELD_NAMES: readonly string[];
+/**
+ * Values worth offering for the fields that have a fixed set of them.
+ *
+ * Only where the set really is closed. `rule`, `identity` and `path` take anything, and
+ * offering a guess there would be inventing options rather than completing them.
+ */
+export declare const FIELD_VALUES: Readonly<Record<string, readonly string[]>>;
+/**
+ * What to offer for the token the caret is sitting in.
+ *
+ * Returns the completions and the span they would replace, so the caller can put one in
+ * without disturbing the rest of the query. A token that already names a field with a
+ * closed value set completes the value; anything else completes the field name.
+ */
+export declare function suggestFor(input: string, caret: number): {
+    options: readonly string[];
+    from: number;
+    to: number;
+};
+/** The operator words the language understands. Offered by the completions too. */
+export declare const OPERATORS: readonly string[];
+/** Parses a query. An empty or unparseable one matches everything. */
+export declare function parseFilter(input: string): Filter;
 /** Everything about a request, as one lower-case string. What a free term is matched against. */
 export declare function searchableText(entry: DashboardEntry): string;
-/** True when every term is satisfied. An empty query matches everything. */
-export declare function matchesQuery(terms: readonly Term[], entry: DashboardEntry, haystack: string): boolean;
+/** True when the query is satisfied. An empty one matches everything. */
+export declare function matches(filter: Filter, entry: DashboardEntry, haystack: string): boolean;
 /** The named filter buttons, which are a second, independent narrowing. */
 export type FilterName = "all" | "proven" | "suspected" | "human" | "guard" | "deny" | "mitigate" | "allow";
 export declare function matchesFilter(filter: FilterName, entry: DashboardEntry): boolean;

package/dist/dashboard/client/registry.d.ts

@@ -1,4 +1,29 @@
+import type { ActorRow } from "./types.js";
 export declare function loadActors(): Promise<void>;
 /** Polls while the screen is showing, and stops the moment it is not. */
 export declare function trackActors(): void;
+/**
+ * The actors visible in the feed you are looking at.
+ *
+ * The registry answers "who is hitting me hardest", which is a different question from
+ * "who is in *this*" — and once a filter is on, the second one is usually what somebody
+ * has in mind. Derived from the rows the feed is already showing, so it narrows with the
+ * filter, the timeframe and the search without another request.
+ *
+ * Three columns are left blank on purpose. `Per min`, `Cadence` and `Unsolved` are
+ * properties of the whole actor as the engine sees it, and the feed's ring holds a few
+ * hundred requests rather than a client's history — computing them from that slice would
+ * put a confident number under a heading that means something else. A dash says "ask the
+ * registry", which is the button next to it.
+ */
+export declare function feedActors(): ActorRow[];
+/**
+ * Moves the toggle to `scope` and redraws, without touching the URL.
+ *
+ * Separate from the click handler because the URL is also an input: opening a link and
+ * pressing Back both arrive here, and neither should write the address they just read.
+ */
+export declare function applyActorScope(scope: "tracked" | "feed"): void;
+/** Wires the tracked/shown toggle. Called once. */
+export declare function initActorScope(): void;
 export declare function drawActors(): void;

package/dist/dashboard/client/saved.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Filters somebody saved.
+ *
+ * They live in this browser rather than on the handler, and that is a decision worth
+ * stating. A saved filter is a personal working note — the view one operator returns to
+ * during an incident — not configuration the whole team shares. Keeping it here means it
+ * needs no write endpoint, no auth decision about who may change whose, and no migration
+ * when the handler restarts. The cost is that it does not follow you to another machine,
+ * which is the right trade for a bookmark.
+ *
+ * Hidden traffic used to live here too, as a second list. It does not any more: `$not`
+ * in the query says the same thing and, unlike a list in one person's browser, travels
+ * in the URL — so a view with the noise taken out is something you can send somebody.
+ *
+ * Every read and write is wrapped: a private window, cleared site data or a browser set to
+ * refuse storage all throw on access rather than returning nothing, and a dashboard that
+ * cannot save a bookmark must still show the traffic.
+ */
+export interface SavedFilter {
+    name: string;
+    /** The query text, exactly as typed. */
+    query: string;
+    /** The chip it was saved with, because a filter is usually both. */
+    filter: string;
+}
+export declare function savedFilters(): SavedFilter[];
+/** Saves under a name, replacing any filter already using it. */
+export declare function saveFilter(entry: SavedFilter): SavedFilter[];
+export declare function deleteFilter(name: string): SavedFilter[];

package/dist/dashboard/client/store.d.ts

@@ -1,5 +1,5 @@
 import type { EditorRule } from "./draft.js";
-import type { FilterName, Term } from "./query.js";
+import type { Filter, FilterName } from "./query.js";
 import type { ActorRow, DashboardEntry, Policy, Row, Snapshot, TabName } from "./types.js";
 /** Rows built into the table at once. Beyond this a feed is scrolled past, not read. */
 export declare const FEED_LIMIT = 300;
@@ -11,10 +11,13 @@ export interface State {
     /** The Actors screen's list, fetched rather than streamed. See `registry.ts`. */
     actors: ActorRow[];
     actorsTracked: number;
+    /** Which population the Actors screen is listing. See `registry.feedActors`. */
+    actorScope: "tracked" | "feed";
     paused: boolean;
     filter: FilterName;
     search: string;
-    terms: Term[];
+    /** The parsed search. A tree, so `$or` means something. */
+    query: Filter;
     tab: TabName;
     open: Set<string>;
     actor: string | undefined;
@@ -49,6 +52,15 @@ export interface State {
     /** How many rows a page of each table holds. Chosen in the page, not configured. */
     feedPageSize: number;
     actorsPageSize: number;
+    /**
+     * The window somebody asked to look at, as absolute instants.
+     *
+     * Either end may be left open, which is what makes one control answer all three of the
+     * questions people actually ask: from an incident until now, from the beginning until
+     * something stopped, or between two moments.
+     */
+    fromMs: number | undefined;
+    toMs: number | undefined;
     /**
      * How many skipped entries have already been fetched back and merged.
      *
@@ -70,6 +82,8 @@ export declare const state: State;
 export declare function ingest(entry: DashboardEntry): void;
 export declare function clearFeed(): void;
 export declare function setSearch(value: string): void;
+/** Sets the window somebody is looking at. Either end may be left open. */
+export declare function setTimeframe(from: number | undefined, to: number | undefined): void;
 /** Back to the live first page, thawed. Called whenever what matches changes. */
 export declare function resetPaging(): void;
 /**

package/dist/dashboard/client/types.d.ts

@@ -55,6 +55,8 @@ export interface Snapshot extends DashboardSnapshot {
  * of the store came to fail on `HTMLInputElement`.
  */
 export interface ActorRow {
+    /** A name somebody gave this actor. Never read by detection. */
+    label?: string | undefined;
     key: string;
     requests: number;
     recentRate: number;