@osqd/bothandlerjs 0.3.0

package/dist/challenge/language.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Choosing which language to challenge somebody in.
+ *
+ * The interstitial is the only page this library shows to a member of the public, and
+ * it is shown to them because a *probabilistic* verdict went against them. Serving
+ * "Checking your browser" in English to somebody whose browser has been asking for
+ * Japanese since the first request is the same unfairness the guard exists to prevent,
+ * applied to the one screen where it is most visible: a person who cannot read the page
+ * cannot find the contact link on it either.
+ *
+ * The library ships no translations and will not. A machine-translated apology on a
+ * page that just turned somebody away is worse than an honest English one — and only
+ * the operator knows which languages their audience actually reads. What this does is
+ * pick between the translations *you* supply.
+ *
+ * Pure and header-shaped, so it can be tested by calling it.
+ */
+/** One language's copy. Anything omitted falls back to the default text. */
+export interface ChallengeCopy {
+    title?: string;
+    message?: string;
+    contactHtml?: string;
+    /**
+     * The `lang` attribute to put on the document. Defaults to the key this copy is filed
+     * under.
+     *
+     * It matters more than it looks: a screen reader picks its voice and its pronunciation
+     * rules from this attribute, so Japanese text announced as `lang="en"` is read aloud
+     * by an English voice and is unintelligible. Getting the copy right and the attribute
+     * wrong helps nobody.
+     */
+    lang?: string;
+}
+/**
+ * The language tags in an `Accept-Language` header, best first.
+ *
+ * Lower-cased, `q` honoured, malformed entries dropped rather than fatal — this is a
+ * client-supplied header and the page it decides is one somebody is already having a
+ * bad time with. `*` is dropped too: it means "anything", which is what the default is
+ * for.
+ */
+export declare function parseAcceptLanguage(header: string | undefined): string[];
+/**
+ * The best available translation for what the client asked for.
+ *
+ * Exact tag first, then the primary subtag: somebody asking for `pt-BR` gets Brazilian
+ * Portuguese if you supply it and European Portuguese if that is all you have, which is
+ * far better than English. Somebody asking for `pt` never gets `pt-BR` silently,
+ * because a regional variant is a claim about an audience rather than a fallback for
+ * one.
+ *
+ * `undefined` means none matched, and the caller uses its defaults.
+ */
+export declare function pickTranslation(translations: Record<string, ChallengeCopy> | undefined, accepted: readonly string[]): {
+    tag: string;
+    copy: ChallengeCopy;
+} | undefined;

package/dist/challenge/page.d.ts

@@ -0,0 +1,42 @@
+export interface ChallengePageOptions {
+    /** Signed challenge blob the client must solve and return. */
+    challenge: string;
+    /** Leading zero bits required. */
+    difficulty: number;
+    /** Where the solution is POSTed. */
+    verifyPath: string;
+    /** Shown as the page heading. Default "Checking your browser". */
+    title?: string;
+    /** Shown under the heading. Keep it short and non-accusatory. */
+    message?: string;
+    /** Where a person who cannot complete the check should turn. Strongly recommended. */
+    contactHtml?: string;
+    /** Page language for the `lang` attribute. Default "en". */
+    lang?: string;
+}
+export interface RenderedChallenge {
+    html: string;
+    /**
+     * Nonce for the inline script. Put it in your CSP as `script-src 'nonce-…'`.
+     * The action layer does this for you; it is exposed for hand-rolled responses.
+     */
+    scriptNonce: string;
+}
+/**
+ * Renders the interstitial that carries the proof-of-work challenge.
+ *
+ * Design constraints, in the order they mattered:
+ *
+ * 1. **No external resources.** No CDN, no font, no image, no analytics. A page shown
+ *    to a client under suspicion must not become a way to make that client fetch
+ *    something else, and it has to work when the rest of your site is being shielded.
+ * 2. **Accessible.** People using screen readers hit these pages, and a check they
+ *    cannot perceive is indistinguishable from a broken site. The status is a live
+ *    region, focus is managed, and the failure state gives a real way to get help.
+ * 3. **Honest with the visitor.** No fake progress bar, no "verifying you are human"
+ *    when what is actually being verified is that a JavaScript engine is present.
+ * 4. **A visible way out.** `contactHtml` is not decoration. Anyone on a browser
+ *    without WebCrypto, with JavaScript disabled, or on a device too slow to finish
+ *    is a person your site has just locked out; they need somewhere to go.
+ */
+export declare function renderChallengePage(options: ChallengePageOptions): RenderedChallenge;

package/dist/challenge/pow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Proof of work.
+ *
+ * The client must find a counter such that `SHA-256(nonce + ":" + counter)` begins
+ * with `difficulty` zero bits. Verification is one hash; solving takes on average
+ * `2^difficulty` of them.
+ *
+ * **What this actually buys, stated plainly.** It does not identify anyone and it
+ * does not prove a human is present — a headless Chrome solves it as readily as a
+ * person's phone, just paying for the CPU. What it does is convert a scrape from
+ * free into merely cheap, and change the shape of the attack: a stateless scraper
+ * pulling a million pages must now run a JavaScript engine and burn CPU on every
+ * single one. That is often enough to make bulk extraction not worth doing, and it
+ * costs a real visitor a fraction of a second, once.
+ *
+ * Difficulty is in *bits*, so each step doubles the work. The default of 16 is around
+ * 65k hashes — tens of milliseconds in any modern browser. Past about 20 you are
+ * charging real people a visible delay, and the oldest and slowest devices — which
+ * disproportionately belong to the users least able to replace them — pay the most.
+ */
+/** Default difficulty in leading zero bits. ~65k hashes; a few tens of ms in a browser. */
+export declare const DEFAULT_DIFFICULTY = 16;
+/** Refuse to issue beyond this. Above it the wait becomes a usability problem for real visitors. */
+export declare const MAX_DIFFICULTY = 24;
+export declare function countLeadingZeroBits(digest: Uint8Array): number;
+/** True when `solution` satisfies the challenge. One hash — cheap enough for the request path. */
+export declare function verifyProofOfWork(nonce: string, solution: string, difficulty: number): boolean;
+/**
+ * Solves a challenge. Present for tests, examples and load simulation — the real
+ * solver is the browser-side script, and no server-side path calls this.
+ */
+export declare function solveProofOfWork(nonce: string, difficulty: number, maxIterations?: number): string | undefined;
+export declare function clampDifficulty(difficulty: number): number;

package/dist/challenge/token.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Signed, stateless tokens.
+ *
+ * Everything here is **signed and not encrypted**, and that is a deliberate,
+ * documented choice rather than an omission. The client can read every claim, so
+ * nothing secret may ever go in one — no user id, no email, no internal path. What
+ * the signature buys is integrity: the client cannot change the expiry, cannot move
+ * a token to a different actor, and cannot mint one.
+ *
+ * Key rotation is built in. `secrets[0]` signs; every entry verifies. To rotate,
+ * prepend the new secret and keep the old one for at least one token lifetime, then
+ * drop it.
+ */
+export interface ClearanceClaims {
+    v: 1;
+    /** Actor this token is bound to. A token stolen from one actor is invalid for another. */
+    sub: string;
+    /** Issued-at, ms since epoch. */
+    iat: number;
+    /** Expiry, ms since epoch. */
+    exp: number;
+    /** Unique id, so a solution can be spent exactly once. */
+    jti: string;
+    /** What was actually demonstrated. See {@link ClearanceLevel}. */
+    lvl: ClearanceLevel;
+}
+/**
+ * What a clearance token proves — and, just as importantly, what it does not.
+ *
+ * - `pow` — the client ran JavaScript, has WebCrypto, and spent measurable CPU. This
+ *   rules out cheap stateless scrapers. It does **not** prove a person is present: a
+ *   headless browser solves a proof of work exactly as well as a human's laptop, only
+ *   paying for the electricity. Treat it as a cost imposed, not as an identity.
+ * - `interaction` — a trusted input event was observed. Stronger, still forgeable by
+ *   a driven browser.
+ * - `operator` — your own application asserted this is a human, e.g. an authenticated
+ *   session. The only level this library treats as conclusive, because the assertion
+ *   comes from you rather than from the client.
+ */
+export type ClearanceLevel = "pow" | "interaction" | "operator";
+export interface ChallengeClaims {
+    v: 1;
+    sub: string;
+    iat: number;
+    exp: number;
+    /** Random value the proof of work is computed over. */
+    nonce: string;
+    /** Required leading zero bits in the digest. */
+    diff: number;
+}
+export type TokenVerification<T> = {
+    ok: true;
+    payload: T;
+} | {
+    ok: false;
+    reason: "malformed" | "bad-signature" | "expired" | "wrong-actor";
+};
+export declare function issueToken<T extends object>(payload: T, secrets: readonly string[]): string;
+/**
+ * Verifies signature and expiry.
+ *
+ * The order matters and is not arbitrary: the signature is checked *before* the
+ * claims are trusted for anything. Reading `exp` from an unverified token to decide
+ * whether to bother checking the signature is a classic way to turn a signed token
+ * into an unsigned one.
+ */
+export declare function verifyToken<T extends {
+    exp: number;
+    sub: string;
+}>(token: string, secrets: readonly string[], now: number, expectedSubject?: string | readonly string[]): TokenVerification<T>;
+export declare function newChallenge(subject: string, difficulty: number, ttlMs: number, now: number): ChallengeClaims;
+export declare function newClearance(subject: string, level: ClearanceLevel, ttlMs: number, now: number): ClearanceClaims;