@osqd/bothandlerjs 0.3.0

package/dist/dashboard/preview.d.ts

@@ -0,0 +1,45 @@
+import { Policy } from "../policy/policy.js";
+import type { DashboardEntry, PolicyPreview } from "./types.js";
+import type { Assessment } from "../types.js";
+import type { Rule } from "../policy/types.js";
+import type { GuardSettings } from "../policy/policy.js";
+/**
+ * "What would this rule set have done to the traffic I just watched?"
+ *
+ * This is the `replay` command's question, asked about the last few minutes instead of
+ * about a log file, and answered before the change is applied rather than after. The
+ * reason it can be answered at all is that {@link Policy.decide} is **pure**: it reads
+ * an assessment and returns a decision, touching no state, no store and no network. So
+ * a candidate policy can be run over the retained window as many times as somebody
+ * cares to edit it, and nothing about the running system moves.
+ *
+ * **What is faithful, and what is not.** Rule *matching* is exact: every field the
+ * matcher reads — verdict, class, identity, category, certainty, score, path, method,
+ * detector, prior confirmations — travels on the feed entry, so a rule matches here
+ * exactly when it would have matched then. The safety guard is exact too, for the same
+ * reason. What a preview cannot tell you is what the *action* would have done: a
+ * challenge might have been solved, a rate limit might not have been reached, a custom
+ * handler would have run code this does not run. It answers "which rule, and which
+ * action", which is the question an edit is about.
+ */
+export declare function previewPolicy(entries: readonly DashboardEntry[], live: Policy, candidate: Policy, warnings?: string[]): PolicyPreview;
+/**
+ * Rebuilds enough of an {@link Assessment} for the policy to decide about it.
+ *
+ * Deliberately built from the feed entry rather than from a retained assessment
+ * object. Keeping the real assessments alive would mean holding every request's full
+ * header set — cookies included — in memory for as long as the ring is long, to
+ * support a feature that only reads a dozen fields. The entry already carries those
+ * dozen fields, so the preview costs nothing extra and the headers stay where they
+ * were already redacted.
+ */
+export declare function assessmentFromEntry(entry: DashboardEntry): Assessment;
+/**
+ * Builds a candidate policy with the live policy's guard settings.
+ *
+ * The guard is copied rather than accepted from the caller, and that is the point: a
+ * preview — and the apply that may follow it — changes which rules exist and never how
+ * far one may go. Somebody editing rules in a browser cannot turn `strict` into
+ * `aggressive` by adding a field to the JSON, because the field is not read.
+ */
+export declare function candidatePolicy(rules: readonly Rule[], live: Policy, guard?: Partial<GuardSettings>): Policy;

package/dist/dashboard/server.d.ts

@@ -0,0 +1,70 @@
+import type { BotHandler } from "../core.js";
+import type { DashboardHandlerOptions, DashboardOptions, DashboardRequestHandler, DashboardServer } from "./types.js";
+/**
+ * The dashboard as a request handler, for mounting on a server you already have.
+ *
+ * The reason to want this is almost always TLS. `startDashboard` opens a plain HTTP
+ * listener, which is right on a laptop and wrong in most production networks: the
+ * certificate lives at an ingress, everything has to be reachable under one hostname,
+ * or the platform exposes exactly one port. None of that is an argument against the
+ * design — it is an argument about *which* server the page is served from.
+ *
+ * ```ts
+ * const dashboard = createDashboardHandler(botHandler, {
+ *   basePath: "/_bots",
+ *   auth: { authorize: (req) => sessionFrom(req)?.email ?? false },
+ * });
+ *
+ * https.createServer(tls, (req, res) => {
+ *   if (req.url?.startsWith("/_bots")) return dashboard(req, res);
+ *   return app(req, res);
+ * }).listen(443);
+ * ```
+ *
+ * Two things are different from the listening form, and both follow from not owning
+ * the socket:
+ *
+ * - **`auth` is required**, including the explicit `auth: false`. The listening form
+ *   may skip it on `127.0.0.1` because the operating system is then the access
+ *   control; here there is no bind address to inspect, so nothing can be assumed and
+ *   the safe assumption is "public".
+ * - **`close()` does not close a server it does not own.** It unsubscribes from the
+ *   engine, ends every event stream and stops the timers. Your server is yours.
+ *
+ * What has *not* changed is the reason the dashboard is a separate listener from your
+ * application: mount it on a server that does not run your bot handler. Serving it
+ * from inside the application it reports on means reading the dashboard shows up in
+ * the dashboard, and a challenge served to your site can lock you out of the tool you
+ * are using to read about it.
+ *
+ * `basePath` should name the path the page is served under, so the page can build its
+ * own URLs. Routing accepts the path with or without that prefix, so it works whether
+ * or not your framework strips the mount point before calling this.
+ */
+export declare function createDashboardHandler(handler: BotHandler, options: DashboardHandlerOptions): DashboardRequestHandler;
+/**
+ * Starts the dashboard on a listener of its own.
+ *
+ * Two decisions in here are load-bearing, and both are about the fact that this page
+ * is a description of your detection rather than a description of your traffic.
+ *
+ * **It binds to loopback by default.** The page lists client addresses and, on any
+ * row you click, the individual pieces of evidence with the reason each one fired.
+ * That is a tuning guide for whoever is scraping you: it names the next signal to fix.
+ * A dashboard reachable from the internet is a scraper's fastest route to a
+ * header set that passes.
+ *
+ * **It refuses to bind anywhere else without an explicit decision about access.**
+ * Not a warning in a log nobody reads — a `ConfigError` at startup, naming the two
+ * ways out: configure `auth`, or write `auth: false` to say you have another control
+ * in front of it. The failure mode this prevents is the one where a dashboard goes up
+ * on 0.0.0.0 for five minutes during an incident and stays there for two years.
+ *
+ * It is also, deliberately, a *separate listener* from the site it reports on. Serving
+ * it from inside your own application would put it behind the bot handler, where
+ * watching the dashboard shows up in the dashboard, and where a challenge served to
+ * your site can lock you out of the tool you are using to read about it. To serve it
+ * from a listener of your own — behind your own TLS, under your own path — see
+ * {@link createDashboardHandler}, which is the same dashboard without the socket.
+ */
+export declare function startDashboard(handler: BotHandler, options?: DashboardOptions): Promise<DashboardServer>;