@naulon/enforce 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @naulon/enforce
+
+The runtime-agnostic toll-decision kernel plus the in-app enforcement middleware.
+
+This is the neutral low-level core that both `@naulon/tollgate` (the gate shell —
+the reverse-proxy that boots `createApp`) and `@naulon/sdk` (the publisher SDK)
+sit **above**, with no dependency cycle. It depends only on `@naulon/shared` (and
+`viem`, for the holder-of-key proof). The heavy settlement path — the Circle
+facilitator, the pending-leg drain — stays in `@naulon/tollgate`; nothing here
+imports `@circle-fin/x402-batching`.
+
+## Why it exists
+
+`decide()` is one pure function: given a web `Request` and a known publisher, it
+returns a verdict — serve free, refuse, or `402` with the payment legs — and
+performs **no** side effects (no proxy, no settle, no observe). Extracting it lets
+two very different runtimes reach the *same* verdict:
+
+- **The gate** (`@naulon/tollgate`) runs `decide()` inside its Hono reverse proxy.
+- **In-app middleware** runs the *identical* `decide()` in the publisher's own app,
+  so an agent's request reaches the origin directly instead of routing through the
+  fleet's single egress IP (which an origin edge can rate-limit).
+
+Both build a byte-identical `402`, because they share this code.
+
+## Exports
+
+### `@naulon/enforce`
+
+The decision kernel and the framework-agnostic middleware core:
+
+- `decide(input)` — the pure verdict function.
+- `naulonMiddleware(opts)` — takes a `Request`, returns `{ response, setHeaders }`:
+  a `Response` to short-circuit (`402`/`403`), or `null` to let the app render
+  (with `setHeaders` to attach to the app's response on a paid pass).
+- `withNaulon(handler, opts)` — wrap a generic `fetch` handler.
+- `localQuoteSource(fn)` / `httpQuoteSource(url, key)` — pluggable price + payees.
+- The classification, Web Bot Auth, nonce, and proof primitives (`classify`,
+  `verifyBotAuth`, …) and the x402 build side (`build402`, `buildRequirements`).
+
+### `@naulon/enforce/next`
+
+- `createNaulonMiddleware(opts, NextResponse)` — the Next.js App Router adapter.
+  It has no hard `next` dependency; you inject `NextResponse` (your app already has
+  it), keeping the core framework-agnostic.
+
+## Usage
+
+```ts
+// middleware.ts (Next.js App Router)
+import { NextResponse } from "next/server";
+import { createNaulonMiddleware } from "@naulon/enforce/next";
+import { httpQuoteSource } from "@naulon/enforce";
+
+export const middleware = createNaulonMiddleware(
+  {
+    publisher: { id: "your-site", articlePrefixes: ["/articles/"] },
+    quote: httpQuoteSource("https://<your-control-plane>/_naulon/quote", process.env.NAULON_API_KEY!),
+    verifyUrl: "https://<your-control-plane>/_naulon/verify",
+    apiKey: process.env.NAULON_API_KEY!,
+  },
+  NextResponse,
+);
+
+export const config = { matcher: ["/articles/:path*"] };
+```
+
+`quote` and `verifyUrl` point at whatever runs the money + catalog legs — the
+managed control plane, or your own self-hosted `POST /_naulon/verify` +
+`GET /_naulon/quote`. The middleware never holds funds: it forwards the buyer's
+signed payment to `verifyUrl`, which settles buyer → author directly.
+
+## Layering
+
+```
+@naulon/shared
+      ▲
+@naulon/enforce        ← this package (decision kernel + middleware)
+      ▲
+@naulon/tollgate       (the gate shell runs decide() inside its reverse proxy)
+```
+
+A publisher vendors `@naulon/enforce` directly (it builds to its own `dist/`
+tarball) and wires the middleware; the gate consumes the very same package, which
+is what guarantees both reach an identical verdict. `@naulon/enforce` is
+deliberately NOT re-exported through `@naulon/sdk` — the SDK imports `@naulon/shared`,
+which re-exports the SDK, so an `sdk → enforce` edge would form a declaration-build
+cycle. Keeping enforce standalone (a second, small dependency alongside the SDK)
+avoids that and keeps the package graph a clean chain.

package/dist/agentDetect.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Human vs. machine classification — the hinge of the whole thesis.
+ *
+ * "Humans read free, forever. Machines pay." Everything downstream trusts this
+ * call. The asymmetry that matters:
+ *
+ *   - False positive (human flagged as agent) -> a human hits a 402 paywall.
+ *     This BREAKS the "open to all" promise. Worst outcome. Bias away from it.
+ *   - False negative (agent flagged as human) -> a crawler reads free. We lose a
+ *     micro-toll. Cheap. Tolerable.
+ *
+ * So the classifier should be conservative: only charge when we're confident the
+ * caller is a machine. Signed intent (an agent that *declares* itself via the
+ * x402 handshake) is the strongest, cleanest signal — it sidesteps the UA
+ * arms race entirely.
+ */
+import type { VerifiedAgent } from "./botAuth.ts";
+export type Verdict = {
+    kind: "human" | "agent";
+    reason: string;
+    confidence: number;
+};
+/** Request facts the classifier reasons over (framework-agnostic). */
+export interface RequestSignals {
+    userAgent: string;
+    /** Present when the caller already speaks x402 (declared intent to pay). */
+    hasPaymentHeader: boolean;
+    /** Explicit opt-in header an agent may send: `X-Naulon-Agent: <id>`. */
+    declaredAgentId: string | null;
+    /** Accept header — browsers ask for text/html; many bots don't. */
+    accept: string;
+    headers: Record<string, string>;
+    /**
+     * Cryptographically verified Web Bot Auth identity (RFC 9421/Ed25519), when
+     * the request carried a valid signature. Computed once in app.ts — only for
+     * requests that present the three signature headers; everyone else pays zero
+     * cost and classifies exactly as before.
+     */
+    verifiedAgent?: VerifiedAgent | null;
+}
+/** Per-publisher classification policy the gate supplies from `PublisherConfig`. */
+export interface ClassifyPolicy {
+    /**
+     * Verified search / discovery crawler UA fragments that read FREE for this
+     * publisher (their SEO allowlist). Honored ahead of the known-agent list, so an
+     * allowlisted crawler is freed even if its UA also looks like a bot — the point
+     * is to never toll the crawlers a publisher needs for indexing. Matched
+     * case-insensitively against the user-agent. UA is spoofable; verifying crawler
+     * identity (reverse DNS / Web Bot Auth) is a later hardening — for now a
+     * publisher's own allowlist is the stored intent we honor.
+     */
+    seoAllowlist?: string[];
+    /**
+     * Publisher-charged UA fragments. Honored between the allowlist and the built-in
+     * known-agent list: fragments a publisher explicitly charges are classified as
+     * agents even when the conservative default would read the UA as browser-shaped or
+     * ambiguous (and thus free). Allow wins over charge on overlap.
+     */
+    chargeList?: string[];
+}
+/**
+ * First fragment (case-insensitive substring) of `fragments` found in `ua`,
+ * else undefined. The one matching primitive the tri-state policy shares with
+ * the allowlist path — swap THIS for verified identity (Web Bot Auth) later.
+ */
+export declare function matchUaFragment(ua: string, fragments: string[] | undefined): string | undefined;
+/**
+ * Classify a request as human or agent.
+ *
+ * TODO(you): implement the core heuristic. A starter is provided so the gate
+ * runs today, but this decision shapes the product — own it. Consider:
+ *
+ *   1. Declared intent first. `signals.hasPaymentHeader` or
+ *      `signals.declaredAgentId` => almost certainly an agent that WANTS to pay.
+ *      Treat as high-confidence agent. (Already wired below — keep it first.)
+ *   2. Known-bot UA match => agent, but lower confidence (UAs are spoofable and
+ *      churn). Decide how much weight to give a raw UA match.
+ *   3. Browser-shaped requests (Accept: text/html, sec-fetch-* headers,
+ *      Accept-Language present) => lean human. Decide your "looks like a real
+ *      browser" bar.
+ *   4. The ambiguous middle (empty UA, generic Accept, no browser headers).
+ *      THIS is the real design call: default-allow (favor humans, lose tolls) or
+ *      default-charge (capture tolls, risk paywalling a human)? Given the
+ *      asymmetry above, the starter defaults to HUMAN. Change it if you disagree
+ *      — and write down why.
+ *
+ * Return a Verdict with a `reason` (it surfaces in logs + the demo) and a
+ * `confidence` in [0,1].
+ *
+ * `policy` carries per-publisher overrides (the SEO allowlist); the single-tenant
+ * default passes none and behaves exactly as before.
+ */
+export declare function classify(signals: RequestSignals, policy?: ClassifyPolicy): Verdict;
+//# sourceMappingURL=agentDetect.d.ts.map

package/dist/agentDetect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDetect.d.ts","sourceRoot":"","sources":["../src/agentDetect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACtC;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AA6CD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CA2DlF"}

package/dist/agentDetect.js

@@ -0,0 +1,149 @@
+/**
+ * Human vs. machine classification — the hinge of the whole thesis.
+ *
+ * "Humans read free, forever. Machines pay." Everything downstream trusts this
+ * call. The asymmetry that matters:
+ *
+ *   - False positive (human flagged as agent) -> a human hits a 402 paywall.
+ *     This BREAKS the "open to all" promise. Worst outcome. Bias away from it.
+ *   - False negative (agent flagged as human) -> a crawler reads free. We lose a
+ *     micro-toll. Cheap. Tolerable.
+ *
+ * So the classifier should be conservative: only charge when we're confident the
+ * caller is a machine. Signed intent (an agent that *declares* itself via the
+ * x402 handshake) is the strongest, cleanest signal — it sidesteps the UA
+ * arms race entirely.
+ */
+/**
+ * Obvious crawler/agent UA fragments. Extend freely — this is a weak signal.
+ * Verified against the operators' own published UA docs 2026-07-03 (Anthropic:
+ * ClaudeBot/Claude-User/Claude-SearchBot; OpenAI: GPTBot/ChatGPT-User/
+ * OAI-SearchBot/OAI-AdsBot). Dropped as undocumented: claude-web, anthropic-ai.
+ * Dropped as unmatchable: google-extended (a robots.txt-only token — Google
+ * documents NO UA string for it, so a UA fragment could never fire).
+ *
+ * Two kinds of machine read are charged here:
+ *   - training/bulk crawlers (gptbot, claudebot, ccbot, bytespider, amazonbot,
+ *     applebot-extended, meta-externalagent);
+ *   - user-triggered assistant fetches (chatgpt-user, claude-user,
+ *     perplexity-user, perplexitybot) — the citation moment itself. These UAs are
+ *     machine-only (no human browser carries them), so charging them cannot toll
+ *     a human; an x402-capable agent answers the 402 by paying, which is the
+ *     product working, not a wall.
+ *
+ * Note: pure search-indexer UAs (googlebot, bingbot, claude-searchbot,
+ * oai-searchbot, …) are deliberately NOT here. Tolling a search crawler silently
+ * deindexes the publisher — the opposite of what they want — so indexing reads
+ * free by default. A publisher frees additional crawlers (or re-affirms search
+ * ones) via `ClassifyPolicy.seoAllowlist`, or charges one via `chargeList`.
+ */
+const KNOWN_AGENT_UA = [
+    "gptbot",
+    "chatgpt-user",
+    "claudebot",
+    "claude-user",
+    "perplexitybot",
+    "perplexity-user",
+    "ccbot",
+    "bytespider",
+    "amazonbot",
+    "applebot-extended",
+    "meta-externalagent",
+    "python-requests",
+    "node-fetch",
+    "axios",
+    "curl",
+    "wget",
+    "langchain",
+];
+/**
+ * First fragment (case-insensitive substring) of `fragments` found in `ua`,
+ * else undefined. The one matching primitive the tri-state policy shares with
+ * the allowlist path — swap THIS for verified identity (Web Bot Auth) later.
+ */
+export function matchUaFragment(ua, fragments) {
+    if (!fragments?.length)
+        return undefined;
+    const lower = ua.toLowerCase();
+    return fragments.find((f) => f.length > 0 && lower.includes(f.toLowerCase()));
+}
+/**
+ * Classify a request as human or agent.
+ *
+ * TODO(you): implement the core heuristic. A starter is provided so the gate
+ * runs today, but this decision shapes the product — own it. Consider:
+ *
+ *   1. Declared intent first. `signals.hasPaymentHeader` or
+ *      `signals.declaredAgentId` => almost certainly an agent that WANTS to pay.
+ *      Treat as high-confidence agent. (Already wired below — keep it first.)
+ *   2. Known-bot UA match => agent, but lower confidence (UAs are spoofable and
+ *      churn). Decide how much weight to give a raw UA match.
+ *   3. Browser-shaped requests (Accept: text/html, sec-fetch-* headers,
+ *      Accept-Language present) => lean human. Decide your "looks like a real
+ *      browser" bar.
+ *   4. The ambiguous middle (empty UA, generic Accept, no browser headers).
+ *      THIS is the real design call: default-allow (favor humans, lose tolls) or
+ *      default-charge (capture tolls, risk paywalling a human)? Given the
+ *      asymmetry above, the starter defaults to HUMAN. Change it if you disagree
+ *      — and write down why.
+ *
+ * Return a Verdict with a `reason` (it surfaces in logs + the demo) and a
+ * `confidence` in [0,1].
+ *
+ * `policy` carries per-publisher overrides (the SEO allowlist); the single-tenant
+ * default passes none and behaves exactly as before.
+ */
+export function classify(signals, policy) {
+    // 1) Declared intent — strongest, spoof-proof-in-spirit signal. Leave first.
+    if (signals.hasPaymentHeader) {
+        return { kind: "agent", reason: "presented x402 payment header", confidence: 0.99 };
+    }
+    if (signals.declaredAgentId) {
+        return { kind: "agent", reason: `declared agent id ${signals.declaredAgentId}`, confidence: 0.95 };
+    }
+    // 1b) Verified identity (Web Bot Auth). A valid Ed25519 signature proves WHO
+    //     is calling, keyed to the operator's own directory — it outranks every
+    //     UA-derived signal in BOTH directions: a verified allow is the only
+    //     spoof-proof allowlist (UA rotation can't fake a signature), and a
+    //     verified agent is charged even behind a browser-shaped UA (rotation
+    //     can't dodge it). Same fragment vocabulary as the UA lists, matched
+    //     against the verified directory host — `allow: ["chatgpt.com"]` just
+    //     works, no new config shape. Publisher block runs in app.ts BEFORE
+    //     classification (block beats payment) and covers the verified id there.
+    if (signals.verifiedAgent) {
+        const va = signals.verifiedAgent.agent;
+        const allowed = matchUaFragment(va, policy?.seoAllowlist);
+        if (allowed) {
+            return { kind: "human", reason: `seo allowlist matched verified agent "${allowed}"`, confidence: 0.98 };
+        }
+        return { kind: "agent", reason: `verified web-bot-auth (${va})`, confidence: 0.98 };
+    }
+    const ua = signals.userAgent.toLowerCase();
+    // 2) SEO allowlist — verified discovery crawlers this publisher wants indexed
+    //    read FREE. Before the known-bot check so an allowlisted crawler is freed
+    //    even when its UA also matches a known-bot fragment.
+    const allowed = policy?.seoAllowlist?.find((frag) => ua.includes(frag.toLowerCase()));
+    if (allowed) {
+        return { kind: "human", reason: `seo allowlist matched "${allowed}"`, confidence: 0.9 };
+    }
+    // 2b) Publisher-charged crawlers — fragments the publisher explicitly tolls.
+    //     After allow (allow wins) and before the built-in list, so a publisher
+    //     can charge a crawler the conservative default would read as human.
+    const charged = matchUaFragment(signals.userAgent, policy?.chargeList);
+    if (charged) {
+        return { kind: "agent", reason: `publisher charge policy matched "${charged}"`, confidence: 0.8 };
+    }
+    // 3) Known-bot UA — weak, spoofable signal.
+    const hit = KNOWN_AGENT_UA.find((frag) => ua.includes(frag));
+    if (hit) {
+        return { kind: "agent", reason: `user-agent matched "${hit}"`, confidence: 0.8 };
+    }
+    // 4) Browser-shaped => human.
+    const looksBrowser = signals.accept.includes("text/html") || "sec-fetch-mode" in signals.headers;
+    if (looksBrowser) {
+        return { kind: "human", reason: "browser-shaped request", confidence: 0.85 };
+    }
+    // 5) Ambiguous middle. Starter favors humans (see asymmetry note).
+    return { kind: "human", reason: "ambiguous; defaulting to human (free)", confidence: 0.4 };
+}
+//# sourceMappingURL=agentDetect.js.map

package/dist/agentDetect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDetect.js","sourceRoot":"","sources":["../src/agentDetect.ts"],"names":[],"mappings":"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"}

package/dist/botAuth.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Web Bot Auth — RFC 9421 HTTP Message Signatures verifier, scoped to the
+ * web-bot-auth profile (draft-meunier-webbotauth-httpsig-protocol-00 +
+ * Cloudflare's deployed operational profile).
+ *
+ * Hand-rolled minimal structured-field subset by design: the full RFC 8941
+ * grammar is far more than the three headers need, and the one candidate npm
+ * package (web-bot-auth@0.1.x) is a 4-package unaudited tree. This module is
+ * self-contained on node:crypto.
+ */
+/** One covered component in the signature input: a name plus optional ;key=. */
+export interface CoveredComponent {
+    name: string;
+    key?: string;
+    /**
+     * The component identifier exactly as the signer serialized it (quoted name
+     * + params). Base lines reuse it verbatim so the base is byte-exact.
+     */
+    raw: string;
+}
+export interface SignatureInputEntry {
+    label: string;
+    components: CoveredComponent[];
+    params: {
+        created?: number;
+        expires?: number;
+        keyid?: string;
+        tag?: string;
+        alg?: string;
+        nonce?: string;
+    };
+    /**
+     * The member's verbatim SF text (everything after `label=`). Reused as the
+     * `@signature-params` serialization so the base is byte-exact with what the
+     * signer signed — no canonical re-serialization bugs.
+     */
+    rawMemberText: string;
+}
+/**
+ * Parse a `Signature-Input` header: an SF dictionary whose members are inner
+ * lists of covered components followed by the signature params. Returns null
+ * on any grammar trouble — the caller treats that as an invalid signature.
+ */
+export declare function parseSignatureInput(value: string): SignatureInputEntry[] | null;
+/**
+ * Parse a `Signature` header: an SF dictionary of byte sequences
+ * (label=:base64:). Returns null on grammar trouble.
+ */
+export declare function parseSignatureHeader(value: string): Map<string, Uint8Array> | null;
+/**
+ * Parse a `Signature-Agent` header into the directory URL.
+ *
+ * Accepts the CF operational profile's plain quoted string (what deployed
+ * signers send — CF explicitly REJECTS the dictionary form), tolerates the
+ * rev-00 dictionary form (first member wins), and normalizes a bare host to
+ * https. Returns null when neither shape parses or the URL is unusable.
+ */
+export declare function parseSignatureAgent(value: string): string | null;
+/** The request facts the base builder serializes components from. */
+export interface RequestFacts {
+    /** Host the request targeted (the `Host` header / URL authority). */
+    authority: string;
+    method: string;
+    path: string;
+    targetUri: string;
+    /** Lowercase header-name → raw value. */
+    headers: Record<string, string>;
+}
+/**
+ * Build the RFC 9421 signature base for one Signature-Input entry. Returns
+ * null when a covered component is unsupported or unresolvable — the caller
+ * treats that as an invalid signature. Supported: `@authority`, `@method`,
+ * `@path`, `@target-uri`, plain headers, and dictionary members via `;key=` —
+ * everything real web-bot-auth signers cover (CF profile minimum: @authority).
+ */
+export declare function buildSignatureBase(entry: SignatureInputEntry, facts: RequestFacts): string | null;
+/**
+ * RFC 7638 JWK thumbprint of an Ed25519 public key (the profile's keyid).
+ * Required members in lexicographic order: crv, kty, x.
+ */
+export declare function jwkThumbprint(x: string): string;
+/** Ed25519-verify `sig` over the UTF-8 `base` with a raw JWK x. Never throws. */
+export declare function verifyEd25519(base: string, sig: Uint8Array, x: string): boolean;
+/** keyid (RFC 7638 thumbprint) → raw Ed25519 JWK x, for one directory. */
+export type DirectoryKeys = Map<string, string>;
+/**
+ * LRU + TTL cache of fetched key directories. `null` is a NEGATIVE entry
+ * (directory unreachable/unusable) with its own shorter TTL, so a broken
+ * operator doesn't get hammered but recovers quickly. One fetch per operator
+ * per TTL — verification cost amortizes to zero on the hot path.
+ */
+export declare class DirectoryCache {
+    private readonly entries;
+    private readonly posTtlMs;
+    private readonly negTtlMs;
+    private readonly cap;
+    private readonly now;
+    constructor(opts?: {
+        posTtlMs?: number;
+        negTtlMs?: number;
+        cap?: number;
+        now?: () => number;
+    });
+    /** undefined = no usable entry; null = cached negative; Map = cached keys. */
+    get(url: string): DirectoryKeys | null | undefined;
+    set(url: string, keys: DirectoryKeys | null): void;
+}
+export interface BotAuthOptions {
+    fetchFn?: typeof fetch;
+    cache?: DirectoryCache;
+    /** epoch ms clock, injectable for tests. */
+    now?: () => number;
+    /**
+     * Permit http:// + localhost directories — LOCAL TEST FIXTURES ONLY (the
+     * signer walk serves its directory from a loopback port). Never in prod.
+     */
+    allowInsecureHttp?: boolean;
+    clockSkewSec?: number;
+}
+export interface VerifiedAgent {
+    /** The operator's directory host — the identity policy fragments match on. */
+    agent: string;
+    keyid: string;
+}
+export type BotAuthOutcome = 
+/** No web-bot-auth signature on the request (or signed for another protocol). */
+{
+    status: "absent";
+} | {
+    status: "verified";
+    agent: VerifiedAgent;
+}
+/** A signature was presented and is WRONG — masquerade telemetry. */
+ | {
+    status: "invalid";
+    reason: string;
+}
+/** Verifier/network trouble — fail open, treat as unsigned. */
+ | {
+    status: "unverified";
+    reason: string;
+};
+/**
+ * Verify a request's Web Bot Auth signature, end to end.
+ *
+ * Outcome discipline (the product decision, not just plumbing):
+ *  - absent     → no signature / not this protocol: the UA path proceeds as if
+ *                 this module didn't exist (byte-identical regression bar).
+ *  - verified   → cryptographic identity: classify() gets `verifiedAgent`.
+ *  - invalid    → a PRESENTED signature failed: still served via the UA path
+ *                 (fail-open), but flagged `sigInvalid` — masquerade telemetry.
+ *  - unverified → OUR side couldn't verify (directory down, network): fail
+ *                 open with no flag; a verifier outage must never block traffic.
+ *
+ * No nonce/replay cache in slice 1: the created/expires window (CF profile
+ * ~1 minute) bounds replay; a replayed signature buys the same 402 quote.
+ */
+export declare function verifyBotAuth(facts: RequestFacts, opts?: BotAuthOptions): Promise<BotAuthOutcome>;
+//# sourceMappingURL=botAuth.d.ts.map

package/dist/botAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"botAuth.d.ts","sourceRoot":"","sources":["../src/botAuth.ts"],"names":[],"mappings":"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"}